test(cli/e2e): add member management E2E suite (get/create/delete/set member)

28 tests covering all four member commands:

get member (10 tests)
  - list contains created member
  - required column headers (ID/NAME/EMAIL/ROLE/STATUS)
  - authenticated account appears as owner/active
  - JSON shape: data array with id/email/role/status fields
  - no ANSI codes in non-TTY output
  - pipe-friendly JSON output (ends with newline)
  - -o yaml returns valid YAML
  - -w flag overrides workspace
  - unauthenticated → exit 4

set member (7 tests)
  - promote normal → admin, verify via get member
  - demote admin → normal, verify via get member
  - --role owner rejected client-side (exit 2)
  - missing --role → usage error
  - missing member-id → usage error
  - non-existent UUID → server error
  - unauthenticated → exit 4

create member error paths (5 tests)
  - invalid role (superadmin) rejected client-side (exit 2)
  - --role owner rejected client-side (exit 2)
  - missing --email → usage error
  - missing --role → usage error
  - unauthenticated → exit 4

delete member (6 tests)
  - success: member removed from list
  - cannot delete self → server error
  - missing member-id → usage error
  - non-existent UUID → server error
  - -o json on error → structured error envelope
  - unauthenticated → exit 4

Data lifecycle: beforeAll invites two auto_test+<ts>@dify.ai
members; afterAll cleans them up. No extra env vars required.

.github/workflows/cli-edge.yml

@@ -0,0 +1,74 @@
+name: CLI Edge Publish
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'cli/**'
+      - 'packages/contracts/generated/api/openapi/**'
+  workflow_dispatch:
+
+concurrency:
+  group: difyctl-edge-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: build + publish edge to R2
+    runs-on: ${{ github.repository == 'langgenius/dify' && 'depot-ubuntu-24.04' || 'ubuntu-24.04' }}
+    if: vars.DIFYCTL_R2_BUCKET != ''
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./cli
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Enable cross-arch native prebuilds
+        working-directory: ./
+        run: cat cli/scripts/cross-arch.pnpm.yaml >> pnpm-workspace.yaml
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5 # v2.0.2
+        with:
+          bun-version-file: cli/.bun-version
+
+      - name: Compute edge version
+        id: ver
+        run: echo "version=$(node scripts/release-naming.mjs edge-version "$(git rev-parse --short HEAD)")" >> "$GITHUB_OUTPUT"
+
+      - name: Compile standalone binaries (all targets, all-or-nothing)
+        run: |
+          CLI_VERSION="${{ steps.ver.outputs.version }}" \
+          DIFYCTL_CHANNEL=edge \
+          DIFYCTL_COMMIT="$(git rev-parse HEAD)" \
+          DIFYCTL_BUILD_DATE="$(git log -1 --format=%cI HEAD)" \
+            pnpm build:bin
+
+      - name: Generate sha256 checksums
+        run: CLI_VERSION="${{ steps.ver.outputs.version }}" scripts/release-write-checksums.sh
+
+      - name: Smoke the runner-arch binary
+        run: ./dist/bin/difyctl-v${{ steps.ver.outputs.version }}-linux-x64 version
+
+      - name: Publish to R2
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.DIFYCTL_R2_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.DIFYCTL_R2_SECRET_ACCESS_KEY }}
+          AWS_DEFAULT_REGION: auto
+          AWS_REQUEST_CHECKSUM_CALCULATION: WHEN_REQUIRED
+          AWS_RESPONSE_CHECKSUM_VALIDATION: WHEN_REQUIRED
+          DIFYCTL_R2_S3_ENDPOINT: ${{ vars.DIFYCTL_R2_S3_ENDPOINT }}
+          DIFYCTL_R2_BUCKET: ${{ vars.DIFYCTL_R2_BUCKET }}
+          DIFYCTL_R2_PUBLIC_BASE: ${{ vars.DIFYCTL_R2_PUBLIC_BASE }}
+          DIFYCTL_COMMIT: ${{ github.sha }}
+        run: |
+          DIFYCTL_BUILD_DATE="$(git log -1 --format=%cI HEAD)" \
+            scripts/release-r2-publish.sh edge "${{ steps.ver.outputs.version }}"

.github/workflows/deploy-agent.yml

@@ -0,0 +1,28 @@
+name: Deploy Agent
+
+permissions:
+  contents: read
+
+on:
+  workflow_run:
+    workflows: ["Build and Push API & Web"]
+    branches:
+      - "deploy/agent"
+    types:
+      - completed
+
+jobs:
+  deploy:
+    runs-on: depot-ubuntu-24.04
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'deploy/agent'
+    steps:
+      - name: Deploy to server
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        with:
+          host: ${{ secrets.AGENT_SSH_HOST }}
+          username: ${{ secrets.SSH_USER }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          script: |
+            ${{ vars.SSH_SCRIPT_AGENT || secrets.SSH_SCRIPT_AGENT }}

.github/workflows/web-tests.yml

@@ -113,7 +113,7 @@ jobs:
         run: vp exec playwright install --with-deps chromium
 
       - name: Run dify-ui tests
-        run: vp test run --coverage --silent=passed-only
+        run: vp test run --project unit --coverage --silent=passed-only
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
@@ -123,3 +123,26 @@ jobs:
           flags: dify-ui
         env:
           CODECOV_TOKEN: ${{ env.CODECOV_TOKEN }}
+
+  dify-ui-storybook-test:
+    name: dify-ui Storybook Tests
+    runs-on: depot-ubuntu-24.04-4
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./packages/dify-ui
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Install Chromium for Browser Mode
+        run: vp exec playwright install --with-deps chromium
+
+      - name: Run dify-ui Storybook tests
+        run: vp run test:storybook

Makefile

@@ -157,7 +157,7 @@ build-web:
 
 build-api:
 	@echo "Building API Docker image: $(API_IMAGE):$(VERSION)..."
-	docker build -t $(API_IMAGE):$(VERSION) ./api
+	docker build -t $(API_IMAGE):$(VERSION) -f api/Dockerfile .
 	@echo "API Docker image built successfully: $(API_IMAGE):$(VERSION)"
 
 # Push Docker images

api/.env.example

@@ -774,3 +774,11 @@ EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS=2000
 ENABLE_HUMAN_INPUT_TIMEOUT_TASK=true
 # Human input timeout check interval in minutes
 HUMAN_INPUT_TIMEOUT_TASK_INTERVAL=1
+
+# Nacos remote settings source HTTP timeouts (seconds).
+# Bound how long requests to the Nacos endpoint wait before failing, so a slow or
+# unresponsive Nacos server cannot stall API startup or token refresh.
+# Read timeout for Nacos requests (default: 10.0)
+DIFY_ENV_NACOS_REQUEST_TIMEOUT=10.0
+# Connect timeout for Nacos requests (default: 3.0)
+DIFY_ENV_NACOS_CONNECT_TIMEOUT=3.0

api/Dockerfile.dockerignore

@@ -8,18 +8,30 @@
 !dify-agent/src/
 !dify-agent/src/**
 
-api/.venv
-api/.venv/**
-api/.env
-api/*.env.*
-api/.idea
-api/.mypy_cache
-api/.ruff_cache
-api/storage/generate_files/*
-api/storage/privkeys/*
-api/storage/tools/*
-api/storage/upload_files/*
-api/logs
-api/*.log*
+# Environment configuration and example
+.env
+*.env.*
+
+# Python related files
 **/__pycache__
 **/*.pyc
+**/.venv/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.import_linter_cache/
+**/.pytest_cache/
+**/.hypothesis/
+
+
+# Upload files and logs
+api/storage/**
+api/logs/
+api/*.log*
+
+# Tests
+api/tests
+
+
+# Editor configuration
+**/.vscode/
+**/.idea/

api/clients/agent_backend/request_builder.py

@@ -19,6 +19,7 @@ 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
+from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
 from dify_agent.layers.dify_plugin import (
     DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
     DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
@@ -26,6 +27,7 @@ from dify_agent.layers.dify_plugin import (
     DifyPluginLLMLayerConfig,
     DifyPluginToolsLayerConfig,
 )
+from dify_agent.layers.drive import DIFY_DRIVE_LAYER_TYPE_ID, DifyDriveLayerConfig
 from dify_agent.layers.execution_context import (
     DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
     DifyExecutionContextLayerConfig,
@@ -37,6 +39,7 @@ from dify_agent.protocol import (
     DIFY_AGENT_MODEL_LAYER_ID,
     DIFY_AGENT_OUTPUT_LAYER_ID,
     CreateRunRequest,
+    DeferredToolResultsPayload,
     LayerExitSignals,
     RunComposition,
     RunLayerSpec,
@@ -50,7 +53,9 @@ 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_DRIVE_LAYER_ID = "drive"
 DIFY_PLUGIN_TOOLS_LAYER_ID = "tools"
+DIFY_ASK_HUMAN_LAYER_ID = "ask_human"
 DIFY_SHELL_LAYER_ID = "shell"
 
 
@@ -134,11 +139,21 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
     idempotency_key: str | None = None
     output: AgentBackendOutputConfig | None = None
     tools: DifyPluginToolsLayerConfig | None = None
+    # Drive Skills & Files declaration (dify.drive) — an index the agent pulls
+    # through the back proxy, never inline content; see AGENT_DRIVE_MANIFEST_ENABLED.
+    drive_config: DifyDriveLayerConfig | None = None
+    # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
+    # 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 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
+    # Human tool results fed back into a continuation run after a HITL submission
+    # (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)
@@ -170,11 +185,20 @@ class AgentBackendAgentAppRunInput(BaseModel):
     idempotency_key: str | None = None
     output: AgentBackendOutputConfig | None = None
     tools: DifyPluginToolsLayerConfig | None = None
+    # Drive Skills & Files declaration (dify.drive) — an index the agent pulls
+    # through the back proxy, never inline content; see AGENT_DRIVE_MANIFEST_ENABLED.
+    drive_config: DifyDriveLayerConfig | None = None
+    # 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 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
+    # Human tool results fed back into a continuation run after a HITL submission
+    # (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)
@@ -228,6 +252,18 @@ class AgentBackendRunRequestBuilder:
             ]
         )
 
+        if run_input.drive_config is not None:
+            # Drive Skills & Files declaration (dify.drive): a config-only index;
+            # the agent pulls listed entries through the back proxy by drive_ref.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_DRIVE_LAYER_ID,
+                    type=DIFY_DRIVE_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.drive_config,
+                )
+            )
+
         if run_input.include_history:
             layers.append(
                 RunLayerSpec(
@@ -264,6 +300,19 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.ask_human_config is not None:
+            # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends
+            # the run with a deferred_tool_call; the caller pauses (workflow HITL) and
+            # later resumes with deferred_tool_results. Needs the history layer above.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_ASK_HUMAN_LAYER_ID,
+                    type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.ask_human_config,
+                )
+            )
+
         if run_input.include_shell:
             # Sandboxed bash workspace (dify.shell). Depends on execution_context so
             # the agent server can mint per-command Agent Stub env (back proxy);
@@ -298,6 +347,7 @@ class AgentBackendRunRequestBuilder:
             idempotency_key=run_input.idempotency_key,
             metadata=run_input.metadata,
             session_snapshot=run_input.session_snapshot,
+            deferred_tool_results=run_input.deferred_tool_results,
             on_exit=LayerExitSignals(
                 default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
             ),
@@ -383,6 +433,18 @@ class AgentBackendRunRequestBuilder:
             ]
         )
 
+        if run_input.drive_config is not None:
+            # Drive Skills & Files declaration (dify.drive): a config-only index;
+            # the agent pulls listed entries through the back proxy by drive_ref.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_DRIVE_LAYER_ID,
+                    type=DIFY_DRIVE_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.drive_config,
+                )
+            )
+
         if run_input.include_history:
             layers.append(
                 RunLayerSpec(
@@ -421,6 +483,19 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.ask_human_config is not None:
+            # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends
+            # the run with a deferred_tool_call; the caller pauses (workflow HITL) and
+            # later resumes with deferred_tool_results. Needs the history layer above.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_ASK_HUMAN_LAYER_ID,
+                    type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.ask_human_config,
+                )
+            )
+
         if run_input.include_shell:
             # Sandboxed bash workspace (dify.shell). Depends on execution_context so
             # the agent server can mint per-command Agent Stub env (back proxy);
@@ -455,6 +530,7 @@ class AgentBackendRunRequestBuilder:
             idempotency_key=run_input.idempotency_key,
             metadata=run_input.metadata,
             session_snapshot=run_input.session_snapshot,
+            deferred_tool_results=run_input.deferred_tool_results,
             on_exit=LayerExitSignals(
                 default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
             ),

api/commands/__init__.py

@@ -11,6 +11,7 @@ from .data_migration import (
     migration_data_wizard,
 )
 from .plugin import (
+    backfill_plugin_auto_upgrade,
     extract_plugins,
     extract_unique_plugins,
     install_plugins,
@@ -49,6 +50,7 @@ from .vector import (
 __all__ = [
     "add_qdrant_index",
     "archive_workflow_runs",
+    "backfill_plugin_auto_upgrade",
     "clean_expired_messages",
     "clean_workflow_runs",
     "cleanup_orphaned_draft_variables",

api/commands/plugin.py

@@ -1,10 +1,11 @@
 import json
 import logging
+import time
 from typing import Any, cast
 
 import click
 from pydantic import TypeAdapter
-from sqlalchemy import delete, select
+from sqlalchemy import delete, func, select
 from sqlalchemy.engine import CursorResult
 
 from configs import dify_config
@@ -15,11 +16,13 @@ from core.plugin.plugin_service import PluginService
 from core.tools.utils.system_encryption import encrypt_system_params
 from extensions.ext_database import db
 from models import Tenant
+from models.account import TenantPluginAutoUpgradeStrategy
 from models.oauth import DatasourceOauthParamConfig, DatasourceProvider
 from models.provider_ids import DatasourceProviderID, ToolProviderID
 from models.source import DataSourceApiKeyAuthBinding, DataSourceOauthBinding
 from models.tools import ToolOAuthSystemClient
 from services.plugin.data_migration import PluginDataMigration
+from services.plugin.plugin_auto_upgrade_service import PluginAutoUpgradeService
 from services.plugin.plugin_migration import PluginMigration
 
 logger = logging.getLogger(__name__)
@@ -402,6 +405,110 @@ def migrate_data_for_plugin():
     click.echo(click.style("Migrate data for plugin completed.", fg="green"))
 
 
+def _candidate_auto_upgrade_strategy_tenant_ids_stmt(limit: int | None = None):
+    category_count = len(TenantPluginAutoUpgradeStrategy.PluginCategory)
+    stmt = (
+        select(TenantPluginAutoUpgradeStrategy.tenant_id)
+        .group_by(TenantPluginAutoUpgradeStrategy.tenant_id)
+        .having(func.count(func.distinct(TenantPluginAutoUpgradeStrategy.category)) < category_count)
+        .order_by(TenantPluginAutoUpgradeStrategy.tenant_id)
+    )
+
+    if limit is not None:
+        stmt = stmt.limit(limit)
+
+    return stmt
+
+
+def _count_auto_upgrade_strategy_tenant_ids(limit: int | None) -> int:
+    candidate_stmt = _candidate_auto_upgrade_strategy_tenant_ids_stmt(limit).subquery()
+    return db.session.scalar(select(func.count()).select_from(candidate_stmt)) or 0
+
+
+def _iter_auto_upgrade_strategy_tenant_ids(limit: int | None):
+    stmt = _candidate_auto_upgrade_strategy_tenant_ids_stmt(limit).execution_options(yield_per=1000)
+    yield from db.session.scalars(stmt)
+
+
+@click.command(
+    "backfill-plugin-auto-upgrade",
+    help="Backfill category-scoped plugin auto-upgrade strategies and normalize plugin lists.",
+)
+@click.option("--tenant-id", multiple=True, help="Tenant ID to backfill. Can be passed multiple times.")
+@click.option("--limit", type=int, default=None, help="Maximum number of candidate tenants to process.")
+@click.option("--batch-size", type=int, default=500, show_default=True, help="Progress reporting batch size.")
+@click.option("--dry-run", is_flag=True, help="Only print candidate tenant count.")
+def backfill_plugin_auto_upgrade(
+    tenant_id: tuple[str, ...],
+    limit: int | None,
+    batch_size: int,
+    dry_run: bool,
+):
+    """
+    Backfill historical auto-upgrade strategies after the category column exists.
+
+    Missing category rows are created from the tenant's tool/default row. Pure default
+    strategies become latest for model plugins and fix-only for all other categories.
+    Tenants with include/exclude plugin IDs are split
+    by installed plugin category using plugin daemon metadata.
+    """
+    start_at = time.perf_counter()
+    candidate_count = len(tenant_id) if tenant_id else _count_auto_upgrade_strategy_tenant_ids(limit)
+    click.echo(click.style(f"Found {candidate_count} candidate tenants.", fg="yellow"))
+
+    if dry_run:
+        elapsed = time.perf_counter() - start_at
+        click.echo(click.style(f"Dry run completed. elapsed={elapsed:.2f}s", fg="green"))
+        return
+
+    tenant_ids = list(tenant_id) if tenant_id else _iter_auto_upgrade_strategy_tenant_ids(limit)
+
+    backfilled_count = 0
+    created_count = 0
+    normalized_count = 0
+    skipped_count = 0
+    failed_count = 0
+    for index, current_tenant_id in enumerate(tenant_ids, start=1):
+        try:
+            result = PluginAutoUpgradeService.backfill_strategy_categories(
+                current_tenant_id,
+            )
+        except Exception as e:
+            failed_count += 1
+            click.echo(click.style(f"Failed tenant {current_tenant_id}: {str(e)}", fg="red"))
+            continue
+
+        if result.created_count > 0:
+            backfilled_count += 1
+            created_count += result.created_count
+        elif not result.normalized:
+            skipped_count += 1
+        if result.normalized:
+            normalized_count += 1
+
+        if batch_size > 0 and index % batch_size == 0:
+            click.echo(
+                click.style(
+                    f"Processed {index}/{candidate_count} tenants. "
+                    f"backfilled={backfilled_count}, created_rows={created_count}, "
+                    f"normalized={normalized_count}, skipped={skipped_count}, failed={failed_count}, "
+                    f"elapsed={time.perf_counter() - start_at:.2f}s",
+                    fg="yellow",
+                )
+            )
+
+    elapsed = time.perf_counter() - start_at
+    click.echo(
+        click.style(
+            f"Backfill plugin auto-upgrade strategy categories completed. "
+            f"backfilled={backfilled_count}, created_rows={created_count}, "
+            f"normalized={normalized_count}, skipped={skipped_count}, failed={failed_count}, "
+            f"elapsed={elapsed:.2f}s",
+            fg="green",
+        )
+    )
+
+
 @click.command("extract-plugins", help="Extract plugins.")
 @click.option("--output_file", prompt=True, help="The file to store the extracted plugins.", default="plugins.jsonl")
 @click.option("--workers", prompt=True, help="The number of workers to extract plugins.", default=10)

api/configs/enterprise/__init__.py

@@ -16,7 +16,7 @@ class EnterpriseFeatureConfig(BaseSettings):
 
     CAN_REPLACE_LOGO: bool = Field(
         description="Allow customization of the enterprise logo.",
-        default=False,
+        default=True,
     )
 
     ENTERPRISE_REQUEST_TIMEOUT: int = Field(

api/configs/extra/agent_backend_config.py

@@ -31,3 +31,13 @@ class AgentBackendConfig(BaseSettings):
         ),
         default=False,
     )
+
+    AGENT_DRIVE_MANIFEST_ENABLED: bool = Field(
+        description=(
+            "Inject the dify.drive layer (Skills & Files drive manifest declaration) "
+            "into Agent runs. The declaration is an index only — the agent backend "
+            "pulls the actual SKILL.md / files through the back proxy. Keep it off "
+            "until the agent backend registers the dify.drive layer type."
+        ),
+        default=False,
+    )

api/configs/remote_settings_sources/nacos/http_request.py

@@ -20,6 +20,12 @@ class NacosHttpClient:
         self.token: str | None = None
         self.token_ttl = 18000
         self.token_expire_time: float = 0
+        # Bounded timeouts so a slow or unresponsive Nacos server cannot hang the API
+        # service indefinitely during startup or token refresh.
+        self.timeout = httpx.Timeout(
+            float(os.getenv("DIFY_ENV_NACOS_REQUEST_TIMEOUT", "10.0")),
+            connect=float(os.getenv("DIFY_ENV_NACOS_CONNECT_TIMEOUT", "3.0")),
+        )
 
     def http_request(
         self, url: str, method: str = "GET", headers: dict[str, str] | None = None, params: dict[str, str] | None = None
@@ -28,12 +34,17 @@ class NacosHttpClient:
             headers = {}
         if params is None:
             params = {}
+        full_url = "http://" + self.server + url
         try:
             self._inject_auth_info(headers, params)
-            response = httpx.request(method, url="http://" + self.server + url, headers=headers, params=params)
+            response = httpx.request(method, url=full_url, headers=headers, params=params, timeout=self.timeout)
             response.raise_for_status()
             return response.text
+        except httpx.TimeoutException as e:
+            logger.warning("Request to Nacos timed out (url=%s, timeout=%s): %s", full_url, self.timeout, e)
+            return f"Request to Nacos timed out: {e}"
         except httpx.RequestError as e:
+            logger.warning("Request to Nacos failed (url=%s): %s", full_url, e)
             return f"Request to Nacos failed: {e}"
 
     def _inject_auth_info(self, headers: dict[str, str], params: dict[str, str], module: str = "config") -> None:
@@ -78,13 +89,16 @@ class NacosHttpClient:
         params = {"username": self.username, "password": self.password}
         url = "http://" + self.server + "/nacos/v1/auth/login"
         try:
-            resp = httpx.request("POST", url, headers=None, params=params)
+            resp = httpx.request("POST", url, headers=None, params=params, timeout=self.timeout)
             resp.raise_for_status()
             response_data = resp.json()
             self.token = response_data.get("accessToken")
             self.token_ttl = response_data.get("tokenTtl", 18000)
             self.token_expire_time = current_time + self.token_ttl - 10
             return self.token
+        except httpx.TimeoutException:
+            logger.exception("[get-access-token] request to Nacos timed out (url=%s, timeout=%s)", url, self.timeout)
+            raise
         except Exception:
             logger.exception("[get-access-token] exception occur")
             raise

api/controllers/common/wraps.py

@@ -0,0 +1,30 @@
+from collections.abc import Callable
+from functools import wraps
+
+from core.rbac import RBACPermission, RBACResourceScope
+
+__all__ = ["RBACPermission", "RBACResourceScope", "rbac_permission_required"]
+
+
+def rbac_permission_required[**P, R](
+    resource_type: RBACResourceScope,
+    scene: RBACPermission,
+    *,
+    resource_required: bool = True,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Check enterprise RBAC permissions for the current user.
+
+    Args:
+        resource_type: The :class:`RBACResourceScope` member (app/dataset/workspace).
+        scene: The :class:`RBACPermission` permission point.
+        resource_required: Whether a concrete resource ID is required.
+    """
+
+    def decorator(view: Callable[P, R]) -> Callable[P, R]:
+        @wraps(view)
+        def decorated(*args: P.args, **kwargs: P.kwargs) -> R:
+            return view(*args, **kwargs)
+
+        return decorated
+
+    return decorator

api/controllers/console/__init__.py

@@ -54,6 +54,7 @@ from .app import (
     agent_app_access,
     agent_app_feature,
     agent_app_sandbox,
+    agent_drive_inspector,
     annotation,
     app,
     audio,
@@ -155,6 +156,7 @@ __all__ = [
     "agent_app_feature",
     "agent_app_sandbox",
     "agent_composer",
+    "agent_drive_inspector",
     "agent_providers",
     "agent_roster",
     "annotation",

api/controllers/console/agent/app_helpers.py

@@ -0,0 +1,10 @@
+from uuid import UUID
+
+from extensions.ext_database import db
+from models.model import App
+from services.agent.roster_service import AgentRosterService
+
+
+def resolve_agent_app_model(*, tenant_id: str, agent_id: UUID) -> App:
+    """Resolve the hidden Agent App backing an Agent Console resource."""
+    return AgentRosterService(db.session).get_agent_app_model(tenant_id=tenant_id, agent_id=str(agent_id))

api/controllers/console/agent/composer.py

@@ -1,7 +1,10 @@
+from uuid import UUID
+
 from flask_restx import Resource
 
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
     account_initialization_required,
@@ -35,6 +38,10 @@ register_response_schema_models(
 )
 
 
+def _resolve_agent_app_id(*, tenant_id: str, agent_id: UUID) -> str:
+    return resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id).id
+
+
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer")
 class WorkflowAgentComposerApi(Resource):
     @console_ns.response(
@@ -94,7 +101,13 @@ class WorkflowAgentComposerValidateApi(Resource):
     def post(self, tenant_id: str, app_model: App, node_id: str):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_save_payload(payload)
-        findings = AgentComposerService.collect_validation_findings(tenant_id=tenant_id, payload=payload)
+        findings = AgentComposerService.collect_validation_findings(
+            tenant_id=tenant_id,
+            payload=payload,
+            agent_id=AgentComposerService.resolve_workflow_node_agent_id(
+                tenant_id=tenant_id, app_id=app_model.id, node_id=node_id
+            ),
+        )
         return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": [], **findings})
 
 
@@ -170,18 +183,18 @@ class WorkflowAgentComposerSaveToRosterApi(Resource):
         )
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-composer")
-class AgentAppComposerApi(Resource):
+@console_ns.route("/agent/<uuid:agent_id>/composer")
+class AgentComposerApi(Resource):
     @console_ns.response(200, "Agent app composer state", console_ns.models[AgentAppComposerResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_tenant_id
-    def get(self, tenant_id: str, app_model: App):
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_id = _resolve_agent_app_id(tenant_id=tenant_id, agent_id=agent_id)
         return dump_response(
             AgentAppComposerResponse,
-            AgentComposerService.load_agent_app_composer(tenant_id=tenant_id, app_id=app_model.id),
+            AgentComposerService.load_agent_app_composer(tenant_id=tenant_id, app_id=app_id),
         )
 
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
@@ -190,24 +203,24 @@ class AgentAppComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_user_id
     @with_current_tenant_id
-    def put(self, tenant_id: str, account_id: str, app_model: App):
+    def put(self, tenant_id: str, account_id: str, agent_id: UUID):
+        app_id = _resolve_agent_app_id(tenant_id=tenant_id, agent_id=agent_id)
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         return dump_response(
             AgentAppComposerResponse,
             AgentComposerService.save_agent_app_composer(
                 tenant_id=tenant_id,
-                app_id=app_model.id,
+                app_id=app_id,
                 account_id=account_id,
                 payload=payload,
             ),
         )
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-composer/validate")
-class AgentAppComposerValidateApi(Resource):
+@console_ns.route("/agent/<uuid:agent_id>/composer/validate")
+class AgentComposerValidateApi(Resource):
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
     @console_ns.response(
         200, "Agent app composer validation result", console_ns.models[AgentComposerValidateResponse.__name__]
@@ -215,32 +228,36 @@ class AgentAppComposerValidateApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_tenant_id
-    def post(self, tenant_id: str, app_model: App):
+    def post(self, tenant_id: str, agent_id: UUID):
+        _resolve_agent_app_id(tenant_id=tenant_id, agent_id=agent_id)
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_save_payload(payload)
-        findings = AgentComposerService.collect_validation_findings(tenant_id=tenant_id, payload=payload)
+        findings = AgentComposerService.collect_validation_findings(
+            tenant_id=tenant_id,
+            payload=payload,
+            agent_id=str(agent_id),
+        )
         return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": [], **findings})
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-composer/candidates")
-class AgentAppComposerCandidatesApi(Resource):
+@console_ns.route("/agent/<uuid:agent_id>/composer/candidates")
+class AgentComposerCandidatesApi(Resource):
     @console_ns.response(
         200, "Agent app composer candidates", console_ns.models[AgentComposerCandidatesResponse.__name__]
     )
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_user_id
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user_id: str, app_model: App):
+    def get(self, tenant_id: str, current_user_id: str, agent_id: UUID):
+        app_id = _resolve_agent_app_id(tenant_id=tenant_id, agent_id=agent_id)
         return dump_response(
             AgentComposerCandidatesResponse,
             AgentComposerService.get_agent_app_candidates(
                 tenant_id=tenant_id,
-                app_id=app_model.id,
+                app_id=app_id,
                 user_id=current_user_id,
             ),
         )

api/controllers/console/agent/roster.py

@@ -6,12 +6,21 @@ from pydantic import BaseModel, Field
 
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
+from controllers.console.app.app import (
+    AppDetailWithSite,
+    AppListQuery,
+    AppPagination,
+    UpdateAppPayload,
+    _normalize_app_list_query_args,
+)
 from controllers.console.wraps import (
     account_initialization_required,
+    cloud_edition_billing_resource_check,
     edit_permission_required,
+    enterprise_license_required,
     setup_required,
     with_current_tenant_id,
-    with_current_user_id,
+    with_current_user,
 )
 from extensions.ext_database import db
 from fields.agent_fields import (
@@ -20,12 +29,17 @@ from fields.agent_fields import (
     AgentInviteOptionsResponse,
     AgentPublishedReferenceResponse,
     AgentRosterListResponse,
-    AgentRosterResponse,
 )
 from libs.helper import dump_response
 from libs.login import login_required
+from models import Account
+from models.model import IconType
+from services.agent.errors import AgentNotFoundError
 from services.agent.roster_service import AgentRosterService
-from services.entities.agent_entities import RosterAgentCreatePayload, RosterAgentUpdatePayload, RosterListQuery
+from services.app_service import AppListParams, AppService, CreateAppParams
+from services.enterprise.enterprise_service import EnterpriseService
+from services.entities.agent_entities import RosterListQuery
+from services.feature_service import FeatureService
 
 
 class AgentInviteOptionsQuery(RosterListQuery):
@@ -36,22 +50,38 @@ class AgentIdPath(BaseModel):
     agent_id: str
 
 
+class AgentAppCreatePayload(BaseModel):
+    name: str = Field(..., min_length=1, description="Agent name")
+    description: str | None = Field(default=None, description="Agent description (max 400 chars)", max_length=400)
+    role: str = Field(default="", description="Agent role", max_length=255)
+    icon_type: IconType | None = Field(default=None, description="Icon type")
+    icon: str | None = Field(default=None, description="Icon")
+    icon_background: str | None = Field(default=None, description="Icon background color")
+
+
+class AgentAppUpdatePayload(UpdateAppPayload):
+    role: str | None = Field(default=None, description="Agent role", max_length=255)
+
+
 register_schema_models(
     console_ns,
+    AgentAppCreatePayload,
+    AgentAppUpdatePayload,
     AgentInviteOptionsQuery,
     AgentIdPath,
-    RosterAgentCreatePayload,
-    RosterAgentUpdatePayload,
+    AppListQuery,
+    UpdateAppPayload,
     RosterListQuery,
 )
 register_response_schema_models(
     console_ns,
+    AppDetailWithSite,
+    AppPagination,
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
     AgentInviteOptionsResponse,
     AgentPublishedReferenceResponse,
     AgentRosterListResponse,
-    AgentRosterResponse,
 )
 
 
@@ -59,42 +89,152 @@ def _agent_roster_service() -> AgentRosterService:
     return AgentRosterService(db.session)
 
 
-@console_ns.route("/agents")
-class AgentRosterListApi(Resource):
-    @console_ns.doc(params=query_params_from_model(RosterListQuery))
-    @console_ns.response(200, "Agent roster list", console_ns.models[AgentRosterListResponse.__name__])
+def _serialize_agent_app_detail(app_model) -> dict:
+    app_model = AppService().get_app(app_model)
+    if FeatureService.get_system_features().webapp_auth.enabled:
+        app_setting = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_id=str(app_model.id))
+        app_model.access_mode = app_setting.access_mode  # type: ignore[attr-defined]
+
+    agent = _agent_roster_service().get_app_backing_agent(tenant_id=app_model.tenant_id, app_id=app_model.id)
+    if not agent:
+        raise AgentNotFoundError()
+    payload = AppDetailWithSite.model_validate(app_model, from_attributes=True).model_dump(mode="json")
+    payload.pop("bound_agent_id", None)
+    payload["app_id"] = str(app_model.id)
+    payload["id"] = agent.id
+    payload["role"] = agent.role or ""
+    return payload
+
+
+def _serialize_agent_app_pagination(app_pagination, *, tenant_id: str) -> dict:
+    app_ids = [str(app.id) for app in app_pagination.items]
+    agents_by_app_id = _agent_roster_service().load_app_backing_agents_by_app_id(
+        tenant_id=tenant_id,
+        app_ids=app_ids,
+    )
+    payload = AppPagination.model_validate(app_pagination, from_attributes=True).model_dump(mode="json")
+    for item in payload["data"]:
+        app_id = item["id"]
+        item.pop("bound_agent_id", None)
+        agent = agents_by_app_id.get(app_id)
+        if agent:
+            item["app_id"] = app_id
+            item["id"] = agent.id
+            item["role"] = agent.role or ""
+    return payload
+
+
+def _resolve_agent_app_model(*, tenant_id: str, agent_id: UUID):
+    return _agent_roster_service().get_agent_app_model(tenant_id=tenant_id, agent_id=str(agent_id))
+
+
+@console_ns.route("/agent")
+class AgentAppListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AppListQuery))
+    @console_ns.response(200, "Agent app list", console_ns.models[AppPagination.__name__])
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str):
-        query = RosterListQuery.model_validate(request.args.to_dict(flat=True))
-        return dump_response(
-            AgentRosterListResponse,
-            _agent_roster_service().list_roster_agents(
-                tenant_id=tenant_id, page=query.page, limit=query.limit, keyword=query.keyword
-            ),
+    def get(self, current_tenant_id: str, current_user: Account):
+        args = AppListQuery.model_validate(_normalize_app_list_query_args(request.args))
+        params = AppListParams(
+            page=args.page,
+            limit=args.limit,
+            mode="agent",
+            name=args.name,
+            tag_ids=args.tag_ids,
+            creator_ids=args.creator_ids,
+            is_created_by_me=args.is_created_by_me,
+            status="normal",
         )
 
-    @console_ns.expect(console_ns.models[RosterAgentCreatePayload.__name__])
-    @console_ns.response(201, "Agent created", console_ns.models[AgentRosterResponse.__name__])
+        app_pagination = AppService().get_paginate_apps(current_user.id, current_tenant_id, params)
+        if app_pagination is None:
+            empty = AppPagination(page=args.page, limit=args.limit, total=0, has_more=False, data=[])
+            return empty.model_dump(mode="json")
+
+        return _serialize_agent_app_pagination(app_pagination, tenant_id=current_tenant_id)
+
+    @console_ns.expect(console_ns.models[AgentAppCreatePayload.__name__])
+    @console_ns.response(201, "Agent app created successfully", console_ns.models[AppDetailWithSite.__name__])
+    @console_ns.response(403, "Insufficient permissions")
+    @console_ns.response(400, "Invalid request parameters")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @cloud_edition_billing_resource_check("apps")
+    @edit_permission_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account):
+        args = AgentAppCreatePayload.model_validate(console_ns.payload)
+        params = CreateAppParams(
+            name=args.name,
+            description=args.description,
+            mode="agent",
+            agent_role=args.role,
+            icon_type=args.icon_type,
+            icon=args.icon,
+            icon_background=args.icon_background,
+        )
+
+        app = AppService().create_app(current_tenant_id, params, current_user)
+        return _serialize_agent_app_detail(app), 201
+
+
+@console_ns.route("/agent/<uuid:agent_id>")
+class AgentAppApi(Resource):
+    @console_ns.response(200, "Agent app detail", console_ns.models[AppDetailWithSite.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _serialize_agent_app_detail(app_model)
+
+    @console_ns.expect(console_ns.models[AgentAppUpdatePayload.__name__])
+    @console_ns.response(200, "Agent app updated successfully", console_ns.models[AppDetailWithSite.__name__])
+    @console_ns.response(403, "Insufficient permissions")
+    @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @with_current_user_id
     @with_current_tenant_id
-    def post(self, tenant_id: str, account_id: str):
-        payload = RosterAgentCreatePayload.model_validate(console_ns.payload or {})
-        service = _agent_roster_service()
-        agent = service.create_roster_agent(tenant_id=tenant_id, account_id=account_id, payload=payload)
-        return dump_response(
-            AgentRosterResponse,
-            service.get_roster_agent_detail(tenant_id=tenant_id, agent_id=agent.id),
-        ), 201
+    def put(self, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        args = AgentAppUpdatePayload.model_validate(console_ns.payload)
+        args_dict: AppService.ArgsDict = {
+            "name": args.name,
+            "description": args.description or "",
+            "icon_type": args.icon_type,
+            "icon": args.icon or "",
+            "icon_background": args.icon_background or "",
+            "use_icon_as_answer_icon": args.use_icon_as_answer_icon or False,
+            "max_active_requests": args.max_active_requests or 0,
+            "role": args.role,
+        }
+        updated = AppService().update_app(app_model, args_dict)
+        return _serialize_agent_app_detail(updated)
+
+    @console_ns.response(204, "Agent app deleted successfully")
+    @console_ns.response(403, "Insufficient permissions")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_tenant_id
+    def delete(self, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        AppService().delete_app(app_model)
+        return "", 204
 
 
-@console_ns.route("/agents/invite-options")
+@console_ns.route("/agent/invite-options")
 class AgentInviteOptionsApi(Resource):
     @console_ns.doc(params=query_params_from_model(AgentInviteOptionsQuery))
     @console_ns.response(200, "Agent invite options", console_ns.models[AgentInviteOptionsResponse.__name__])
@@ -116,49 +256,7 @@ class AgentInviteOptionsApi(Resource):
         )
 
 
-@console_ns.route("/agents/<uuid:agent_id>")
-class AgentRosterDetailApi(Resource):
-    @console_ns.response(200, "Agent detail", console_ns.models[AgentRosterResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
-        return dump_response(
-            AgentRosterResponse,
-            _agent_roster_service().get_roster_agent_detail(tenant_id=tenant_id, agent_id=str(agent_id)),
-        )
-
-    @console_ns.expect(console_ns.models[RosterAgentUpdatePayload.__name__])
-    @console_ns.response(200, "Agent updated", console_ns.models[AgentRosterResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @edit_permission_required
-    @with_current_user_id
-    @with_current_tenant_id
-    def patch(self, tenant_id: str, account_id: str, agent_id: UUID):
-        payload = RosterAgentUpdatePayload.model_validate(console_ns.payload or {})
-        return dump_response(
-            AgentRosterResponse,
-            _agent_roster_service().update_roster_agent(
-                tenant_id=tenant_id, agent_id=str(agent_id), account_id=account_id, payload=payload
-            ),
-        )
-
-    @console_ns.response(204, "Agent archived")
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @edit_permission_required
-    @with_current_user_id
-    @with_current_tenant_id
-    def delete(self, tenant_id: str, account_id: str, agent_id: UUID):
-        _agent_roster_service().archive_roster_agent(tenant_id=tenant_id, agent_id=str(agent_id), account_id=account_id)
-        return "", 204
-
-
-@console_ns.route("/agents/<uuid:agent_id>/versions")
+@console_ns.route("/agent/<uuid:agent_id>/versions")
 class AgentRosterVersionsApi(Resource):
     @console_ns.response(200, "Agent versions", console_ns.models[AgentConfigSnapshotListResponse.__name__])
     @setup_required
@@ -172,7 +270,7 @@ class AgentRosterVersionsApi(Resource):
         )
 
 
-@console_ns.route("/agents/<uuid:agent_id>/versions/<uuid:version_id>")
+@console_ns.route("/agent/<uuid:agent_id>/versions/<uuid:version_id>")
 class AgentRosterVersionDetailApi(Resource):
     @console_ns.response(200, "Agent version detail", console_ns.models[AgentConfigSnapshotDetailResponse.__name__])
     @setup_required

api/controllers/console/app/agent.py

@@ -1,25 +1,56 @@
+import logging
 from typing import Any
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel, Field, RootModel, field_validator
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import select
 
-from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
+from controllers.common.schema import (
+    query_params_from_model,
+    query_params_from_request,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
+from controllers.console.wraps import (
+    account_initialization_required,
+    setup_required,
+    with_current_tenant_id,
+    with_current_user,
+)
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.helper import uuid_value
 from libs.login import login_required
 from models import Account
-from models.model import App, AppMode
-from services.agent.skill_package_service import SkillPackageError, SkillPackageService
+from models.agent_config_entities import AgentFileRefConfig, AgentSkillRefConfig
+from models.model import App, AppMode, UploadFile
+from services.agent.composer_service import AgentComposerService
+from services.agent.skill_package_service import SkillManifest, SkillPackageError, SkillPackageService
 from services.agent.skill_standardize_service import SkillStandardizeService
-from services.agent_drive_service import AgentDriveError
+from services.agent.skill_tool_inference_service import (
+    SkillToolInferenceError,
+    SkillToolInferenceResult,
+    SkillToolInferenceService,
+)
+from services.agent_drive_service import (
+    AgentDriveError,
+    AgentDriveService,
+    DriveCommitItem,
+    DriveFileRef,
+    normalize_drive_key,
+)
 from services.agent_service import AgentService
 from services.file_service import FileService
 
+logger = logging.getLogger(__name__)
+
+_WORKFLOW_AGENT_DRIVE_APP_MODES = [AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]
+
 
 class AgentLogQuery(BaseModel):
     message_id: str = Field(..., description="Message UUID")
@@ -31,6 +62,27 @@ class AgentLogQuery(BaseModel):
         return uuid_value(value)
 
 
+class AgentDriveFilePayload(BaseModel):
+    upload_file_id: str = Field(..., description="UploadFile UUID from POST /console/api/files/upload")
+
+    @field_validator("upload_file_id")
+    @classmethod
+    def validate_upload_file_id(cls, value: str) -> str:
+        return uuid_value(value)
+
+
+class AgentDriveMutationQuery(BaseModel):
+    node_id: str | None = Field(default=None, description="Workflow node ID (workflow composer variant)")
+
+
+class AgentDriveDeleteFileQuery(AgentDriveMutationQuery):
+    key: str = Field(min_length=1, description="Drive key, e.g. files/sample.pdf")
+
+
+class AgentDriveDeleteFileByAgentQuery(BaseModel):
+    key: str = Field(min_length=1, description="Drive key, e.g. files/sample.pdf")
+
+
 class AgentLogMetaResponse(ResponseModel):
     status: str
     executor: str
@@ -68,16 +120,244 @@ class AgentLogResponse(ResponseModel):
     files: list[Any] = Field(default_factory=list)
 
 
-class AgentSkillUploadResponse(RootModel[dict[str, Any]]):
-    root: dict[str, Any]
+class AgentSkillUploadResponse(ResponseModel):
+    skill: AgentSkillRefConfig
+    manifest: SkillManifest
 
 
-class AgentSkillStandardizeResponse(RootModel[dict[str, Any]]):
-    root: dict[str, Any]
+class AgentSkillStandardizeResponse(ResponseModel):
+    skill: AgentSkillRefConfig
+    manifest: SkillManifest
 
 
-register_schema_models(console_ns, AgentLogQuery)
-register_response_schema_models(console_ns, AgentLogResponse, AgentSkillUploadResponse, AgentSkillStandardizeResponse)
+class AgentDriveFileResponse(ResponseModel):
+    name: str
+    drive_key: str
+    file_id: str
+    size: int | None = None
+    mime_type: str | None = None
+
+
+class AgentDriveFileCommitResponse(ResponseModel):
+    file: AgentDriveFileResponse
+    config_version_id: str | None = None
+
+
+class AgentDriveDeleteResponse(ResponseModel):
+    result: str
+    removed_keys: list[str] = Field(default_factory=list)
+    config_version_id: str | None = None
+
+
+register_schema_models(console_ns, AgentLogQuery, AgentDriveFilePayload, AgentDriveDeleteFileByAgentQuery)
+register_response_schema_models(
+    console_ns,
+    AgentDriveDeleteResponse,
+    AgentDriveFileCommitResponse,
+    AgentDriveFileResponse,
+    AgentLogResponse,
+    AgentSkillStandardizeResponse,
+    AgentSkillUploadResponse,
+    SkillToolInferenceResult,
+)
+
+
+def _resolve_agent_id(app_model: App, node_id: str | None) -> str | None:
+    if node_id and app_model.mode != AppMode.AGENT:
+        return AgentComposerService.resolve_workflow_node_agent_id(
+            tenant_id=app_model.tenant_id, app_id=app_model.id, node_id=node_id
+        )
+    return app_model.bound_agent_id
+
+
+def _agent_not_bound() -> tuple[dict[str, str], int]:
+    return {"code": "agent_not_bound", "message": "no agent is bound for this app/node"}, 400
+
+
+def _upload_skill_for_app(*, current_user: Account):
+    if "file" not in request.files:
+        return {"code": "no_file", "message": "no skill file uploaded"}, 400
+    if len(request.files) > 1:
+        return {"code": "too_many_files", "message": "only one skill file is allowed"}, 400
+
+    upload = request.files["file"]
+    content = upload.stream.read()
+    try:
+        manifest = SkillPackageService().validate_and_extract(content=content, filename=upload.filename or "")
+    except SkillPackageError as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+
+    upload_file = FileService(db.engine).upload_file(
+        filename=upload.filename or "skill.zip",
+        content=content,
+        mimetype=upload.mimetype or "application/zip",
+        user=current_user,
+    )
+    skill_ref = manifest.to_skill_ref(file_id=upload_file.id)
+    return {"skill": skill_ref.model_dump(exclude_none=True), "manifest": manifest.model_dump()}, 201
+
+
+def _standardize_skill_for_app(*, current_user: Account, app_model: App):
+    query = query_params_from_request(AgentDriveMutationQuery)
+    agent_id = _resolve_agent_id(app_model, query.node_id)
+    if not agent_id:
+        return _agent_not_bound()
+    if "file" not in request.files:
+        return {"code": "no_file", "message": "no skill file uploaded"}, 400
+    if len(request.files) > 1:
+        return {"code": "too_many_files", "message": "only one skill file is allowed"}, 400
+
+    upload = request.files["file"]
+    content = upload.stream.read()
+    try:
+        result = SkillStandardizeService().standardize(
+            content=content,
+            filename=upload.filename or "",
+            tenant_id=app_model.tenant_id,
+            user_id=current_user.id,
+            agent_id=agent_id,
+        )
+    except (SkillPackageError, AgentDriveError) as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+    return result, 201
+
+
+def _commit_drive_file_for_app(*, current_user: Account, app_model: App, allow_node_id: bool = True):
+    query = query_params_from_request(AgentDriveMutationQuery)
+    node_id = query.node_id if allow_node_id else None
+    agent_id = _resolve_agent_id(app_model, node_id)
+    if not agent_id:
+        return _agent_not_bound()
+    payload = AgentDriveFilePayload.model_validate(console_ns.payload or {})
+
+    upload_file = db.session.scalar(
+        select(UploadFile).where(
+            UploadFile.id == payload.upload_file_id,
+            UploadFile.tenant_id == app_model.tenant_id,
+        )
+    )
+    if upload_file is None:
+        return {"code": "upload_file_not_found", "message": "upload file not found in this workspace"}, 404
+
+    try:
+        key = normalize_drive_key(f"files/{upload_file.name}")
+        committed = AgentDriveService().commit(
+            tenant_id=app_model.tenant_id,
+            user_id=current_user.id,
+            agent_id=agent_id,
+            items=[
+                DriveCommitItem(
+                    key=key,
+                    file_ref=DriveFileRef(kind="upload_file", id=upload_file.id),
+                    # ADD FILE uploads exist solely to live in the drive, so the
+                    # drive owns (and physically cleans) the value on delete.
+                    value_owned_by_drive=True,
+                )
+            ],
+        )
+    except AgentDriveError as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+
+    row = committed[0]
+    file_ref = AgentFileRefConfig.model_validate(
+        {
+            "id": row["key"],
+            "name": upload_file.name,
+            "file_id": upload_file.id,
+            "drive_key": row["key"],
+            "type": row.get("mime_type"),
+            "size": row.get("size"),
+        }
+    )
+    config_version_id = AgentComposerService.add_drive_file_ref(
+        tenant_id=app_model.tenant_id,
+        agent_id=agent_id,
+        account_id=current_user.id,
+        file_ref=file_ref,
+        app_id=app_model.id,
+        node_id=node_id,
+    )
+    return {
+        "file": {
+            "name": upload_file.name,
+            "drive_key": row["key"],
+            "file_id": upload_file.id,
+            "size": row.get("size"),
+            "mime_type": row.get("mime_type"),
+        },
+        "config_version_id": config_version_id,
+    }, 201
+
+
+def _delete_drive_file_for_app(*, current_user: Account, app_model: App, allow_node_id: bool = True):
+    query = query_params_from_request(AgentDriveDeleteFileQuery)
+    node_id = query.node_id if allow_node_id else None
+    agent_id = _resolve_agent_id(app_model, node_id)
+    if not agent_id:
+        return _agent_not_bound()
+    try:
+        key = normalize_drive_key(query.key)
+    except AgentDriveError as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+
+    config_version_id = AgentComposerService.remove_drive_refs(
+        tenant_id=app_model.tenant_id,
+        agent_id=agent_id,
+        account_id=current_user.id,
+        file_key=key,
+        app_id=app_model.id,
+        node_id=node_id,
+    )
+    removed_keys: list[str] = []
+    try:
+        removed_keys = AgentDriveService().delete(tenant_id=app_model.tenant_id, agent_id=agent_id, key=key)
+    except AgentDriveError as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+    except Exception:
+        # Soul-first ordering: the ref is already gone; orphan KV rows are
+        # harmless and an idempotent DELETE retry cleans them.
+        logger.exception("agent drive delete failed for key %s (soul already updated)", key)
+    return {"result": "success", "removed_keys": removed_keys, "config_version_id": config_version_id}
+
+
+def _delete_skill_for_app(*, current_user: Account, app_model: App, slug: str, allow_node_id: bool = True):
+    query = query_params_from_request(AgentDriveMutationQuery)
+    node_id = query.node_id if allow_node_id else None
+    agent_id = _resolve_agent_id(app_model, node_id)
+    if not agent_id:
+        return _agent_not_bound()
+    if "/" in slug or not slug.strip():
+        return {"code": "drive_key_invalid", "message": "skill slug must be a single path segment"}, 400
+
+    config_version_id = AgentComposerService.remove_drive_refs(
+        tenant_id=app_model.tenant_id,
+        agent_id=agent_id,
+        account_id=current_user.id,
+        skill_slug=slug,
+        app_id=app_model.id,
+        node_id=node_id,
+    )
+    removed_keys: list[str] = []
+    try:
+        removed_keys = AgentDriveService().delete(tenant_id=app_model.tenant_id, agent_id=agent_id, prefix=f"{slug}/")
+    except AgentDriveError as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+    except Exception:
+        logger.exception("agent drive delete failed for skill %s (soul already updated)", slug)
+    return {"result": "success", "removed_keys": removed_keys, "config_version_id": config_version_id}
+
+
+def _infer_skill_tools_for_app(*, app_model: App, slug: str):
+    query = query_params_from_request(AgentDriveMutationQuery)
+    agent_id = _resolve_agent_id(app_model, query.node_id)
+    if not agent_id:
+        return _agent_not_bound()
+    if "/" in slug or not slug.strip():
+        return {"code": "drive_key_invalid", "message": "skill slug must be a single path segment"}, 400
+    try:
+        return SkillToolInferenceService().infer(tenant_id=app_model.tenant_id, agent_id=agent_id, slug=slug)
+    except SkillToolInferenceError as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/logs")
@@ -99,6 +379,23 @@ class AgentLogApi(Resource):
         return AgentService.get_agent_logs(app_model, args.conversation_id, args.message_id)
 
 
+@console_ns.route("/agent/<uuid:agent_id>/skills/upload")
+class AgentSkillUploadByAgentApi(Resource):
+    @console_ns.doc("upload_agent_skill_by_agent")
+    @console_ns.doc(description="Upload + validate a Skill package for an Agent App")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.response(201, "Skill validated", console_ns.models[AgentSkillUploadResponse.__name__])
+    @console_ns.response(400, "Invalid skill package")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _upload_skill_for_app(current_user=current_user)
+
+
 @console_ns.route("/apps/<uuid:app_id>/agent/skills/upload")
 class AgentSkillUploadApi(Resource):
     @console_ns.doc("upload_agent_skill")
@@ -109,7 +406,7 @@ class AgentSkillUploadApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
     @with_current_user
     def post(self, current_user: Account, app_model: App):
         """Validate an uploaded Skill package and persist the archive.
@@ -117,33 +414,14 @@ class AgentSkillUploadApi(Resource):
         Returns a validated skill ref (to bind into the Agent soul config on save)
         plus its manifest. Standardizing into the agent drive is ENG-594.
         """
-        if "file" not in request.files:
-            return {"code": "no_file", "message": "no skill file uploaded"}, 400
-        if len(request.files) > 1:
-            return {"code": "too_many_files", "message": "only one skill file is allowed"}, 400
-
-        upload = request.files["file"]
-        content = upload.stream.read()
-        try:
-            manifest = SkillPackageService().validate_and_extract(content=content, filename=upload.filename or "")
-        except SkillPackageError as exc:
-            return {"code": exc.code, "message": exc.message}, exc.status_code
-
-        upload_file = FileService(db.engine).upload_file(
-            filename=upload.filename or "skill.zip",
-            content=content,
-            mimetype=upload.mimetype or "application/zip",
-            user=current_user,
-        )
-        skill_ref = manifest.to_skill_ref(file_id=upload_file.id)
-        return {"skill": skill_ref.model_dump(exclude_none=True), "manifest": manifest.model_dump()}, 201
+        return _upload_skill_for_app(current_user=current_user)
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent/skills/standardize")
-class AgentSkillStandardizeApi(Resource):
-    @console_ns.doc("standardize_agent_skill")
-    @console_ns.doc(description="Validate + standardize a Skill into the agent drive (ENG-594)")
-    @console_ns.doc(params={"app_id": "Application ID"})
+@console_ns.route("/agent/<uuid:agent_id>/skills/standardize")
+class AgentSkillStandardizeByAgentApi(Resource):
+    @console_ns.doc("standardize_agent_skill_by_agent")
+    @console_ns.doc(description="Validate + standardize a Skill into an Agent App drive")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
     @console_ns.response(
         201,
         "Skill standardized into drive",
@@ -153,28 +431,177 @@ class AgentSkillStandardizeApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _standardize_skill_for_app(current_user=current_user, app_model=app_model)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/standardize")
+class AgentSkillStandardizeApi(Resource):
+    @console_ns.doc("standardize_agent_skill")
+    @console_ns.doc(description="Validate + standardize a Skill into the agent drive (ENG-594)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveMutationQuery)})
+    @console_ns.response(
+        201,
+        "Skill standardized into drive",
+        console_ns.models[AgentSkillStandardizeResponse.__name__],
+    )
+    @console_ns.response(400, "Invalid skill package or no bound agent")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
     @with_current_user
     def post(self, current_user: Account, app_model: App):
         """Upload a Skill, validate it, and standardize it into the app agent's drive."""
-        agent_id = app_model.bound_agent_id
-        if not agent_id:
-            return {"code": "no_bound_agent", "message": "app has no bound agent"}, 400
-        if "file" not in request.files:
-            return {"code": "no_file", "message": "no skill file uploaded"}, 400
-        if len(request.files) > 1:
-            return {"code": "too_many_files", "message": "only one skill file is allowed"}, 400
+        return _standardize_skill_for_app(current_user=current_user, app_model=app_model)
 
-        upload = request.files["file"]
-        content = upload.stream.read()
-        try:
-            result = SkillStandardizeService().standardize(
-                content=content,
-                filename=upload.filename or "",
-                tenant_id=app_model.tenant_id,
-                user_id=current_user.id,
-                agent_id=agent_id,
-            )
-        except (SkillPackageError, AgentDriveError) as exc:
-            return {"code": exc.code, "message": exc.message}, exc.status_code
-        return result, 201
+
+@console_ns.route("/agent/<uuid:agent_id>/files")
+class AgentDriveFilesByAgentApi(Resource):
+    @console_ns.doc("commit_agent_drive_file_by_agent")
+    @console_ns.doc(description="Commit an uploaded file into the Agent App drive under files/<name>")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.expect(console_ns.models[AgentDriveFilePayload.__name__])
+    @console_ns.response(
+        201, "File committed into the agent drive", console_ns.models[AgentDriveFileCommitResponse.__name__]
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _commit_drive_file_for_app(current_user=current_user, app_model=app_model, allow_node_id=False)
+
+    @console_ns.doc("delete_agent_drive_file_by_agent")
+    @console_ns.doc(description="Delete one Agent App drive file by key")
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentDriveDeleteFileByAgentQuery)})
+    @console_ns.response(200, "File removed", console_ns.models[AgentDriveDeleteResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def delete(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _delete_drive_file_for_app(current_user=current_user, app_model=app_model, allow_node_id=False)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/files")
+class AgentDriveFilesApi(Resource):
+    @console_ns.doc("commit_agent_drive_file")
+    @console_ns.doc(description="Commit an uploaded file into the agent drive under files/<name> (ENG-625 D3)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveMutationQuery)})
+    @console_ns.expect(console_ns.models[AgentDriveFilePayload.__name__])
+    @console_ns.response(
+        201, "File committed into the agent drive", console_ns.models[AgentDriveFileCommitResponse.__name__]
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        """ADD FILE: commit one uploaded file into the bound agent's drive."""
+        return _commit_drive_file_for_app(current_user=current_user, app_model=app_model)
+
+    @console_ns.doc("delete_agent_drive_file")
+    @console_ns.doc(description="Delete one drive file by key; soul ref first, then the KV row (ENG-625 D5)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveDeleteFileQuery)})
+    @console_ns.response(200, "File removed", console_ns.models[AgentDriveDeleteResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
+    @with_current_user
+    def delete(self, current_user: Account, app_model: App):
+        return _delete_drive_file_for_app(current_user=current_user, app_model=app_model)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/skills/<string:slug>")
+class AgentSkillByAgentApi(Resource):
+    @console_ns.doc("delete_agent_skill_by_agent")
+    @console_ns.doc(description="Delete a standardized skill from an Agent App drive")
+    @console_ns.doc(params={"agent_id": "Agent ID", "slug": "Skill slug (single path segment)"})
+    @console_ns.response(200, "Skill removed", console_ns.models[AgentDriveDeleteResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def delete(self, tenant_id: str, current_user: Account, agent_id: UUID, slug: str):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _delete_skill_for_app(current_user=current_user, app_model=app_model, slug=slug, allow_node_id=False)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/<string:slug>")
+class AgentSkillApi(Resource):
+    @console_ns.doc("delete_agent_skill")
+    @console_ns.doc(
+        description="Delete a standardized skill: soul ref first, then the <slug>/ drive prefix (ENG-625 D5)"
+    )
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "slug": "Skill slug (single path segment)",
+            **query_params_from_model(AgentDriveMutationQuery),
+        }
+    )
+    @console_ns.response(200, "Skill removed", console_ns.models[AgentDriveDeleteResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
+    @with_current_user
+    def delete(self, current_user: Account, app_model: App, slug: str):
+        return _delete_skill_for_app(current_user=current_user, app_model=app_model, slug=slug)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/skills/<string:slug>/infer-tools")
+class AgentSkillInferToolsByAgentApi(Resource):
+    @console_ns.doc("infer_agent_skill_tools_by_agent")
+    @console_ns.doc(description="Infer CLI tool + ENV suggestions from a standardized Agent App skill")
+    @console_ns.doc(params={"agent_id": "Agent ID", "slug": "Skill slug (single path segment)"})
+    @console_ns.response(
+        200,
+        "Inference result (draft suggestions, nothing persisted)",
+        console_ns.models[SkillToolInferenceResult.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def post(self, tenant_id: str, agent_id: UUID, slug: str):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _infer_skill_tools_for_app(app_model=app_model, slug=slug)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/<string:slug>/infer-tools")
+class AgentSkillInferToolsApi(Resource):
+    @console_ns.doc("infer_agent_skill_tools")
+    @console_ns.doc(
+        description="Infer CLI tool + ENV suggestions from a standardized skill's SKILL.md (draft only, ENG-371)"
+    )
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "slug": "Skill slug (single path segment)",
+            **query_params_from_model(AgentDriveMutationQuery),
+        }
+    )
+    @console_ns.response(
+        200,
+        "Inference result (draft suggestions, nothing persisted)",
+        console_ns.models[SkillToolInferenceResult.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
+    def post(self, app_model: App, slug: str):
+        """Suggest CLI tools/env for a skill. Saving still goes through composer validation."""
+        return _infer_skill_tools_for_app(app_model=app_model, slug=slug)

api/controllers/console/app/agent_app_access.py

@@ -5,25 +5,31 @@ reference. This exposes the read-only "Workflow access" surface from the PRD:
 which workflow apps use this Agent, without leaking the workflows' internals.
 """
 
+from uuid import UUID
+
 from flask_restx import Resource
 from pydantic import Field
 
 from controllers.common.schema import register_response_schema_models
 from controllers.console import console_ns
-from controllers.console.app.wraps import get_app_model
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 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.model import App, AppMode
 from services.agent.roster_service import AgentRosterService
 
 
 class AgentReferencingWorkflowResponse(ResponseModel):
     app_id: str
     app_name: str
+    app_icon_type: str | None = None
+    app_icon: str | None = None
+    app_icon_background: str | None = None
     app_mode: str
+    app_updated_at: int | None = None
     workflow_id: str
+    workflow_version: str
     node_ids: list[str] = Field(default_factory=list)
 
 
@@ -34,23 +40,23 @@ class AgentReferencingWorkflowsResponse(ResponseModel):
 register_response_schema_models(console_ns, AgentReferencingWorkflowsResponse)
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-referencing-workflows")
+@console_ns.route("/agent/<uuid:agent_id>/referencing-workflows")
 class AgentAppReferencingWorkflowsResource(Resource):
     @console_ns.doc("list_agent_app_referencing_workflows")
     @console_ns.doc(description="List workflow apps that reference this Agent App's bound Agent (read-only)")
-    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.doc(params={"agent_id": "Agent ID"})
     @console_ns.response(
         200,
         "Referencing workflows listed successfully",
         console_ns.models[AgentReferencingWorkflowsResponse.__name__],
     )
-    @console_ns.response(404, "App not found")
+    @console_ns.response(404, "Agent not found")
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_tenant_id
-    def get(self, tenant_id: str, app_model: App):
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         workflows = AgentRosterService(db.session).list_workflows_referencing_app_agent(
             tenant_id=tenant_id, app_id=app_model.id
         )

api/controllers/console/app/agent_app_feature.py

@@ -9,17 +9,20 @@ persists them onto the app's ``app_model_config`` without touching anything the
 Soul owns.
 """
 
+from uuid import UUID
+
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
 from controllers.common.fields import SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
-from controllers.console.app.wraps import get_app_model
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
 )
 from events.app_event import app_model_config_was_updated
@@ -32,7 +35,6 @@ from models.agent_config_entities import (
     AgentSuggestedQuestionsAfterAnswerFeatureConfig,
     AgentTextToSpeechFeatureConfig,
 )
-from models.model import App, AppMode
 from services.agent_app_feature_service import AgentAppFeatureConfigService
 
 
@@ -64,22 +66,23 @@ register_schema_models(console_ns, AgentAppFeaturesPayload)
 register_response_schema_models(console_ns, SimpleResultResponse)
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-features")
+@console_ns.route("/agent/<uuid:agent_id>/features")
 class AgentAppFeatureConfigResource(Resource):
     @console_ns.doc("update_agent_app_features")
     @console_ns.doc(description="Update an Agent App's presentation features (opener, follow-up, citations, ...)")
-    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.doc(params={"agent_id": "Agent ID"})
     @console_ns.expect(console_ns.models[AgentAppFeaturesPayload.__name__])
     @console_ns.response(200, "Features updated successfully", console_ns.models[SimpleResultResponse.__name__])
     @console_ns.response(400, "Invalid configuration")
-    @console_ns.response(404, "App not found")
+    @console_ns.response(404, "Agent not found")
     @setup_required
     @login_required
     @edit_permission_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_user
-    def post(self, current_user: Account, app_model: App):
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         args = AgentAppFeaturesPayload.model_validate(console_ns.payload or {})
 
         new_app_model_config = AgentAppFeatureConfigService.update_features(

api/controllers/console/app/agent_app_sandbox.py

@@ -22,6 +22,7 @@ from controllers.common.schema import (
     register_schema_models,
 )
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_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
 from fields.base import ResponseModel
@@ -132,18 +133,18 @@ def _handle(exc: Exception) -> tuple[dict[str, object], int]:
     raise exc
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files")
+@console_ns.route("/agent/<uuid:agent_id>/sandbox/files")
 class AgentAppSandboxListResource(Resource):
     @console_ns.doc("list_agent_app_sandbox_files")
     @console_ns.doc(description="List a directory in an Agent App conversation sandbox")
-    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentSandboxListQuery)})
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentSandboxListQuery)})
     @console_ns.response(200, "Listing returned", console_ns.models[SandboxListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_tenant_id
-    def get(self, tenant_id: str, app_model: App):
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxListQuery)
         try:
             result = AgentAppSandboxService().list_files(
@@ -157,18 +158,18 @@ class AgentAppSandboxListResource(Resource):
         return result.model_dump()
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files/read")
+@console_ns.route("/agent/<uuid:agent_id>/sandbox/files/read")
 class AgentAppSandboxReadResource(Resource):
     @console_ns.doc("read_agent_app_sandbox_file")
     @console_ns.doc(description="Read a text/binary preview file in an Agent App conversation sandbox")
-    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentSandboxFileQuery)})
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentSandboxFileQuery)})
     @console_ns.response(200, "Preview returned", console_ns.models[SandboxReadResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_tenant_id
-    def get(self, tenant_id: str, app_model: App):
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxFileQuery)
         try:
             result = AgentAppSandboxService().read_file(
@@ -182,7 +183,7 @@ class AgentAppSandboxReadResource(Resource):
         return result.model_dump()
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files/upload")
+@console_ns.route("/agent/<uuid:agent_id>/sandbox/files/upload")
 class AgentAppSandboxUploadResource(Resource):
     @console_ns.doc("upload_agent_app_sandbox_file")
     @console_ns.doc(description="Upload one Agent App sandbox file as a Dify ToolFile mapping")
@@ -191,9 +192,9 @@ class AgentAppSandboxUploadResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_tenant_id
-    def post(self, tenant_id: str, app_model: App):
+    def post(self, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         payload = AgentSandboxUploadPayload.model_validate(request.get_json(silent=True) or {})
         try:
             result = AgentAppSandboxService().upload_file(

api/controllers/console/app/agent_drive_inspector.py

@@ -0,0 +1,235 @@
+"""Console read-only inspector for the agent drive (ENG-624).
+
+``agent-drive`` looks at the *static* drive assets (standardized skills and
+committed files); the sibling ``agent-sandbox`` routes look at a *runtime*
+sandbox workspace. Unlike the sandbox routes this never proxies to the agent
+backend — drive data lives in the API's own DB/storage, served straight from
+``AgentDriveService``. Download hands the browser an **external** signed URL
+(the inner manifest hands agents internal ones — the two must never mix).
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from flask_restx import Resource
+from pydantic import BaseModel, Field
+
+from controllers.common.schema import (
+    query_params_from_model,
+    query_params_from_request,
+    register_response_schema_models,
+)
+from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_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
+from fields.base import ResponseModel
+from libs.login import login_required
+from models.model import App, AppMode
+from services.agent.composer_service import AgentComposerService
+from services.agent_drive_service import AgentDriveError, AgentDriveService
+
+
+class AgentDriveListQuery(BaseModel):
+    prefix: str = Field(default="", description="Key prefix filter: '<slug>/' for one skill, 'files/' for files")
+    node_id: str | None = Field(default=None, description="Workflow node ID (workflow composer variant)")
+
+
+class AgentDriveListByAgentQuery(BaseModel):
+    prefix: str = Field(default="", description="Key prefix filter: '<slug>/' for one skill, 'files/' for files")
+
+
+class AgentDriveFileQuery(BaseModel):
+    key: str = Field(min_length=1, description="Drive key, e.g. tender-analyzer/SKILL.md")
+    node_id: str | None = Field(default=None, description="Workflow node ID (workflow composer variant)")
+
+
+class AgentDriveFileByAgentQuery(BaseModel):
+    key: str = Field(min_length=1, description="Drive key, e.g. tender-analyzer/SKILL.md")
+
+
+class AgentDriveItemResponse(ResponseModel):
+    key: str
+    size: int | None = None
+    mime_type: str | None = None
+    hash: str | None = None
+    file_kind: str
+    created_at: int | None = None
+
+
+class AgentDriveListResponse(ResponseModel):
+    items: list[AgentDriveItemResponse] = Field(default_factory=list)
+
+
+class AgentDrivePreviewResponse(ResponseModel):
+    key: str
+    size: int | None = None
+    truncated: bool
+    binary: bool
+    text: str | None = None
+
+
+class AgentDriveDownloadResponse(ResponseModel):
+    url: str
+
+
+register_response_schema_models(
+    console_ns, AgentDriveListResponse, AgentDrivePreviewResponse, AgentDriveDownloadResponse
+)
+
+
+def _resolve_agent_id(app_model: App, node_id: str | None) -> str | None:
+    """Agent identity for the drive: app-bound agent, or the workflow node binding."""
+    if node_id:
+        return AgentComposerService.resolve_workflow_node_agent_id(
+            tenant_id=app_model.tenant_id, app_id=app_model.id, node_id=node_id
+        )
+    return app_model.bound_agent_id
+
+
+def _agent_not_bound() -> tuple[dict[str, object], int]:
+    return {"code": "agent_not_bound", "message": "no agent is bound for this app/node"}, 400
+
+
+def _handle(exc: AgentDriveError) -> tuple[dict[str, object], int]:
+    return {"code": exc.code, "message": exc.message}, exc.status_code
+
+
+_WORKFLOW_APP_MODES = [AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]
+
+
+@console_ns.route("/agent/<uuid:agent_id>/drive/files")
+class AgentDriveListByAgentApi(Resource):
+    @console_ns.doc("list_agent_drive_files_by_agent")
+    @console_ns.doc(description="List agent drive entries for an Agent App")
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentDriveListByAgentQuery)})
+    @console_ns.response(200, "Drive entries", console_ns.models[AgentDriveListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        query = query_params_from_request(AgentDriveListByAgentQuery)
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        try:
+            items = AgentDriveService().manifest(tenant_id=tenant_id, agent_id=str(agent_id), prefix=query.prefix)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        return {"items": [{k: v for k, v in item.items() if k != "file_id"} for item in items]}
+
+
+@console_ns.route("/agent/<uuid:agent_id>/drive/files/preview")
+class AgentDrivePreviewByAgentApi(Resource):
+    @console_ns.doc("preview_agent_drive_file_by_agent")
+    @console_ns.doc(description="Truncated text preview of one Agent App drive value")
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentDriveFileByAgentQuery)})
+    @console_ns.response(200, "Preview", console_ns.models[AgentDrivePreviewResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        query = query_params_from_request(AgentDriveFileByAgentQuery)
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        try:
+            return AgentDriveService().preview(tenant_id=tenant_id, agent_id=str(agent_id), key=query.key)
+        except AgentDriveError as exc:
+            return _handle(exc)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/drive/files/download")
+class AgentDriveDownloadByAgentApi(Resource):
+    @console_ns.doc("download_agent_drive_file_by_agent")
+    @console_ns.doc(description="Time-limited external signed URL for one Agent App drive value")
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentDriveFileByAgentQuery)})
+    @console_ns.response(200, "Signed URL", console_ns.models[AgentDriveDownloadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        query = query_params_from_request(AgentDriveFileByAgentQuery)
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        try:
+            url = AgentDriveService().download_url(tenant_id=tenant_id, agent_id=str(agent_id), key=query.key)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        return {"url": url}
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/drive/files")
+class AgentDriveListApi(Resource):
+    @console_ns.doc("list_agent_drive_files")
+    @console_ns.doc(description="List agent drive entries (read-only inspector; one endpoint for both tabs)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveListQuery)})
+    @console_ns.response(200, "Drive entries", console_ns.models[AgentDriveListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, app_model: App):
+        query = query_params_from_request(AgentDriveListQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        try:
+            items = AgentDriveService().manifest(tenant_id=app_model.tenant_id, agent_id=agent_id, prefix=query.prefix)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        # the inner manifest exposes file_id for agent-side pulls; the console
+        # inspector is a pure read surface and does not need value pointers
+        return {"items": [{k: v for k, v in item.items() if k != "file_id"} for item in items]}
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/drive/files/preview")
+class AgentDrivePreviewApi(Resource):
+    @console_ns.doc("preview_agent_drive_file")
+    @console_ns.doc(description="Truncated text preview of one drive value (binary-safe; SKILL.md is the main case)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveFileQuery)})
+    @console_ns.response(200, "Preview", console_ns.models[AgentDrivePreviewResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, app_model: App):
+        query = query_params_from_request(AgentDriveFileQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        try:
+            return AgentDriveService().preview(tenant_id=app_model.tenant_id, agent_id=agent_id, key=query.key)
+        except AgentDriveError as exc:
+            return _handle(exc)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/drive/files/download")
+class AgentDriveDownloadApi(Resource):
+    @console_ns.doc("download_agent_drive_file")
+    @console_ns.doc(description="Time-limited external signed URL for one drive value (no streaming proxy)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveFileQuery)})
+    @console_ns.response(200, "Signed URL", console_ns.models[AgentDriveDownloadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, app_model: App):
+        query = query_params_from_request(AgentDriveFileQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        try:
+            url = AgentDriveService().download_url(tenant_id=app_model.tenant_id, agent_id=agent_id, key=query.key)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        return {"url": url}
+
+
+__all__ = [
+    "AgentDriveDownloadApi",
+    "AgentDriveDownloadByAgentApi",
+    "AgentDriveListApi",
+    "AgentDriveListByAgentApi",
+    "AgentDrivePreviewApi",
+    "AgentDrivePreviewByAgentApi",
+]

api/controllers/console/app/app.py

@@ -1,6 +1,7 @@
 import logging
 import re
 import uuid
+from collections.abc import Sequence
 from datetime import datetime
 from typing import Any, Literal, cast
 
@@ -41,12 +42,12 @@ from core.trigger.constants import TRIGGER_NODE_TYPES
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from graphon.enums import WorkflowExecutionStatus
-from libs.helper import build_icon_url, to_timestamp
+from libs.helper import build_icon_url, dump_response, to_timestamp
 from libs.login import login_required
 from models import Account, App, DatasetPermissionEnum, Workflow
 from models.model import IconType
 from services.app_dsl_service import AppDslService
-from services.app_service import AppListParams, AppService, CreateAppParams
+from services.app_service import AppListParams, AppListSortBy, AppService, CreateAppParams, StarredAppListParams
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import ImportMode, ImportStatus
 from services.entities.knowledge_entities.knowledge_entities import (
@@ -63,7 +64,7 @@ from services.entities.knowledge_entities.knowledge_entities import (
 )
 from services.feature_service import FeatureService
 
-ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"]
+ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "advanced-chat", "workflow", "completion"]
 
 register_enum_models(console_ns, IconType)
 
@@ -73,10 +74,14 @@ _CREATOR_IDS_BRACKET_PATTERN = re.compile(r"^creator_ids\[(\d+)\]$")
 AppListMode = Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"]
 
 
-class AppListQuery(BaseModel):
+class AppListBaseQuery(BaseModel):
     page: int = Field(default=1, ge=1, le=99999, description="Page number (1-99999)")
     limit: int = Field(default=20, ge=1, le=100, description="Page size (1-100)")
     mode: AppListMode = Field(default=cast(AppListMode, "all"), description="App mode filter")
+    sort_by: AppListSortBy = Field(
+        default="last_modified",
+        description="Sort apps by last modified, recently created, or earliest created",
+    )
     name: str | None = Field(default=None, description="Filter by app name")
     tag_ids: list[str] | None = Field(default=None, description="Filter by tag IDs")
     creator_ids: list[str] | None = Field(default=None, description="Filter by creator account IDs")
@@ -119,6 +124,14 @@ class AppListQuery(BaseModel):
             raise ValueError("Invalid UUID format in creator_ids.") from exc
 
 
+class AppListQuery(AppListBaseQuery):
+    pass
+
+
+class StarredAppListQuery(AppListBaseQuery):
+    pass
+
+
 def _normalize_app_list_query_args(query_args: MultiDict[str, str]) -> dict[str, str | list[str]]:
     normalized: dict[str, str | list[str]] = {}
     indexed_tag_ids: list[tuple[int, str]] = []
@@ -150,9 +163,7 @@ def _normalize_app_list_query_args(query_args: MultiDict[str, str]) -> dict[str,
 class CreateAppPayload(BaseModel):
     name: str = Field(..., min_length=1, description="App name")
     description: str | None = Field(default=None, description="App description (max 400 chars)", max_length=400)
-    mode: Literal["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"] = Field(
-        ..., description="App mode"
-    )
+    mode: Literal["chat", "agent-chat", "advanced-chat", "workflow", "completion"] = Field(..., description="App mode")
     icon_type: IconType | None = Field(default=None, description="Icon type")
     icon: str | None = Field(default=None, description="Icon")
     icon_background: str | None = Field(default=None, description="Icon background color")
@@ -387,6 +398,12 @@ class AppPartial(ResponseModel):
     create_user_name: str | None = None
     author_name: str | None = None
     has_draft_trigger: bool | None = None
+    # For Agent App type: the roster Agent backing this app (None otherwise).
+    bound_agent_id: str | None = None
+    # For Agent App responses exposed through /agent.
+    app_id: str | None = None
+    role: str | None = None
+    is_starred: bool = False
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -437,6 +454,9 @@ class AppDetailWithSite(AppDetail):
     site: Site | None = None
     # For Agent App type: the roster Agent backing this app (None otherwise).
     bound_agent_id: str | None = None
+    # For Agent App responses exposed through /agent.
+    app_id: str | None = None
+    role: str | None = None
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -456,12 +476,54 @@ class AppExportResponse(ResponseModel):
     data: str
 
 
+def _enrich_app_list_items(session: Session, *, apps: Sequence[App], tenant_id: str) -> None:
+    if FeatureService.get_system_features().webapp_auth.enabled:
+        app_ids = [str(app.id) for app in apps]
+        res = EnterpriseService.WebAppAuth.batch_get_app_access_mode_by_id(app_ids=app_ids)
+        if len(res) != len(app_ids):
+            raise BadRequest("Invalid app id in webapp auth")
+
+        for app in apps:
+            if str(app.id) in res:
+                app.access_mode = res[str(app.id)].access_mode
+
+    workflow_capable_app_ids = [str(app.id) for app in apps if app.mode in {"workflow", "advanced-chat"}]
+    draft_trigger_app_ids: set[str] = set()
+    if workflow_capable_app_ids:
+        draft_workflows = (
+            session.execute(
+                select(Workflow).where(
+                    Workflow.version == Workflow.VERSION_DRAFT,
+                    Workflow.app_id.in_(workflow_capable_app_ids),
+                    Workflow.tenant_id == tenant_id,
+                )
+            )
+            .scalars()
+            .all()
+        )
+        trigger_node_types = TRIGGER_NODE_TYPES
+        for workflow in draft_workflows:
+            node_id = None
+            try:
+                for node_id, node_data in workflow.walk_nodes():
+                    if node_data.get("type") in trigger_node_types:
+                        draft_trigger_app_ids.add(str(workflow.app_id))
+                        break
+            except Exception:
+                _logger.exception("error while walking nodes, workflow_id=%s, node_id=%s", workflow.id, node_id)
+                continue
+
+    for app in apps:
+        app.has_draft_trigger = str(app.id) in draft_trigger_app_ids
+
+
 register_enum_models(console_ns, RetrievalMethod, WorkflowExecutionStatus, DatasetPermissionEnum)
 register_response_schema_models(console_ns, AppTraceResponse, RedirectUrlResponse, SimpleResultResponse)
 
 register_schema_models(
     console_ns,
     AppListQuery,
+    StarredAppListQuery,
     CreateAppPayload,
     UpdateAppPayload,
     CopyAppPayload,
@@ -521,6 +583,7 @@ class AppListApi(Resource):
             page=args.page,
             limit=args.limit,
             mode=args.mode,
+            sort_by=args.sort_by,
             name=args.name,
             tag_ids=args.tag_ids,
             creator_ids=args.creator_ids,
@@ -534,46 +597,7 @@ class AppListApi(Resource):
             empty = AppPagination(page=args.page, limit=args.limit, total=0, has_more=False, data=[])
             return empty.model_dump(mode="json"), 200
 
-        if FeatureService.get_system_features().webapp_auth.enabled:
-            app_ids = [str(app.id) for app in app_pagination.items]
-            res = EnterpriseService.WebAppAuth.batch_get_app_access_mode_by_id(app_ids=app_ids)
-            if len(res) != len(app_ids):
-                raise BadRequest("Invalid app id in webapp auth")
-
-            for app in app_pagination.items:
-                if str(app.id) in res:
-                    app.access_mode = res[str(app.id)].access_mode
-
-        workflow_capable_app_ids = [
-            str(app.id) for app in app_pagination.items if app.mode in {"workflow", "advanced-chat"}
-        ]
-        draft_trigger_app_ids: set[str] = set()
-        if workflow_capable_app_ids:
-            draft_workflows = (
-                session.execute(
-                    select(Workflow).where(
-                        Workflow.version == Workflow.VERSION_DRAFT,
-                        Workflow.app_id.in_(workflow_capable_app_ids),
-                        Workflow.tenant_id == current_tenant_id,
-                    )
-                )
-                .scalars()
-                .all()
-            )
-            trigger_node_types = TRIGGER_NODE_TYPES
-            for workflow in draft_workflows:
-                node_id = None
-                try:
-                    for node_id, node_data in workflow.walk_nodes():
-                        if node_data.get("type") in trigger_node_types:
-                            draft_trigger_app_ids.add(str(workflow.app_id))
-                            break
-                except Exception:
-                    _logger.exception("error while walking nodes, workflow_id=%s, node_id=%s", workflow.id, node_id)
-                    continue
-
-        for app in app_pagination.items:
-            app.has_draft_trigger = str(app.id) in draft_trigger_app_ids
+        _enrich_app_list_items(session, apps=app_pagination.items, tenant_id=current_tenant_id)
 
         pagination_model = AppPagination.model_validate(app_pagination, from_attributes=True)
         return pagination_model.model_dump(mode="json"), 200
@@ -581,7 +605,7 @@ class AppListApi(Resource):
     @console_ns.doc("create_app")
     @console_ns.doc(description="Create a new application")
     @console_ns.expect(console_ns.models[CreateAppPayload.__name__])
-    @console_ns.response(201, "App created successfully", console_ns.models[AppDetail.__name__])
+    @console_ns.response(201, "App created successfully", console_ns.models[AppDetailWithSite.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
@@ -605,10 +629,82 @@ class AppListApi(Resource):
 
         app_service = AppService()
         app = app_service.create_app(current_tenant_id, params, current_user)
-        app_detail = AppDetail.model_validate(app, from_attributes=True)
+        app_detail = AppDetailWithSite.model_validate(app, from_attributes=True)
         return app_detail.model_dump(mode="json"), 201
 
 
+@console_ns.route("/apps/starred")
+class StarredAppListApi(Resource):
+    @console_ns.doc("list_starred_apps")
+    @console_ns.doc(description="Get applications starred by the current account")
+    @console_ns.doc(params=query_params_from_model(StarredAppListQuery))
+    @console_ns.response(200, "Success", console_ns.models[AppPagination.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_session(write=False)
+    @with_current_user_id
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user_id: str, session: Session):
+        args = StarredAppListQuery.model_validate(_normalize_app_list_query_args(request.args))
+        params = StarredAppListParams(
+            page=args.page,
+            limit=args.limit,
+            mode=args.mode,
+            sort_by=args.sort_by,
+            name=args.name,
+            tag_ids=args.tag_ids,
+            creator_ids=args.creator_ids,
+            is_created_by_me=args.is_created_by_me,
+        )
+
+        app_pagination = AppService().get_paginate_starred_apps(current_user_id, current_tenant_id, params)
+        if not app_pagination:
+            empty = AppPagination(page=args.page, limit=args.limit, total=0, has_more=False, data=[])
+            return empty.model_dump(mode="json"), 200
+
+        _enrich_app_list_items(session, apps=app_pagination.items, tenant_id=current_tenant_id)
+
+        pagination_model = AppPagination.model_validate(app_pagination, from_attributes=True)
+        return pagination_model.model_dump(mode="json"), 200
+
+
+@console_ns.route("/apps/<uuid:app_id>/star")
+class AppStarApi(Resource):
+    @console_ns.doc("star_app")
+    @console_ns.doc(description="Star an application for the current account")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
+    @console_ns.response(404, "App not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_current_user_id
+    @with_session
+    @get_app_model(mode=None)
+    def post(self, session: Session, current_user_id: str, app_model: App):
+        AppService.star_app(session, app=app_model, account_id=current_user_id)
+        return dump_response(SimpleResultResponse, {"result": "success"})
+
+    @console_ns.doc("unstar_app")
+    @console_ns.doc(description="Remove the current account's star from an application")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
+    @console_ns.response(404, "App not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_current_user_id
+    @with_session
+    @get_app_model(mode=None)
+    def delete(self, session: Session, current_user_id: str, app_model: App):
+        AppService.unstar_app(session, app=app_model, account_id=current_user_id)
+        return dump_response(SimpleResultResponse, {"result": "success"})
+
+
 @console_ns.route("/apps/<uuid:app_id>")
 class AppApi(Resource):
     @console_ns.doc("get_app_detail")
@@ -628,7 +724,7 @@ class AppApi(Resource):
 
         if FeatureService.get_system_features().webapp_auth.enabled:
             app_setting = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_id=str(app_model.id))
-            app_model.access_mode = app_setting.access_mode  # type: ignore[attr-defined]
+            app_model.access_mode = app_setting.access_mode
 
         response_model = AppDetailWithSite.model_validate(app_model, from_attributes=True)
         return response_model.model_dump(mode="json")

api/controllers/console/app/completion.py

@@ -1,5 +1,6 @@
 import logging
 from typing import Any, Literal
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -10,6 +11,7 @@ import services
 from controllers.common.fields import GeneratedAppResponse, SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.error import (
     AppUnavailableError,
     CompletionRequestError,
@@ -23,6 +25,7 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
     with_current_user_id,
 )
@@ -186,51 +189,27 @@ class ChatMessageApi(Resource):
     @edit_permission_required
     @with_current_user
     def post(self, current_user: Account, app_model: App):
-        raw_payload = console_ns.payload or {}
-        args_model = ChatMessagePayload.model_validate(raw_payload)
-        args = args_model.model_dump(exclude_none=True, by_alias=True)
+        return _create_chat_message(current_user=current_user, app_model=app_model)
 
-        streaming = _resolve_debugger_chat_streaming(
-            app_mode=AppMode.value_of(app_model.mode),
-            response_mode=args_model.response_mode,
-            response_mode_provided=isinstance(raw_payload, dict) and "response_mode" in raw_payload,
-        )
-        if AppMode.value_of(app_model.mode) == AppMode.AGENT:
-            args["response_mode"] = "streaming"
-        args["auto_generate_name"] = False
 
-        external_trace_id = get_external_trace_id(request)
-        if external_trace_id:
-            args["external_trace_id"] = external_trace_id
-
-        try:
-            response = AppGenerateService.generate(
-                app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.DEBUGGER, streaming=streaming
-            )
-
-            return helper.compact_generate_response(response)
-        except services.errors.conversation.ConversationNotExistsError:
-            raise NotFound("Conversation Not Exists.")
-        except services.errors.conversation.ConversationCompletedError:
-            raise ConversationCompletedError()
-        except services.errors.app_model_config.AppModelConfigBrokenError:
-            logger.exception("App model config broken.")
-            raise AppUnavailableError()
-        except ProviderTokenNotInitError as ex:
-            raise ProviderNotInitializeError(ex.description)
-        except QuotaExceededError:
-            raise ProviderQuotaExceededError()
-        except ModelCurrentlyNotSupportError:
-            raise ProviderModelCurrentlyNotSupportError()
-        except InvokeRateLimitError as ex:
-            raise InvokeRateLimitHttpError(ex.description)
-        except InvokeError as e:
-            raise CompletionRequestError(e.description)
-        except ValueError as e:
-            raise e
-        except Exception as e:
-            logger.exception("internal server error.")
-            raise InternalServerError()
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages")
+class AgentChatMessageApi(Resource):
+    @console_ns.doc("create_agent_chat_message")
+    @console_ns.doc(description="Generate an Agent App chat message for debugging")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.expect(console_ns.models[ChatMessagePayload.__name__])
+    @console_ns.response(200, "Chat message generated successfully", console_ns.models[GeneratedAppResponse.__name__])
+    @console_ns.response(400, "Invalid request parameters")
+    @console_ns.response(404, "Agent or conversation not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _create_chat_message(current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/chat-messages/<string:task_id>/stop")
@@ -245,12 +224,79 @@ class ChatMessageStopApi(Resource):
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user_id
     def post(self, current_user_id: str, app_model: App, task_id: str):
+        return _stop_chat_message(current_user_id=current_user_id, app_model=app_model, task_id=task_id)
 
-        AppTaskService.stop_task(
-            task_id=task_id,
-            invoke_from=InvokeFrom.DEBUGGER,
-            user_id=current_user_id,
-            app_mode=AppMode.value_of(app_model.mode),
+
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages/<string:task_id>/stop")
+class AgentChatMessageStopApi(Resource):
+    @console_ns.doc("stop_agent_chat_message")
+    @console_ns.doc(description="Stop a running Agent App chat message generation")
+    @console_ns.doc(params={"agent_id": "Agent ID", "task_id": "Task ID to stop"})
+    @console_ns.response(200, "Task stopped successfully", console_ns.models[SimpleResultResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user_id
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user_id: str, agent_id: UUID, task_id: str):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _stop_chat_message(current_user_id=current_user_id, app_model=app_model, task_id=task_id)
+
+
+def _create_chat_message(*, current_user: Account, app_model: App):
+    raw_payload = console_ns.payload or {}
+    args_model = ChatMessagePayload.model_validate(raw_payload)
+    args = args_model.model_dump(exclude_none=True, by_alias=True)
+
+    streaming = _resolve_debugger_chat_streaming(
+        app_mode=AppMode.value_of(app_model.mode),
+        response_mode=args_model.response_mode,
+        response_mode_provided=isinstance(raw_payload, dict) and "response_mode" in raw_payload,
+    )
+    if AppMode.value_of(app_model.mode) == AppMode.AGENT:
+        args["response_mode"] = "streaming"
+    args["auto_generate_name"] = False
+
+    external_trace_id = get_external_trace_id(request)
+    if external_trace_id:
+        args["external_trace_id"] = external_trace_id
+
+    try:
+        response = AppGenerateService.generate(
+            app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.DEBUGGER, streaming=streaming
         )
 
-        return {"result": "success"}, 200
+        return helper.compact_generate_response(response)
+    except services.errors.conversation.ConversationNotExistsError:
+        raise NotFound("Conversation Not Exists.")
+    except services.errors.conversation.ConversationCompletedError:
+        raise ConversationCompletedError()
+    except services.errors.app_model_config.AppModelConfigBrokenError:
+        logger.exception("App model config broken.")
+        raise AppUnavailableError()
+    except ProviderTokenNotInitError as ex:
+        raise ProviderNotInitializeError(ex.description)
+    except QuotaExceededError:
+        raise ProviderQuotaExceededError()
+    except ModelCurrentlyNotSupportError:
+        raise ProviderModelCurrentlyNotSupportError()
+    except InvokeRateLimitError as ex:
+        raise InvokeRateLimitHttpError(ex.description)
+    except InvokeError as e:
+        raise CompletionRequestError(e.description)
+    except ValueError as e:
+        raise e
+    except Exception as e:
+        logger.exception("internal server error.")
+        raise InternalServerError()
+
+
+def _stop_chat_message(*, current_user_id: str, app_model: App, task_id: str):
+    AppTaskService.stop_task(
+        task_id=task_id,
+        invoke_from=InvokeFrom.DEBUGGER,
+        user_id=current_user_id,
+        app_mode=AppMode.value_of(app_model.mode),
+    )
+
+    return {"result": "success"}, 200

api/controllers/console/app/message.py

@@ -13,6 +13,7 @@ from controllers.common.controller_schemas import MessageFeedbackPayload as _Mes
 from controllers.common.fields import SimpleResultResponse, TextFileResponse
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.error import (
     CompletionRequestError,
     ProviderModelCurrentlyNotSupportError,
@@ -25,6 +26,7 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
 )
 from core.app.entities.app_invoke_entities import InvokeFrom
@@ -183,67 +185,25 @@ class ChatMessageListApi(Resource):
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     def get(self, app_model: App):
-        args = ChatMessagesQuery.model_validate(request.args.to_dict())
+        return _list_chat_messages(app_model=app_model)
 
-        conversation = db.session.scalar(
-            select(Conversation)
-            .where(Conversation.id == args.conversation_id, Conversation.app_id == app_model.id)
-            .limit(1)
-        )
 
-        if not conversation:
-            raise NotFound("Conversation Not Exists.")
-
-        if args.first_id:
-            first_message = db.session.scalar(
-                select(Message).where(Message.conversation_id == conversation.id, Message.id == args.first_id).limit(1)
-            )
-
-            if not first_message:
-                raise NotFound("First message not found")
-
-            history_messages = db.session.scalars(
-                select(Message)
-                .where(
-                    Message.conversation_id == conversation.id,
-                    Message.created_at < first_message.created_at,
-                    Message.id != first_message.id,
-                )
-                .order_by(Message.created_at.desc())
-                .limit(args.limit)
-            ).all()
-        else:
-            history_messages = db.session.scalars(
-                select(Message)
-                .where(Message.conversation_id == conversation.id)
-                .order_by(Message.created_at.desc())
-                .limit(args.limit)
-            ).all()
-
-        # Initialize has_more based on whether we have a full page
-        if len(history_messages) == args.limit:
-            current_page_first_message = history_messages[-1]
-            # Check if there are more messages before the current page
-            has_more = db.session.scalar(
-                select(
-                    exists().where(
-                        Message.conversation_id == conversation.id,
-                        Message.created_at < current_page_first_message.created_at,
-                        Message.id != current_page_first_message.id,
-                    )
-                )
-            )
-        else:
-            # If we don't have a full page, there are no more messages
-            has_more = False
-
-        history_messages = list(reversed(history_messages))
-        attach_message_extra_contents(history_messages)
-
-        return MessageInfiniteScrollPaginationResponse.model_validate(
-            InfiniteScrollPagination(data=history_messages, limit=args.limit, has_more=has_more),
-            from_attributes=True,
-        ).model_dump(mode="json")
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages")
+class AgentChatMessageListApi(Resource):
+    @console_ns.doc("list_agent_chat_messages")
+    @console_ns.doc(description="Get Agent App chat messages for a conversation with pagination")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.doc(params=query_params_from_model(ChatMessagesQuery))
+    @console_ns.response(200, "Success", console_ns.models[MessageInfiniteScrollPaginationResponse.__name__])
+    @console_ns.response(404, "Agent or conversation not found")
+    @login_required
+    @account_initialization_required
+    @setup_required
+    @edit_permission_required
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _list_chat_messages(app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/feedbacks")
@@ -261,44 +221,25 @@ class MessageFeedbackApi(Resource):
     @account_initialization_required
     @with_current_user
     def post(self, current_user: Account, app_model: App):
-        args = MessageFeedbackPayload.model_validate(console_ns.payload)
+        return _update_message_feedback(current_user=current_user, app_model=app_model)
 
-        message_id = str(args.message_id)
 
-        message = db.session.scalar(
-            select(Message).where(Message.id == message_id, Message.app_id == app_model.id).limit(1)
-        )
-
-        if not message:
-            raise NotFound("Message Not Exists.")
-
-        feedback = message.admin_feedback
-
-        if not args.rating and feedback:
-            db.session.delete(feedback)
-        elif args.rating and feedback:
-            feedback.rating = FeedbackRating(args.rating)
-            feedback.content = args.content
-        elif not args.rating and not feedback:
-            raise ValueError("rating cannot be None when feedback not exists")
-        else:
-            rating_value = args.rating
-            if rating_value is None:
-                raise ValueError("rating is required to create feedback")
-            feedback = MessageFeedback(
-                app_id=app_model.id,
-                conversation_id=message.conversation_id,
-                message_id=message.id,
-                rating=FeedbackRating(rating_value),
-                content=args.content,
-                from_source=FeedbackFromSource.ADMIN,
-                from_account_id=current_user.id,
-            )
-            db.session.add(feedback)
-
-        db.session.commit()
-
-        return {"result": "success"}
+@console_ns.route("/agent/<uuid:agent_id>/feedbacks")
+class AgentMessageFeedbackApi(Resource):
+    @console_ns.doc("create_agent_message_feedback")
+    @console_ns.doc(description="Create or update Agent App message feedback")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.expect(console_ns.models[MessageFeedbackPayload.__name__])
+    @console_ns.response(200, "Feedback updated successfully", console_ns.models[SimpleResultResponse.__name__])
+    @console_ns.response(404, "Agent or message not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _update_message_feedback(current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotations/count")
@@ -340,31 +281,28 @@ class MessageSuggestedQuestionApi(Resource):
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user
     def get(self, current_user: Account, app_model: App, message_id: UUID):
-        message_id_str = str(message_id)
+        return _get_message_suggested_questions(current_user=current_user, app_model=app_model, message_id=message_id)
 
-        try:
-            questions = MessageService.get_suggested_questions_after_answer(
-                app_model=app_model, message_id=message_id_str, user=current_user, invoke_from=InvokeFrom.DEBUGGER
-            )
-        except MessageNotExistsError:
-            raise NotFound("Message not found")
-        except ConversationNotExistsError:
-            raise NotFound("Conversation not found")
-        except ProviderTokenNotInitError as ex:
-            raise ProviderNotInitializeError(ex.description)
-        except QuotaExceededError:
-            raise ProviderQuotaExceededError()
-        except ModelCurrentlyNotSupportError:
-            raise ProviderModelCurrentlyNotSupportError()
-        except InvokeError as e:
-            raise CompletionRequestError(e.description)
-        except SuggestedQuestionsAfterAnswerDisabledError:
-            raise AppSuggestedQuestionsAfterAnswerDisabledError()
-        except Exception:
-            logger.exception("internal server error.")
-            raise InternalServerError()
 
-        return {"data": questions}
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages/<uuid:message_id>/suggested-questions")
+class AgentMessageSuggestedQuestionApi(Resource):
+    @console_ns.doc("get_agent_message_suggested_questions")
+    @console_ns.doc(description="Get suggested questions for an Agent App message")
+    @console_ns.doc(params={"agent_id": "Agent ID", "message_id": "Message ID"})
+    @console_ns.response(
+        200,
+        "Suggested questions retrieved successfully",
+        console_ns.models[SuggestedQuestionsResponse.__name__],
+    )
+    @console_ns.response(404, "Agent, message, or conversation not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user: Account, agent_id: UUID, message_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _get_message_suggested_questions(current_user=current_user, app_model=app_model, message_id=message_id)
 
 
 @console_ns.route("/apps/<uuid:app_id>/feedbacks/export")
@@ -423,14 +361,167 @@ class MessageApi(Resource):
     @login_required
     @account_initialization_required
     def get(self, app_model: App, message_id: UUID):
-        message_id_str = str(message_id)
+        return _get_message_detail(app_model=app_model, message_id=message_id)
 
-        message = db.session.scalar(
-            select(Message).where(Message.id == message_id_str, Message.app_id == app_model.id).limit(1)
+
+@console_ns.route("/agent/<uuid:agent_id>/messages/<uuid:message_id>")
+class AgentMessageApi(Resource):
+    @console_ns.doc("get_agent_message")
+    @console_ns.doc(description="Get Agent App message details by ID")
+    @console_ns.doc(params={"agent_id": "Agent ID", "message_id": "Message ID"})
+    @console_ns.response(200, "Message retrieved successfully", console_ns.models[MessageDetailResponse.__name__])
+    @console_ns.response(404, "Agent or message not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, agent_id: UUID, message_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _get_message_detail(app_model=app_model, message_id=message_id)
+
+
+def _list_chat_messages(*, app_model: App):
+    args = ChatMessagesQuery.model_validate(request.args.to_dict())
+
+    conversation = db.session.scalar(
+        select(Conversation)
+        .where(Conversation.id == args.conversation_id, Conversation.app_id == app_model.id)
+        .limit(1)
+    )
+
+    if not conversation:
+        raise NotFound("Conversation Not Exists.")
+
+    if args.first_id:
+        first_message = db.session.scalar(
+            select(Message).where(Message.conversation_id == conversation.id, Message.id == args.first_id).limit(1)
         )
 
-        if not message:
-            raise NotFound("Message Not Exists.")
+        if not first_message:
+            raise NotFound("First message not found")
 
-        attach_message_extra_contents([message])
-        return MessageDetailResponse.model_validate(message, from_attributes=True).model_dump(mode="json")
+        history_messages = db.session.scalars(
+            select(Message)
+            .where(
+                Message.conversation_id == conversation.id,
+                Message.created_at < first_message.created_at,
+                Message.id != first_message.id,
+            )
+            .order_by(Message.created_at.desc())
+            .limit(args.limit)
+        ).all()
+    else:
+        history_messages = db.session.scalars(
+            select(Message)
+            .where(Message.conversation_id == conversation.id)
+            .order_by(Message.created_at.desc())
+            .limit(args.limit)
+        ).all()
+
+    # Initialize has_more based on whether we have a full page
+    if len(history_messages) == args.limit:
+        current_page_first_message = history_messages[-1]
+        # Check if there are more messages before the current page
+        has_more = db.session.scalar(
+            select(
+                exists().where(
+                    Message.conversation_id == conversation.id,
+                    Message.created_at < current_page_first_message.created_at,
+                    Message.id != current_page_first_message.id,
+                )
+            )
+        )
+    else:
+        # If we don't have a full page, there are no more messages
+        has_more = False
+
+    history_messages = list(reversed(history_messages))
+    attach_message_extra_contents(history_messages)
+
+    return MessageInfiniteScrollPaginationResponse.model_validate(
+        InfiniteScrollPagination(data=history_messages, limit=args.limit, has_more=has_more),
+        from_attributes=True,
+    ).model_dump(mode="json")
+
+
+def _update_message_feedback(*, current_user: Account, app_model: App):
+    args = MessageFeedbackPayload.model_validate(console_ns.payload)
+
+    message_id = str(args.message_id)
+
+    message = db.session.scalar(
+        select(Message).where(Message.id == message_id, Message.app_id == app_model.id).limit(1)
+    )
+
+    if not message:
+        raise NotFound("Message Not Exists.")
+
+    feedback = message.admin_feedback
+
+    if not args.rating and feedback:
+        db.session.delete(feedback)
+    elif args.rating and feedback:
+        feedback.rating = FeedbackRating(args.rating)
+        feedback.content = args.content
+    elif not args.rating and not feedback:
+        raise ValueError("rating cannot be None when feedback not exists")
+    else:
+        rating_value = args.rating
+        if rating_value is None:
+            raise ValueError("rating is required to create feedback")
+        feedback = MessageFeedback(
+            app_id=app_model.id,
+            conversation_id=message.conversation_id,
+            message_id=message.id,
+            rating=FeedbackRating(rating_value),
+            content=args.content,
+            from_source=FeedbackFromSource.ADMIN,
+            from_account_id=current_user.id,
+        )
+        db.session.add(feedback)
+
+    db.session.commit()
+
+    return {"result": "success"}
+
+
+def _get_message_suggested_questions(*, current_user: Account, app_model: App, message_id: UUID):
+    message_id_str = str(message_id)
+
+    try:
+        questions = MessageService.get_suggested_questions_after_answer(
+            app_model=app_model, message_id=message_id_str, user=current_user, invoke_from=InvokeFrom.DEBUGGER
+        )
+    except MessageNotExistsError:
+        raise NotFound("Message not found")
+    except ConversationNotExistsError:
+        raise NotFound("Conversation not found")
+    except ProviderTokenNotInitError as ex:
+        raise ProviderNotInitializeError(ex.description)
+    except QuotaExceededError:
+        raise ProviderQuotaExceededError()
+    except ModelCurrentlyNotSupportError:
+        raise ProviderModelCurrentlyNotSupportError()
+    except InvokeError as e:
+        raise CompletionRequestError(e.description)
+    except SuggestedQuestionsAfterAnswerDisabledError:
+        raise AppSuggestedQuestionsAfterAnswerDisabledError()
+    except Exception:
+        logger.exception("internal server error.")
+        raise InternalServerError()
+
+    return {"data": questions}
+
+
+def _get_message_detail(*, app_model: App, message_id: UUID):
+    message_id_str = str(message_id)
+
+    message = db.session.scalar(
+        select(Message).where(Message.id == message_id_str, Message.app_id == app_model.id).limit(1)
+    )
+
+    if not message:
+        raise NotFound("Message Not Exists.")
+
+    attach_message_extra_contents([message])
+    return MessageDetailResponse.model_validate(message, from_attributes=True).model_dump(mode="json")

api/controllers/console/app/workflow.py

@@ -2,12 +2,12 @@ import json
 import logging
 from collections.abc import Sequence
 from datetime import datetime
-from typing import Any, NotRequired, TypedDict
+from typing import Any, NotRequired, TypedDict, cast
 
 from flask import abort, request
 from flask_restx import Resource, fields
 from pydantic import AliasChoices, BaseModel, Field, RootModel, ValidationError, field_validator
-from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import Session, sessionmaker
 from werkzeug.exceptions import BadRequest, Forbidden, InternalServerError, NotFound
 
 import services
@@ -449,8 +449,16 @@ class DraftWorkflowApi(Resource):
         if not workflow:
             raise DraftWorkflowNotExist()
 
-        # return workflow, if not found, return 404
-        return dump_response(WorkflowResponse, workflow)
+        from services.agent.workflow_publish_service import WorkflowAgentPublishService
+
+        # Return workflow with response-only Agent node job projection so the
+        # front-end can treat draft graph node data as the editing source.
+        response = WorkflowResponse.model_validate(workflow, from_attributes=True).model_dump(mode="json")
+        response["graph"] = WorkflowAgentPublishService.project_draft_bindings_to_graph(
+            session=cast(Session, db.session),
+            draft_workflow=workflow,
+        )
+        return response
 
     @setup_required
     @login_required

api/controllers/console/datasets/rag_pipeline/rag_pipeline_workflow.py

@@ -994,7 +994,7 @@ class RagPipelineTransformApi(Resource):
 
         dataset_id_str = str(dataset_id)
         rag_pipeline_transform_service = RagPipelineTransformService()
-        result = rag_pipeline_transform_service.transform_dataset(dataset_id_str)
+        result = rag_pipeline_transform_service.transform_dataset(dataset_id_str, db.session)
         return result
 
 

api/controllers/console/explore/recommended_app.py

@@ -9,6 +9,7 @@ from constants.languages import languages
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import account_initialization_required, with_current_user
+from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.helper import build_icon_url
 from libs.login import login_required
@@ -65,6 +66,10 @@ class RecommendedAppListResponse(ResponseModel):
     categories: list[str]
 
 
+class LearnDifyAppListResponse(ResponseModel):
+    recommended_apps: list[RecommendedAppResponse]
+
+
 class RecommendedAppDetailResponse(RootModel[dict[str, Any]]):
     root: dict[str, Any]
 
@@ -75,10 +80,19 @@ register_schema_models(
     RecommendedAppInfoResponse,
     RecommendedAppResponse,
     RecommendedAppListResponse,
+    LearnDifyAppListResponse,
 )
 register_response_schema_models(console_ns, RecommendedAppDetailResponse)
 
 
+def _resolve_language(language: str | None, user: Account) -> str:
+    if language and language in languages:
+        return language
+    if user.interface_language:
+        return user.interface_language
+    return languages[0]
+
+
 @console_ns.route("/explore/apps")
 class RecommendedAppListApi(Resource):
     @console_ns.doc(params=query_params_from_model(RecommendedAppsQuery))
@@ -89,16 +103,27 @@ class RecommendedAppListApi(Resource):
     def get(self, current_user: Account):
         # language args
         args = RecommendedAppsQuery.model_validate(request.args.to_dict(flat=True))
-        language = args.language
-        if language and language in languages:
-            language_prefix = language
-        elif current_user.interface_language:
-            language_prefix = current_user.interface_language
-        else:
-            language_prefix = languages[0]
+        language_prefix = _resolve_language(args.language, current_user)
 
         return RecommendedAppListResponse.model_validate(
-            RecommendedAppService.get_recommended_apps_and_categories(language_prefix),
+            RecommendedAppService.get_recommended_apps_and_categories(db.session, language_prefix),
+            from_attributes=True,
+        ).model_dump(mode="json")
+
+
+@console_ns.route("/explore/apps/learn-dify")
+class LearnDifyAppListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(RecommendedAppsQuery))
+    @console_ns.response(200, "Success", console_ns.models[LearnDifyAppListResponse.__name__])
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    def get(self, current_user: Account):
+        args = RecommendedAppsQuery.model_validate(request.args.to_dict(flat=True))
+        language_prefix = _resolve_language(args.language, current_user)
+
+        return LearnDifyAppListResponse.model_validate(
+            RecommendedAppService.get_learn_dify_apps(db.session, language_prefix),
             from_attributes=True,
         ).model_dump(mode="json")
 
@@ -109,4 +134,4 @@ class RecommendedAppApi(Resource):
     @login_required
     @account_initialization_required
     def get(self, app_id: UUID):
-        return RecommendedAppService.get_recommend_app_detail(str(app_id))
+        return RecommendedAppService.get_recommend_app_detail(db.session, str(app_id))

api/controllers/console/explore/trial.py

@@ -223,7 +223,7 @@ class TrialAppWorkflowRunApi(TrialAppResource):
             response = AppGenerateService.generate(
                 app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.EXPLORE, streaming=True
             )
-            RecommendedAppService.add_trial_app_record(app_id, user_id)
+            RecommendedAppService.add_trial_app_record(db.session, app_id, user_id)
             return helper.compact_generate_response(response)
         except ProviderTokenNotInitError as ex:
             raise ProviderNotInitializeError(ex.description)
@@ -296,7 +296,7 @@ class TrialChatApi(TrialAppResource):
             response = AppGenerateService.generate(
                 app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.EXPLORE, streaming=True
             )
-            RecommendedAppService.add_trial_app_record(app_id, user_id)
+            RecommendedAppService.add_trial_app_record(db.session, app_id, user_id)
             return helper.compact_generate_response(response)
         except services.errors.conversation.ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
@@ -373,7 +373,7 @@ class TrialChatAudioApi(TrialAppResource):
             user_id = current_user.id
 
             response = AudioService.transcript_asr(app_model=app_model, file=file, end_user=None)
-            RecommendedAppService.add_trial_app_record(app_id, user_id)
+            RecommendedAppService.add_trial_app_record(db.session, app_id, user_id)
             return response
         except services.errors.app_model_config.AppModelConfigBrokenError:
             logger.exception("App model config broken.")
@@ -420,7 +420,7 @@ class TrialChatTextApi(TrialAppResource):
             user_id = current_user.id
 
             response = AudioService.transcript_tts(app_model=app_model, text=text, voice=voice, message_id=message_id)
-            RecommendedAppService.add_trial_app_record(app_id, user_id)
+            RecommendedAppService.add_trial_app_record(db.session, app_id, user_id)
             return response
         except services.errors.app_model_config.AppModelConfigBrokenError:
             logger.exception("App model config broken.")
@@ -473,7 +473,7 @@ class TrialCompletionApi(TrialAppResource):
                 app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.EXPLORE, streaming=streaming
             )
 
-            RecommendedAppService.add_trial_app_record(app_id, user_id)
+            RecommendedAppService.add_trial_app_record(db.session, app_id, user_id)
             return helper.compact_generate_response(response)
         except services.errors.conversation.ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")

api/controllers/console/tag/tags.py

@@ -16,6 +16,7 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
+from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.login import login_required
 from models import Account
@@ -101,7 +102,7 @@ class TagListApi(Resource):
     def get(self, current_tenant_id: str):
         raw_args = request.args.to_dict()
         param = TagListQueryParam.model_validate(raw_args)
-        tags = TagService.get_tags(param.type, current_tenant_id, param.keyword)
+        tags = TagService.get_tags(db.session(), param.type, current_tenant_id, param.keyword)
 
         serialized_tags = [
             TagResponse.model_validate(tag, from_attributes=True).model_dump(mode="json") for tag in tags

api/controllers/console/workspace/plugin.py

@@ -1,10 +1,11 @@
 import io
 from collections.abc import Mapping
-from typing import Any, Literal
+from datetime import datetime
+from typing import Any, Literal, TypedDict
 
 from flask import request, send_file
 from flask_restx import Resource
-from pydantic import BaseModel, Field, RootModel
+from pydantic import BaseModel, ConfigDict, Field, RootModel
 from werkzeug.datastructures import FileStorage
 from werkzeug.exceptions import Forbidden
 
@@ -26,15 +27,33 @@ from controllers.console.wraps import (
     with_current_user,
     with_current_user_id,
 )
+from core.helper.position_helper import is_filtered
+from core.plugin.entities.plugin import PluginCategory, PluginInstallationSource
 from core.plugin.impl.exc import PluginDaemonClientSideError
 from core.plugin.plugin_service import PluginService
+from core.tools.builtin_tool.providers._positions import BuiltinToolProviderSort
+from core.tools.entities.common_entities import I18nObject
+from core.tools.entities.tool_entities import ToolProviderType
+from core.tools.tool_manager import ToolManager
 from fields.base import ResponseModel
 from graphon.model_runtime.utils.encoders import jsonable_encoder
+from libs.helper import dump_response
 from libs.login import login_required
 from models.account import Account, TenantPluginAutoUpgradeStrategy, TenantPluginPermission
+from models.provider_ids import ToolProviderID
+from services.entities.model_provider_entities import ProviderEntityResponse
 from services.plugin.plugin_auto_upgrade_service import PluginAutoUpgradeService
 from services.plugin.plugin_parameter_service import PluginParameterService
 from services.plugin.plugin_permission_service import PluginPermissionService
+from services.tools.tools_transform_service import ToolTransformService
+
+
+class AutoUpgradeSettingsResponse(TypedDict):
+    strategy_setting: TenantPluginAutoUpgradeStrategy.StrategySetting
+    upgrade_time_of_day: int
+    upgrade_mode: TenantPluginAutoUpgradeStrategy.UpgradeMode
+    exclude_plugins: list[str]
+    include_plugins: list[str]
 
 
 class ParserList(BaseModel):
@@ -42,6 +61,11 @@ class ParserList(BaseModel):
     page_size: int = Field(default=256, ge=1, le=256, description="Page size (1-256)")
 
 
+class PluginCategoryListQuery(BaseModel):
+    page: int = Field(default=1, ge=1, description="Page number")
+    page_size: int = Field(default=256, ge=1, le=256, description="Page size (1-256)")
+
+
 class ParserLatest(BaseModel):
     plugin_ids: list[str]
 
@@ -100,8 +124,8 @@ class ParserUninstall(BaseModel):
 
 
 class ParserPermissionChange(BaseModel):
-    install_permission: TenantPluginPermission.InstallPermission
-    debug_permission: TenantPluginPermission.DebugPermission
+    install_permission: TenantPluginPermission.InstallPermission = TenantPluginPermission.InstallPermission.EVERYONE
+    debug_permission: TenantPluginPermission.DebugPermission = TenantPluginPermission.DebugPermission.EVERYONE
 
 
 class ParserDynamicOptions(BaseModel):
@@ -137,13 +161,64 @@ class PluginAutoUpgradeSettingsPayload(BaseModel):
     include_plugins: list[str] = Field(default_factory=list)
 
 
-class ParserPreferencesChange(BaseModel):
-    permission: PluginPermissionSettingsPayload
+class PluginAutoUpgradeChangeResponse(ResponseModel):
+    success: bool
+    message: str | None = None
+
+
+class PluginAutoUpgradeSettingsResponseModel(ResponseModel):
+    strategy_setting: TenantPluginAutoUpgradeStrategy.StrategySetting
+    upgrade_time_of_day: int
+    upgrade_mode: TenantPluginAutoUpgradeStrategy.UpgradeMode
+    exclude_plugins: list[str]
+    include_plugins: list[str]
+
+
+class PluginAutoUpgradeFetchResponse(ResponseModel):
+    category: TenantPluginAutoUpgradeStrategy.PluginCategory
+    auto_upgrade: PluginAutoUpgradeSettingsResponseModel
+
+
+class PluginDeclarationResponse(ResponseModel):
+    version: str
+    author: str | None
+    name: str
+    description: I18nObject
+    icon: str
+    icon_dark: str | None = None
+    label: I18nObject
+    category: PluginCategory
+    created_at: datetime
+    resource: Mapping[str, Any]
+    plugins: Mapping[str, list[str] | None]
+    tags: list[str] = Field(default_factory=list)
+    repo: str | None = None
+    verified: bool = False
+    tool: Mapping[str, Any] | None = None
+    model: ProviderEntityResponse | None = None
+    endpoint: Mapping[str, Any] | None = None
+    agent_strategy: Mapping[str, Any] | None = None
+    datasource: Mapping[str, Any] | None = None
+    trigger: Mapping[str, Any] | None = None
+    meta: Mapping[str, Any]
+
+
+class ParserAutoUpgradeChange(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    category: TenantPluginAutoUpgradeStrategy.PluginCategory
     auto_upgrade: PluginAutoUpgradeSettingsPayload
 
 
+class ParserAutoUpgradeFetch(BaseModel):
+    category: TenantPluginAutoUpgradeStrategy.PluginCategory
+
+
 class ParserExcludePlugin(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
     plugin_id: str
+    category: TenantPluginAutoUpgradeStrategy.PluginCategory
 
 
 class ParserReadme(BaseModel):
@@ -157,6 +232,63 @@ class PluginDebuggingKeyResponse(ResponseModel):
     port: int
 
 
+class PluginCategoryInstalledPluginResponse(ResponseModel):
+    id: str
+    name: str
+    tenant_id: str
+    plugin_id: str
+    plugin_unique_identifier: str
+    endpoints_active: int
+    endpoints_setups: int
+    installation_id: str
+    declaration: PluginDeclarationResponse
+    runtime_type: str
+    version: str
+    created_at: datetime
+    updated_at: datetime
+    source: PluginInstallationSource
+    checksum: str
+    meta: Mapping[str, Any]
+
+
+class PluginCategoryBuiltinToolResponse(ResponseModel):
+    model_config = ConfigDict(extra="allow")
+
+    author: str
+    name: str
+    label: I18nObject
+    description: I18nObject
+    parameters: list[Mapping[str, Any]] | None = None
+    labels: list[str]
+    output_schema: Mapping[str, object]
+
+
+class PluginCategoryBuiltinToolProviderResponse(ResponseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: str
+    author: str
+    name: str
+    plugin_id: str | None
+    plugin_unique_identifier: str | None
+    description: I18nObject
+    icon: str | Mapping[str, str]
+    icon_dark: str | Mapping[str, str] | None
+    label: I18nObject
+    type: ToolProviderType
+    team_credentials: Mapping[str, object]
+    is_team_authorization: bool
+    allow_delete: bool
+    tools: list[PluginCategoryBuiltinToolResponse]
+    labels: list[str]
+
+
+class PluginCategoryListResponse(ResponseModel):
+    plugins: list[PluginCategoryInstalledPluginResponse]
+    builtin_tools: list[PluginCategoryBuiltinToolProviderResponse]
+    has_more: bool
+
+
 class PluginDaemonOperationResponse(RootModel[Any]):
     root: Any
 
@@ -200,11 +332,6 @@ class PluginOperationSuccessResponse(ResponseModel):
     message: str | None = None
 
 
-class PluginPreferencesResponse(ResponseModel):
-    permission: PluginPermissionSettingsPayload
-    auto_upgrade: PluginAutoUpgradeSettingsPayload
-
-
 class PluginReadmeResponse(ResponseModel):
     readme: str
 
@@ -212,6 +339,7 @@ class PluginReadmeResponse(ResponseModel):
 register_schema_models(
     console_ns,
     ParserList,
+    PluginCategoryListQuery,
     PluginAutoUpgradeSettingsPayload,
     PluginPermissionSettingsPayload,
     ParserLatest,
@@ -228,13 +356,21 @@ register_schema_models(
     ParserPermissionChange,
     ParserDynamicOptions,
     ParserDynamicOptionsWithCredentials,
-    ParserPreferencesChange,
+    ParserAutoUpgradeChange,
+    ParserAutoUpgradeFetch,
     ParserExcludePlugin,
     ParserReadme,
 )
 register_response_schema_models(
     console_ns,
+    PluginAutoUpgradeChangeResponse,
+    PluginAutoUpgradeFetchResponse,
+    PluginAutoUpgradeSettingsResponseModel,
     BinaryFileResponse,
+    PluginCategoryBuiltinToolProviderResponse,
+    PluginCategoryBuiltinToolResponse,
+    PluginCategoryInstalledPluginResponse,
+    PluginCategoryListResponse,
     PluginDaemonOperationResponse,
     PluginDebuggingKeyResponse,
     PluginDynamicOptionsResponse,
@@ -243,7 +379,6 @@ register_response_schema_models(
     PluginManifestResponse,
     PluginOperationSuccessResponse,
     PluginPermissionResponse,
-    PluginPreferencesResponse,
     PluginReadmeResponse,
     PluginTaskResponse,
     PluginTasksResponse,
@@ -254,12 +389,36 @@ register_response_schema_models(
 register_enum_models(
     console_ns,
     TenantPluginPermission.DebugPermission,
+    TenantPluginAutoUpgradeStrategy.PluginCategory,
     TenantPluginAutoUpgradeStrategy.UpgradeMode,
     TenantPluginAutoUpgradeStrategy.StrategySetting,
     TenantPluginPermission.InstallPermission,
 )
 
 
+def _default_auto_upgrade_settings(
+    tenant_id: str,
+    category: TenantPluginAutoUpgradeStrategy.PluginCategory,
+) -> AutoUpgradeSettingsResponse:
+    return {
+        "strategy_setting": PluginAutoUpgradeService.default_strategy_setting_for_category(category),
+        "upgrade_time_of_day": PluginAutoUpgradeService.default_upgrade_time_of_day(tenant_id),
+        "upgrade_mode": TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE,
+        "exclude_plugins": [],
+        "include_plugins": [],
+    }
+
+
+def _auto_upgrade_settings_to_dict(strategy: TenantPluginAutoUpgradeStrategy) -> AutoUpgradeSettingsResponse:
+    return {
+        "strategy_setting": strategy.strategy_setting,
+        "upgrade_time_of_day": strategy.upgrade_time_of_day,
+        "upgrade_mode": strategy.upgrade_mode,
+        "exclude_plugins": strategy.exclude_plugins,
+        "include_plugins": strategy.include_plugins,
+    }
+
+
 def _read_upload_content(file: FileStorage, max_size: int) -> bytes:
     """
     Read the uploaded file and validate its actual size before delegating to the plugin service.
@@ -274,6 +433,33 @@ def _read_upload_content(file: FileStorage, max_size: int) -> bytes:
     return content
 
 
+def _list_hardcoded_builtin_tool_providers(tenant_id: str) -> list[dict[str, Any]]:
+    db_builtin_providers = {
+        str(ToolProviderID(provider.provider)): provider
+        for provider in ToolManager.list_default_builtin_providers(tenant_id)
+    }
+    builtin_providers = []
+
+    for provider in ToolManager.list_hardcoded_providers():
+        if is_filtered(
+            include_set=dify_config.POSITION_TOOL_INCLUDES_SET,
+            exclude_set=dify_config.POSITION_TOOL_EXCLUDES_SET,
+            data=provider,
+            name_func=lambda provider_controller: provider_controller.entity.identity.name,
+        ):
+            continue
+
+        user_provider = ToolTransformService.builtin_provider_to_user_provider(
+            provider_controller=provider,
+            db_provider=db_builtin_providers.get(provider.entity.identity.name),
+            decrypt_credentials=False,
+        )
+        ToolTransformService.repack_provider(tenant_id=tenant_id, provider=user_provider)
+        builtin_providers.append(user_provider)
+
+    return [provider.to_dict() for provider in BuiltinToolProviderSort.sort(builtin_providers)]
+
+
 @console_ns.route("/workspaces/current/plugin/debugging-key")
 class PluginDebuggingKeyApi(Resource):
     @console_ns.response(200, "Success", console_ns.models[PluginDebuggingKeyResponse.__name__])
@@ -312,6 +498,41 @@ class PluginListApi(Resource):
         return jsonable_encoder({"plugins": plugins_with_total.list, "total": plugins_with_total.total})
 
 
+@console_ns.route("/workspaces/current/plugin/<string:category>/list")
+class PluginCategoryListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(PluginCategoryListQuery))
+    @console_ns.response(200, "Success", console_ns.models[PluginCategoryListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, category: str):
+        args = PluginCategoryListQuery.model_validate(request.args.to_dict(flat=True))
+
+        try:
+            plugin_category = PluginCategory(category)
+        except ValueError:
+            return {"code": "invalid_param", "message": "invalid plugin category"}, 400
+
+        try:
+            plugins = PluginService.list_by_category(tenant_id, plugin_category, args.page, args.page_size)
+        except PluginDaemonClientSideError as e:
+            return {"code": "plugin_error", "message": e.description}, 400
+
+        builtin_tools = []
+        if plugin_category == PluginCategory.Tool:
+            builtin_tools = _list_hardcoded_builtin_tool_providers(tenant_id)
+
+        return dump_response(
+            PluginCategoryListResponse,
+            {
+                "plugins": jsonable_encoder(plugins.list),
+                "builtin_tools": builtin_tools,
+                "has_more": plugins.has_more,
+            },
+        )
+
+
 @console_ns.route("/workspaces/current/plugin/list/latest-versions")
 class PluginListLatestVersionsApi(Resource):
     @console_ns.expect(console_ns.models[ParserLatest.__name__])
@@ -713,11 +934,13 @@ class PluginChangePermissionApi(Resource):
 
         args = ParserPermissionChange.model_validate(console_ns.payload)
 
-        return {
-            "success": PluginPermissionService.change_permission(
-                tenant_id, args.install_permission, args.debug_permission
-            )
-        }
+        set_permission_result = PluginPermissionService.change_permission(
+            tenant_id, args.install_permission, args.debug_permission
+        )
+        if not set_permission_result:
+            return jsonable_encoder({"success": False, "message": "Failed to set permission"})
+
+        return jsonable_encoder({"success": True})
 
 
 @console_ns.route("/workspaces/current/plugin/permission/fetch")
@@ -806,10 +1029,10 @@ class PluginFetchDynamicSelectOptionsWithCredentialsApi(Resource):
         return jsonable_encoder({"options": options})
 
 
-@console_ns.route("/workspaces/current/plugin/preferences/change")
-class PluginChangePreferencesApi(Resource):
-    @console_ns.expect(console_ns.models[ParserPreferencesChange.__name__])
-    @console_ns.response(200, "Success", console_ns.models[PluginOperationSuccessResponse.__name__])
+@console_ns.route("/workspaces/current/plugin/auto-upgrade/change")
+class PluginChangeAutoUpgradeApi(Resource):
+    @console_ns.expect(console_ns.models[ParserAutoUpgradeChange.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginAutoUpgradeChangeResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -819,38 +1042,17 @@ class PluginChangePreferencesApi(Resource):
         if not user.is_admin_or_owner:
             raise Forbidden()
 
-        args = ParserPreferencesChange.model_validate(console_ns.payload)
-
-        permission = args.permission
-
-        install_permission = permission.install_permission
-        debug_permission = permission.debug_permission
+        args = ParserAutoUpgradeChange.model_validate(console_ns.payload)
 
         auto_upgrade = args.auto_upgrade
-
-        strategy_setting = auto_upgrade.strategy_setting
-        upgrade_time_of_day = auto_upgrade.upgrade_time_of_day
-        upgrade_mode = auto_upgrade.upgrade_mode
-        exclude_plugins = auto_upgrade.exclude_plugins
-        include_plugins = auto_upgrade.include_plugins
-
-        # set permission
-        set_permission_result = PluginPermissionService.change_permission(
-            tenant_id,
-            install_permission,
-            debug_permission,
-        )
-        if not set_permission_result:
-            return jsonable_encoder({"success": False, "message": "Failed to set permission"})
-
-        # set auto upgrade strategy
         set_auto_upgrade_strategy_result = PluginAutoUpgradeService.change_strategy(
             tenant_id,
-            strategy_setting,
-            upgrade_time_of_day,
-            upgrade_mode,
-            exclude_plugins,
-            include_plugins,
+            auto_upgrade.strategy_setting,
+            auto_upgrade.upgrade_time_of_day,
+            auto_upgrade.upgrade_mode,
+            auto_upgrade.exclude_plugins,
+            auto_upgrade.include_plugins,
+            category=args.category,
         )
         if not set_auto_upgrade_strategy_result:
             return jsonable_encoder({"success": False, "message": "Failed to set auto upgrade strategy"})
@@ -858,49 +1060,35 @@ class PluginChangePreferencesApi(Resource):
         return jsonable_encoder({"success": True})
 
 
-@console_ns.route("/workspaces/current/plugin/preferences/fetch")
-class PluginFetchPreferencesApi(Resource):
-    @console_ns.response(200, "Success", console_ns.models[PluginPreferencesResponse.__name__])
+@console_ns.route("/workspaces/current/plugin/auto-upgrade/fetch")
+class PluginFetchAutoUpgradeApi(Resource):
+    @console_ns.doc(params=query_params_from_model(ParserAutoUpgradeFetch))
+    @console_ns.response(200, "Success", console_ns.models[PluginAutoUpgradeFetchResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_tenant_id
     def get(self, tenant_id: str):
-        permission = PluginPermissionService.get_permission(tenant_id)
-        permission_dict = {
-            "install_permission": TenantPluginPermission.InstallPermission.EVERYONE,
-            "debug_permission": TenantPluginPermission.DebugPermission.EVERYONE,
-        }
+        args = ParserAutoUpgradeFetch.model_validate(request.args.to_dict(flat=True))
+        auto_upgrade = PluginAutoUpgradeService.get_strategy(tenant_id, args.category)
+        auto_upgrade_dict = (
+            _auto_upgrade_settings_to_dict(auto_upgrade)
+            if auto_upgrade
+            else _default_auto_upgrade_settings(tenant_id, args.category)
+        )
 
-        if permission:
-            permission_dict["install_permission"] = permission.install_permission
-            permission_dict["debug_permission"] = permission.debug_permission
-
-        auto_upgrade = PluginAutoUpgradeService.get_strategy(tenant_id)
-        auto_upgrade_dict = {
-            "strategy_setting": TenantPluginAutoUpgradeStrategy.StrategySetting.DISABLED,
-            "upgrade_time_of_day": 0,
-            "upgrade_mode": TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE,
-            "exclude_plugins": [],
-            "include_plugins": [],
-        }
-
-        if auto_upgrade:
-            auto_upgrade_dict = {
-                "strategy_setting": auto_upgrade.strategy_setting,
-                "upgrade_time_of_day": auto_upgrade.upgrade_time_of_day,
-                "upgrade_mode": auto_upgrade.upgrade_mode,
-                "exclude_plugins": auto_upgrade.exclude_plugins,
-                "include_plugins": auto_upgrade.include_plugins,
+        return jsonable_encoder(
+            {
+                "category": args.category,
+                "auto_upgrade": auto_upgrade_dict,
             }
-
-        return jsonable_encoder({"permission": permission_dict, "auto_upgrade": auto_upgrade_dict})
+        )
 
 
-@console_ns.route("/workspaces/current/plugin/preferences/autoupgrade/exclude")
+@console_ns.route("/workspaces/current/plugin/auto-upgrade/exclude")
 class PluginAutoUpgradeExcludePluginApi(Resource):
     @console_ns.expect(console_ns.models[ParserExcludePlugin.__name__])
-    @console_ns.response(200, "Success", console_ns.models[PluginOperationSuccessResponse.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SuccessResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -909,7 +1097,9 @@ class PluginAutoUpgradeExcludePluginApi(Resource):
         # exclude one single plugin
         args = ParserExcludePlugin.model_validate(console_ns.payload)
 
-        return jsonable_encoder({"success": PluginAutoUpgradeService.exclude_plugin(tenant_id, args.plugin_id)})
+        return jsonable_encoder(
+            {"success": PluginAutoUpgradeService.exclude_plugin(tenant_id, args.plugin_id, args.category)}
+        )
 
 
 @console_ns.route("/workspaces/current/plugin/readme")

api/controllers/console/workspace/workspace.py

@@ -31,9 +31,9 @@ from controllers.console.wraps import (
 from enums.cloud_plan import CloudPlan
 from extensions.ext_database import db
 from fields.base import ResponseModel
-from libs.helper import TimestampField, dump_response, to_timestamp
+from libs.helper import OptionalTimestampField, TimestampField, dump_response, to_timestamp
 from libs.login import login_required
-from models.account import Account, Tenant, TenantCustomConfigDict, TenantStatus
+from models.account import Account, Tenant, TenantAccountJoin, TenantCustomConfigDict, TenantStatus
 from services.account_service import TenantService
 from services.billing_service import BillingService, SubscriptionPlan
 from services.enterprise.enterprise_service import EnterpriseService
@@ -219,6 +219,7 @@ tenants_fields = {
     "plan": fields.String,
     "status": fields.String,
     "created_at": TimestampField,
+    "last_opened_at": OptionalTimestampField,
     "current": fields.Boolean,
 }
 
@@ -234,7 +235,12 @@ class TenantListApi(Resource):
     @with_current_user
     @with_current_tenant_id
     def get(self, current_tenant_id: str, current_user: Account):
-        tenants = TenantService.get_join_tenants(current_user)
+        tenant_rows: list[tuple[Tenant, TenantAccountJoin]] = [
+            (tenant, membership)
+            for tenant, membership in TenantService.get_workspaces_for_account(db.session, current_user.id)
+            if tenant.status == TenantStatus.NORMAL
+        ]
+        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.EDITION == "CLOUD" and dify_config.BILLING_ENABLED
@@ -247,7 +253,7 @@ class TenantListApi(Resource):
                 if not tenant_plans:
                     logger.warning("get_plan_bulk returned empty result, falling back to legacy feature path")
 
-        for tenant in tenants:
+        for tenant, membership in tenant_rows:
             plan: str = CloudPlan.SANDBOX
             if is_saas:
                 tenant_plan = tenant_plans.get(tenant.id)
@@ -266,6 +272,7 @@ class TenantListApi(Resource):
                 "name": tenant.name,
                 "status": tenant.status,
                 "created_at": tenant.created_at,
+                "last_opened_at": membership.last_opened_at,
                 "plan": plan,
                 "current": tenant.id == current_tenant_id if current_tenant_id else False,
             }

api/controllers/service_api/dataset/dataset.py

@@ -22,6 +22,7 @@ from controllers.service_api.wraps import (
 )
 from core.plugin.impl.model_runtime_factory import create_plugin_provider_manager
 from core.rag.index_processor.constant.index_type import IndexTechniqueType
+from extensions.ext_database import db
 from fields.base import ResponseModel
 from fields.dataset_fields import DatasetDetailResponse
 from graphon.model_runtime.entities.model_entities import ModelType
@@ -608,7 +609,7 @@ class DatasetTagsApi(DatasetApiResource):
         assert isinstance(current_user, Account)
         cid = current_user.current_tenant_id
         assert cid is not None
-        tags = TagService.get_tags("knowledge", cid)
+        tags = TagService.get_tags(db.session(), "knowledge", cid)
         return dump_response(KnowledgeTagListResponse, tags), 200
 
     @service_api_ns.expect(service_api_ns.models[TagCreatePayload.__name__])

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

@@ -1,6 +1,5 @@
 import json
 import logging
-import re
 import time
 from collections.abc import Callable, Generator, Mapping
 from contextlib import contextmanager
@@ -1010,11 +1009,7 @@ class AdvancedChatAppGenerateTaskPipeline(GraphRuntimeStateSupport):
         if message.status == MessageStatus.PAUSED:
             message.status = MessageStatus.NORMAL
 
-        # If there are assistant files, remove markdown image links from answer
         answer_text = self._task_state.answer
-        if self._recorded_files:
-            # Remove markdown image links since we're storing files separately
-            answer_text = re.sub(r"!\[.*?\]\(.*?\)", "", answer_text).strip()
 
         message.answer = answer_text
         message.updated_at = naive_utc_now()

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

@@ -158,6 +158,110 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         )
         return AgentAppGenerateResponseConverter.convert(response=response, invoke_from=invoke_from)
 
+    def resume_after_form_submission(
+        self,
+        *,
+        app_model: App,
+        user: Account | EndUser,
+        conversation_id: str,
+        invoke_from: InvokeFrom,
+    ) -> None:
+        """Resume an Agent App conversation after a submitted ask_human HITL form.
+
+        ENG-635: triggered by a background task (not an HTTP request). Runs one
+        blocking turn with no user query; the runner threads the human's reply
+        into the agent run as deferred_tool_results and the assistant answer is
+        persisted to the conversation. Live streaming to a reconnected client is
+        out of scope here — the message is persisted and can be re-fetched.
+        """
+        agent, snapshot, agent_soul = self._resolve_agent(app_model)
+        conversation = ConversationService.get_conversation(
+            app_model=app_model, conversation_id=conversation_id, user=user
+        )
+
+        app_config = AgentAppConfigManager.get_app_config(
+            app_model=app_model,
+            agent_soul=agent_soul,
+            app_model_config=app_model.app_model_config,
+            conversation=conversation,
+        )
+        model_conf = ModelConfigConverter.convert(app_config)
+        trace_manager = TraceQueueManager(app_model.id, user.id if isinstance(user, Account) else user.session_id)
+
+        # ENG-638: the agent backend requires the resume composition's layer
+        # names to match the suspended snapshot, which includes the per-turn
+        # user-prompt layer. So re-send the original user message (the paused
+        # turn's query); the continuation is driven by deferred_tool_results and
+        # the restored snapshot, not by re-processing this prompt. A blank prompt
+        # would drop the user-prompt layer and fail the snapshot match.
+        paused_message = db.session.scalar(
+            select(Message)
+            .where(Message.conversation_id == conversation.id, Message.query != "")
+            .order_by(Message.created_at.desc())
+            .limit(1)
+        )
+        resume_query = paused_message.query if paused_message and paused_message.query else "(resumed)"
+
+        application_generate_entity = AgentAppGenerateEntity(
+            task_id=str(uuid.uuid4()),
+            app_config=app_config,
+            model_conf=model_conf,
+            conversation_id=conversation.id,
+            # A resume carries no new user inputs; the human's answer is the
+            # submitted form, threaded in by the runner as deferred_tool_results.
+            # The query re-sends the paused turn's message (see above).
+            inputs={},
+            query=resume_query,
+            files=[],
+            parent_message_id=UUID_NIL,
+            user_id=user.id,
+            stream=False,
+            invoke_from=invoke_from,
+            extras={"auto_generate_conversation_name": False},
+            call_depth=0,
+            trace_manager=trace_manager,
+            agent_id=agent.id,
+            agent_config_snapshot_id=snapshot.id,
+        )
+
+        conversation, message = self._init_generate_records(application_generate_entity, conversation)
+
+        queue_manager = MessageBasedAppQueueManager(
+            task_id=application_generate_entity.task_id,
+            user_id=application_generate_entity.user_id,
+            invoke_from=application_generate_entity.invoke_from,
+            conversation_id=conversation.id,
+            app_mode=conversation.mode,
+            message_id=message.id,
+        )
+
+        context = contextvars.copy_context()
+        worker_thread = threading.Thread(
+            target=self._generate_worker,
+            kwargs={
+                "flask_app": current_app._get_current_object(),  # type: ignore
+                "context": context,
+                "application_generate_entity": application_generate_entity,
+                "queue_manager": queue_manager,
+                "conversation_id": conversation.id,
+                "message_id": message.id,
+                "user_from": UserFrom.ACCOUNT if isinstance(user, Account) else UserFrom.END_USER,
+                # Resume continues a paused agent run; skip input guards (see _generate_worker).
+                "is_resume": True,
+            },
+        )
+        worker_thread.start()
+
+        # Blocking: drive the chat task pipeline to persist the assistant answer.
+        self._handle_response(
+            application_generate_entity=application_generate_entity,
+            queue_manager=queue_manager,
+            conversation=conversation,
+            message=message,
+            user=user,
+            stream=False,
+        )
+
     def _generate_worker(
         self,
         *,
@@ -168,6 +272,7 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         conversation_id: str,
         message_id: str,
         user_from: UserFrom,
+        is_resume: bool = False,
     ) -> None:
         from libs.flask_utils import preserve_flask_contexts
 
@@ -177,20 +282,30 @@ class AgentAppGenerator(MessageBasedAppGenerator):
                 message = self._get_message(message_id)
                 app_config = application_generate_entity.app_config
 
-                # Apply app-level input guards (content moderation + annotation
-                # reply) before reaching the Agent backend, mirroring the EasyUI
-                # chat / agent-chat runners. These can short-circuit the turn.
-                app_model = db.session.get(App, app_config.app_id)
-                if app_model is None:
-                    raise AgentAppGeneratorError("App not found")
-                handled, query = self._run_input_guards(
-                    application_generate_entity=application_generate_entity,
-                    app_model=app_model,
-                    message=message,
-                    queue_manager=queue_manager,
-                )
-                if handled:
-                    return
+                if is_resume:
+                    # ENG-638: a resume continues a paused agent run; the human's
+                    # reply is threaded in by the runner as deferred_tool_results.
+                    # The query is the replayed paused-turn message, kept only to
+                    # match the suspended snapshot's layers — it is NOT new
+                    # end-user input, so input guards must NOT run. Moderation or an
+                    # annotation match on the replayed query would short-circuit the
+                    # turn and drop the human reply, stranding the ask_human session.
+                    query = application_generate_entity.query or ""
+                else:
+                    # Apply app-level input guards (content moderation + annotation
+                    # reply) before reaching the Agent backend, mirroring the EasyUI
+                    # chat / agent-chat runners. These can short-circuit the turn.
+                    app_model = db.session.get(App, app_config.app_id)
+                    if app_model is None:
+                        raise AgentAppGeneratorError("App not found")
+                    handled, query = self._run_input_guards(
+                        application_generate_entity=application_generate_entity,
+                        app_model=app_model,
+                        message=message,
+                        queue_manager=queue_manager,
+                    )
+                    if handled:
+                        return
 
                 dify_context = DifyRunContext(
                     tenant_id=app_config.tenant_id,

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

@@ -14,9 +14,12 @@ import json
 import logging
 from typing import Any
 
+from dify_agent.layers.ask_human import AskHumanToolArgs
+from dify_agent.protocol import DeferredToolResultsPayload
 from pydantic import JsonValue
 
 from clients.agent_backend import (
+    AgentBackendDeferredToolCallInternalEvent,
     AgentBackendError,
     AgentBackendInternalEventType,
     AgentBackendRunClient,
@@ -27,13 +30,21 @@ from clients.agent_backend import (
 )
 from core.app.apps.agent_app.runtime_request_builder import (
     AgentAppRuntimeBuildContext,
+    AgentAppRuntimeRequest,
     AgentAppRuntimeRequestBuilder,
 )
-from core.app.apps.agent_app.session_store import AgentAppRuntimeSessionStore, AgentAppSessionScope
+from core.app.apps.agent_app.session_store import (
+    AgentAppRuntimeSessionStore,
+    AgentAppSessionScope,
+    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.queue_entities import QueueLLMChunkEvent, QueueMessageEndEvent
+from core.repositories.human_input_repository import HumanInputFormRepository, HumanInputFormRepositoryImpl
+from core.workflow.nodes.agent_v2.ask_human_hitl import AskHumanFormBuildError, create_ask_human_form
+from core.workflow.nodes.agent_v2.ask_human_resume import build_deferred_tool_results, resolve_ask_human_form
 from graphon.model_runtime.entities.llm_entities import LLMResult, LLMResultChunk, LLMResultChunkDelta, LLMUsage
 from graphon.model_runtime.entities.message_entities import AssistantPromptMessage
 from models.agent_config_entities import AgentSoulConfig
@@ -104,7 +115,13 @@ class AgentAppRunner:
             agent_id=agent_id,
             agent_config_snapshot_id=agent_config_snapshot_id,
         )
-        session_snapshot = self._session_store.load_active_snapshot(scope)
+        # 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_active_session(scope)
+        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
+        )
 
         runtime = self._request_builder.build(
             AgentAppRuntimeBuildContext(
@@ -116,12 +133,29 @@ class AgentAppRunner:
                 user_query=query,
                 idempotency_key=message_id,
                 session_snapshot=session_snapshot,
+                deferred_tool_results=deferred_tool_results,
             )
         )
 
         create_response = self._agent_backend_client.create_run(runtime.request)
         terminal = self._consume_stream(create_response.run_id, queue_manager=queue_manager)
 
+        if isinstance(terminal, AgentBackendDeferredToolCallInternalEvent):
+            # 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(
+                terminal=terminal,
+                scope=scope,
+                dify_context=dify_context,
+                agent_soul=agent_soul,
+                conversation_id=conversation_id,
+                message_id=message_id,
+                model_name=model_name,
+                runtime=runtime,
+                queue_manager=queue_manager,
+            )
+            return
+
         if not isinstance(terminal, AgentBackendRunSucceededInternalEvent):
             error = getattr(terminal, "error", None) or "Agent backend run did not complete successfully."
             raise AgentBackendError(str(error))
@@ -135,6 +169,93 @@ class AgentAppRunner:
             runtime_layer_specs=extract_runtime_layer_specs(runtime.request.composition),
         )
 
+    def _pause_for_ask_human(
+        self,
+        *,
+        terminal: AgentBackendDeferredToolCallInternalEvent,
+        scope: AgentAppSessionScope,
+        dify_context: DifyRunContext,
+        agent_soul: AgentSoulConfig,
+        conversation_id: str,
+        message_id: str,
+        model_name: str,
+        runtime: AgentAppRuntimeRequest,
+        queue_manager: AppQueueManager,
+    ) -> None:
+        """End the chat turn on a dify.ask_human call: create a conversation-owned
+        HITL form, persist the pause correlation, and surface the question."""
+        try:
+            created = create_ask_human_form(
+                deferred_tool_call=terminal.deferred_tool_call,
+                # Chat forms have no workflow node; key by the turn's message id.
+                node_id=message_id,
+                default_node_title="Agent",
+                contacts=agent_soul.human.contacts,
+                repository=self._build_form_repository(dify_context),
+                conversation_id=conversation_id,
+            )
+        except AskHumanFormBuildError as error:
+            raise AgentBackendError(f"Failed to build ask_human form for Agent App chat: {error}") from error
+
+        # Persist the snapshot + correlation so a form submission can start the
+        # second run with the human's answer (ENG-637/638 columns, conversation owner).
+        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),
+            pending_form_id=created.form_id,
+            pending_tool_call_id=terminal.deferred_tool_call.tool_call_id,
+        )
+
+        # The structured form is delivered via the HITL surface(s); the chat turn
+        # ends by echoing the agent's question so the conversation reflects the ask.
+        self._publish_answer(
+            queue_manager=queue_manager,
+            model_name=model_name,
+            answer=self._ask_human_message(created.args),
+        )
+
+    def _resolve_pending_ask_human(
+        self,
+        *,
+        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 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,
+            tenant_id=dify_context.tenant_id,
+            node_id=message_id,
+        )
+        if outcome is None or outcome.deferred_result is None:
+            # Form missing or still waiting — run a normal turn, no resume.
+            return None
+        return build_deferred_tool_results(
+            tool_call_id=stored.pending_tool_call_id,
+            result=outcome.deferred_result,
+        )
+
+    def _build_form_repository(self, dify_context: DifyRunContext) -> HumanInputFormRepository:
+        invoke_source = dify_context.invoke_from.value
+        return HumanInputFormRepositoryImpl(
+            tenant_id=dify_context.tenant_id,
+            app_id=dify_context.app_id,
+            workflow_execution_id=None,
+            invoke_source=invoke_source,
+            submission_actor_id=dify_context.user_id if invoke_source in {"debugger", "explore"} else None,
+        )
+
+    @staticmethod
+    def _ask_human_message(args: AskHumanToolArgs) -> str:
+        parts = [args.question]
+        if args.markdown:
+            parts.append(args.markdown)
+        return "\n\n".join(parts)
+
     def _consume_stream(self, run_id: str, *, queue_manager: AppQueueManager):
         terminal = None
         for public_event in self._agent_backend_client.stream_events(run_id):
@@ -178,6 +299,8 @@ class AgentAppRunner:
         backend_run_id: str,
         snapshot: Any,
         runtime_layer_specs: Any,
+        pending_form_id: str | None = None,
+        pending_tool_call_id: str | None = None,
     ) -> None:
         try:
             self._session_store.save_active_snapshot(
@@ -185,6 +308,8 @@ class AgentAppRunner:
                 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,
             )
         except Exception:
             logger.warning(

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

@@ -18,7 +18,7 @@ from dify_agent.layers.execution_context import (
     DifyExecutionContextLayerConfig,
     DifyExecutionContextUserFrom,
 )
-from dify_agent.protocol import CreateRunRequest
+from dify_agent.protocol import CreateRunRequest, DeferredToolResultsPayload
 
 from clients.agent_backend import (
     AgentBackendAgentAppRunInput,
@@ -32,7 +32,12 @@ from core.workflow.nodes.agent_v2.plugin_tools_builder import (
     WorkflowAgentPluginToolsBuilder,
     WorkflowAgentPluginToolsBuildError,
 )
-from core.workflow.nodes.agent_v2.runtime_request_builder import build_shell_layer_config
+from core.workflow.nodes.agent_v2.runtime_request_builder import (
+    append_runtime_warnings,
+    build_ask_human_layer_config,
+    build_drive_layer_config,
+    build_shell_layer_config,
+)
 from models.agent_config_entities import AgentSoulConfig
 from models.provider_ids import ModelProviderID
 from services.agent.prompt_mentions import build_soul_mention_resolver, expand_prompt_mentions
@@ -60,6 +65,8 @@ class AgentAppRuntimeBuildContext:
     user_query: str
     idempotency_key: str
     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
 
 
 @dataclass(frozen=True, slots=True)
@@ -112,6 +119,11 @@ class AgentAppRuntimeRequestBuilder:
                 "cli_tool_count": len(agent_soul.tools.cli_tools),
             }
 
+        drive_config = None
+        if dify_config.AGENT_DRIVE_MANIFEST_ENABLED:
+            drive_config, drive_warnings = build_drive_layer_config(agent_soul, agent_id=context.agent_id)
+            append_runtime_warnings(metadata, drive_warnings)
+
         request = self._request_builder.build_for_agent_app(
             AgentBackendAgentAppRunInput(
                 model=AgentBackendModelConfig(
@@ -144,9 +156,12 @@ class AgentAppRuntimeRequestBuilder:
                 or None,
                 user_prompt=context.user_query,
                 tools=tools_layer,
+                drive_config=drive_config,
+                ask_human_config=build_ask_human_layer_config(agent_soul),
                 include_shell=dify_config.AGENT_SHELL_ENABLED,
                 shell_config=build_shell_layer_config(agent_soul),
                 session_snapshot=context.session_snapshot,
+                deferred_tool_results=context.deferred_tool_results,
                 idempotency_key=context.idempotency_key,
                 metadata=metadata,
             )

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

@@ -56,6 +56,10 @@ class StoredAgentAppSession:
     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 AgentAppRuntimeSessionStore:
@@ -75,6 +79,8 @@ class AgentAppRuntimeSessionStore:
                 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,
             )
 
     def load_active_session_for_conversation(
@@ -125,6 +131,8 @@ class AgentAppRuntimeSessionStore:
         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:
         if snapshot is None:
             return
@@ -144,6 +152,8 @@ class AgentAppRuntimeSessionStore:
                     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:
@@ -152,6 +162,9 @@ class AgentAppRuntimeSessionStore:
                 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(

api/core/app/apps/chat/app_config_manager.py

@@ -81,7 +81,7 @@ class ChatAppConfigManager(BaseAppConfigManager):
         return app_config
 
     @classmethod
-    def config_validate(cls, tenant_id: str, config: dict) -> AppModelConfigDict:
+    def config_validate(cls, tenant_id: str, config: dict[str, Any]) -> AppModelConfigDict:
         """
         Validate for chat app model config
 

api/core/app/apps/completion/app_config_manager.py

@@ -68,7 +68,7 @@ class CompletionAppConfigManager(BaseAppConfigManager):
         return app_config
 
     @classmethod
-    def config_validate(cls, tenant_id: str, config: dict) -> AppModelConfigDict:
+    def config_validate(cls, tenant_id: str, config: dict[str, Any]) -> AppModelConfigDict:
         """
         Validate for completion app model config
 

api/core/helper/marketplace.py

@@ -12,6 +12,8 @@ from extensions.ext_redis import redis_client
 marketplace_api_url = URL(str(dify_config.MARKETPLACE_API_URL))
 logger = logging.getLogger(__name__)
 
+MARKETPLACE_TIMEOUT = 30
+
 
 def get_plugin_pkg_url(plugin_unique_identifier: str) -> str:
     return str((marketplace_api_url / "api/v1/plugins/download").with_query(unique_identifier=plugin_unique_identifier))
@@ -26,7 +28,12 @@ def batch_fetch_plugin_manifests(plugin_ids: list[str]) -> Sequence[MarketplaceP
         return []
 
     url = str(marketplace_api_url / "api/v1/plugins/batch")
-    response = httpx.post(url, json={"plugin_ids": plugin_ids}, headers={"X-Dify-Version": dify_config.project.version})
+    response = httpx.post(
+        url,
+        json={"plugin_ids": plugin_ids},
+        headers={"X-Dify-Version": dify_config.project.version},
+        timeout=MARKETPLACE_TIMEOUT,
+    )
     response.raise_for_status()
 
     return [MarketplacePluginDeclaration.model_validate(plugin) for plugin in response.json()["data"]["plugins"]]
@@ -37,7 +44,12 @@ def batch_fetch_plugin_by_ids(plugin_ids: list[str]) -> list[dict]:
         return []
 
     url = str(marketplace_api_url / "api/v1/plugins/batch")
-    response = httpx.post(url, json={"plugin_ids": plugin_ids}, headers={"X-Dify-Version": dify_config.project.version})
+    response = httpx.post(
+        url,
+        json={"plugin_ids": plugin_ids},
+        headers={"X-Dify-Version": dify_config.project.version},
+        timeout=MARKETPLACE_TIMEOUT,
+    )
     response.raise_for_status()
 
     data = response.json()
@@ -46,7 +58,7 @@ def batch_fetch_plugin_by_ids(plugin_ids: list[str]) -> list[dict]:
 
 def record_install_plugin_event(plugin_unique_identifier: str):
     url = str(marketplace_api_url / "api/v1/stats/plugins/install_count")
-    response = httpx.post(url, json={"unique_identifier": plugin_unique_identifier})
+    response = httpx.post(url, json={"unique_identifier": plugin_unique_identifier}, timeout=MARKETPLACE_TIMEOUT)
     response.raise_for_status()
 
 
@@ -64,7 +76,7 @@ def fetch_global_plugin_manifest(cache_key_prefix: str, cache_ttl: int) -> None:
         Exception: If any other error occurs during fetching or caching
     """
     url = str(marketplace_api_url / "api/v1/dist/plugins/manifest.json")
-    response = httpx.get(url, headers={"X-Dify-Version": dify_config.project.version}, timeout=30)
+    response = httpx.get(url, headers={"X-Dify-Version": dify_config.project.version}, timeout=MARKETPLACE_TIMEOUT)
     response.raise_for_status()
 
     raw_json = response.json()

api/core/plugin/entities/parameters.py

@@ -132,13 +132,14 @@ def cast_parameter_value(typ: StrEnum, value: Any, /):
                     return value if isinstance(value, bool) else bool(value)
 
             case PluginParameterType.NUMBER:
-                if isinstance(value, int | float):
-                    return value
-                elif isinstance(value, str) and value:
-                    if "." in value:
-                        return float(value)
-                    else:
-                        return int(value)
+                match value:
+                    case int() | float():
+                        return value
+                    case str() if value:
+                        if "." in value:
+                            return float(value)
+                        else:
+                            return int(value)
             case PluginParameterType.SYSTEM_FILES | PluginParameterType.FILES:
                 if not isinstance(value, list):
                     return [value]

api/core/plugin/entities/plugin_daemon.py

@@ -168,6 +168,7 @@ class PluginInstallTask(BasePluginEntity):
 class PluginInstallTaskStartResponse(BaseModel):
     all_installed: bool = Field(description="Whether all plugins are installed.")
     task_id: str = Field(description="The ID of the install task.")
+    task: PluginInstallTask | None = Field(default=None, description="The install task.")
 
 
 class PluginVerification(BaseModel):
@@ -206,6 +207,11 @@ class PluginListResponse(BaseModel):
     total: int
 
 
+class PluginListWithoutTotalResponse(BaseModel):
+    list: list[PluginEntity]
+    has_more: bool
+
+
 class PluginDynamicSelectOptionsResponse(BaseModel):
     options: Sequence[PluginParameterOption] = Field(description="The options of the dynamic select.")
 

api/core/plugin/impl/plugin.py

@@ -6,6 +6,7 @@ from requests import HTTPError
 from core.plugin.entities.bundle import PluginBundleDependency
 from core.plugin.entities.plugin import (
     MissingPluginDependency,
+    PluginCategory,
     PluginDeclaration,
     PluginEntity,
     PluginInstallation,
@@ -16,6 +17,7 @@ from core.plugin.entities.plugin_daemon import (
     PluginInstallTask,
     PluginInstallTaskStartResponse,
     PluginListResponse,
+    PluginListWithoutTotalResponse,
     PluginReadmeResponse,
 )
 from core.plugin.impl.base import BasePluginClient
@@ -74,6 +76,16 @@ class PluginInstaller(BasePluginClient):
             params={"page": page, "page_size": page_size, "response_type": "paged"},
         )
 
+    def list_plugins_by_category(
+        self, tenant_id: str, category: PluginCategory, page: int, page_size: int
+    ) -> PluginListWithoutTotalResponse:
+        return self._request_with_plugin_daemon_response(
+            "GET",
+            f"plugin/{tenant_id}/management/{category.value}/list",
+            PluginListWithoutTotalResponse,
+            params={"page": page, "page_size": page_size, "response_type": "paged"},
+        )
+
     def upload_pkg(
         self,
         tenant_id: str,

api/core/plugin/plugin_service.py

@@ -31,6 +31,7 @@ from core.helper.marketplace import download_plugin_pkg
 from core.helper.model_provider_cache import ProviderCredentialsCache, ProviderCredentialsCacheType
 from core.plugin.entities.bundle import PluginBundleDependency
 from core.plugin.entities.plugin import (
+    PluginCategory,
     PluginDeclaration,
     PluginEntity,
     PluginInstallation,
@@ -41,6 +42,7 @@ from core.plugin.entities.plugin_daemon import (
     PluginInstallTask,
     PluginInstallTaskStatus,
     PluginListResponse,
+    PluginListWithoutTotalResponse,
     PluginModelProviderEntity,
     PluginVerification,
 )
@@ -437,6 +439,19 @@ class PluginService:
         PluginService._reconcile_endpoint_counts(tenant_id, user_id, plugins.list)
         return plugins
 
+    @staticmethod
+    def list_by_category(
+        tenant_id: str, category: PluginCategory, page: int, page_size: int
+    ) -> PluginListWithoutTotalResponse:
+        """
+        List plugins in one category with a has-more cursor signal and without calculating total.
+
+        The daemon scans tenant installations in the existing list order and stops once it finds one extra match.
+        This keeps pagination usable before category is persisted on installation rows.
+        """
+        manager = PluginInstaller()
+        return manager.list_plugins_by_category(tenant_id, category, page, page_size)
+
     @staticmethod
     def _normalize_endpoint_count(value: object) -> int:
         """Convert daemon endpoint counters to safe non-negative integers.

api/core/plugin/utils/converter.py

@@ -6,16 +6,13 @@ from graphon.file import File
 
 def convert_parameters_to_plugin_format(parameters: dict[str, Any]) -> dict[str, Any]:
     for parameter_name, parameter in parameters.items():
-        if isinstance(parameter, File):
-            parameters[parameter_name] = parameter.to_plugin_parameter()
-        elif isinstance(parameter, list) and all(isinstance(p, File) for p in parameter):
-            parameters[parameter_name] = []
-            for p in parameter:
-                parameters[parameter_name].append(p.to_plugin_parameter())
-        elif isinstance(parameter, ToolSelector):
-            parameters[parameter_name] = parameter.to_plugin_parameter()
-        elif isinstance(parameter, list) and all(isinstance(p, ToolSelector) for p in parameter):
-            parameters[parameter_name] = []
-            for p in parameter:
-                parameters[parameter_name].append(p.to_plugin_parameter())
+        match parameter:
+            case File():
+                parameters[parameter_name] = parameter.to_plugin_parameter()
+            case [*items] if all(isinstance(p, File) for p in items):
+                parameters[parameter_name] = [p.to_plugin_parameter() for p in items]
+            case ToolSelector():
+                parameters[parameter_name] = parameter.to_plugin_parameter()
+            case [*items] if all(isinstance(p, ToolSelector) for p in items):
+                parameters[parameter_name] = [p.to_plugin_parameter() for p in items]
     return parameters

api/core/rag/extractor/watercrawl/client.py

@@ -118,16 +118,18 @@ class WaterCrawlAPIClient(BaseAPIClient):
         response.raise_for_status()
         if response.status_code == 204:
             return None
-        if response.headers.get("Content-Type") == "application/json":
+        content_type = response.headers.get("Content-Type", "")
+        media_type = content_type.split(";", 1)[0].strip().lower()
+        if media_type == "application/json":
             return response.json() or {}
 
-        if response.headers.get("Content-Type") == "application/octet-stream":
+        if media_type == "application/octet-stream":
             return response.content
 
-        if response.headers.get("Content-Type") == "text/event-stream":
+        if media_type == "text/event-stream":
             return self.process_eventstream(response)
 
-        raise Exception(f"Unknown response type: {response.headers.get('Content-Type')}")
+        raise Exception(f"Unknown response type: {content_type}")
 
     def get_crawl_requests_list(self, page: int | None = None, page_size: int | None = None):
         query_params = {"page": page or 1, "page_size": page_size or 10}
@@ -217,7 +219,7 @@ class WaterCrawlAPIClient(BaseAPIClient):
                 return event_data["data"]
 
     def download_result(self, result_object: dict[str, Any]):
-        response = httpx.get(result_object["result"], timeout=None)
+        response = httpx.get(result_object["result"], timeout=30)
         try:
             response.raise_for_status()
             result_object["result"] = response.json()

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

@@ -5,6 +5,8 @@ import re
 import uuid
 from typing import Any, TypedDict, cast, override
 
+from sqlalchemy.orm import scoped_session
+
 logger = logging.getLogger(__name__)
 
 from sqlalchemy import select
@@ -411,11 +413,13 @@ class ParagraphIndexProcessor(BaseIndexProcessor):
         if supports_vision:
             # First, try to get images from SegmentAttachmentBinding (preferred method)
             if segment_id:
-                image_files = ParagraphIndexProcessor._extract_images_from_segment_attachments(tenant_id, segment_id)
+                image_files = ParagraphIndexProcessor._extract_images_from_segment_attachments(
+                    tenant_id, segment_id, db.session
+                )
 
             # If no images from attachments, fall back to extracting from text
             if not image_files:
-                image_files = ParagraphIndexProcessor._extract_images_from_text(tenant_id, text)
+                image_files = ParagraphIndexProcessor._extract_images_from_text(tenant_id, text, db.session)
 
         # Build prompt messages
         prompt_messages = []
@@ -469,7 +473,7 @@ class ParagraphIndexProcessor(BaseIndexProcessor):
         return summary_content, usage
 
     @staticmethod
-    def _extract_images_from_text(tenant_id: str, text: str) -> list[File]:
+    def _extract_images_from_text(tenant_id: str, text: str, session: scoped_session) -> list[File]:
         """
         Extract images from markdown text and convert them to File objects.
 
@@ -518,7 +522,7 @@ class ParagraphIndexProcessor(BaseIndexProcessor):
 
         # Get unique IDs for database query
         unique_upload_file_ids = list(set(upload_file_id_list))
-        upload_files = db.session.scalars(
+        upload_files = session.scalars(
             select(UploadFile).where(UploadFile.id.in_(unique_upload_file_ids), UploadFile.tenant_id == tenant_id)
         ).all()
 
@@ -549,7 +553,9 @@ class ParagraphIndexProcessor(BaseIndexProcessor):
         return file_objects
 
     @staticmethod
-    def _extract_images_from_segment_attachments(tenant_id: str, segment_id: str) -> list[File]:
+    def _extract_images_from_segment_attachments(
+        tenant_id: str, segment_id: str, session: scoped_session
+    ) -> list[File]:
         """
         Extract images from SegmentAttachmentBinding table (preferred method).
         This matches how DatasetRetrieval gets segment attachments.
@@ -564,7 +570,7 @@ class ParagraphIndexProcessor(BaseIndexProcessor):
         from sqlalchemy import select
 
         # Query attachments from SegmentAttachmentBinding table
-        attachments_with_bindings = db.session.execute(
+        attachments_with_bindings = session.execute(
             select(SegmentAttachmentBinding, UploadFile)
             .join(UploadFile, UploadFile.id == SegmentAttachmentBinding.attachment_id)
             .where(

api/core/rbac/__init__.py

@@ -0,0 +1,3 @@
+from core.rbac.entities import RBACPermission, RBACResourceScope
+
+__all__ = ["RBACPermission", "RBACResourceScope"]

api/core/rbac/entities.py

@@ -0,0 +1,37 @@
+from enum import StrEnum
+
+
+class RBACResourceScope(StrEnum):
+    """Resource scopes accepted by the ``rbac_permission_required`` decorator.
+
+    ``WORKSPACE`` denotes a workspace-level check that carries no concrete
+    resource id; ``APP`` and ``DATASET`` are resource-scoped checks.
+    """
+
+    APP = "app"
+    DATASET = "dataset"
+    WORKSPACE = "workspace"
+
+
+class RBACPermission(StrEnum):
+    """Permission points (RBAC scenes) checked by ``rbac_permission_required``.
+
+    Each member's value is the scene name forwarded to the RBAC
+    ``check-access`` endpoint.
+    """
+
+    APP_VIEW_LAYOUT = "app_view_layout"
+    APP_TEST_AND_RUN = "app_test_and_run"
+    APP_CREATE_AND_MANAGEMENT = "app_create_and_management"
+    APP_RELEASE_AND_VERSION = "app_release_and_version"
+    APP_IMPORT_EXPORT_DSL = "app_import_export_dsl"
+    APP_MONITOR = "app_monitor"
+    APP_DELETE = "app_delete"
+
+    DATASET_READONLY = "dataset_readonly"
+    DATASET_EDIT = "dataset_edit"
+    DATASET_CREATE_AND_MANAGEMENT = "dataset_create_and_management"
+    DATASET_PIPELINE_TEST = "dataset_pipeline_test"
+    DATASET_DOCUMENT_DOWNLOAD = "dataset_document_download"
+
+    WORKSPACE_ROLE_MANAGE = "workspace_role_manage"

api/core/repositories/human_input_repository.py

@@ -63,6 +63,10 @@ class FormCreateParams:
     display_in_ui: bool
     resolved_default_values: Mapping[str, Any]
     form_kind: HumanInputFormKind = HumanInputFormKind.RUNTIME
+    # ENG-635: the conversation this form belongs to. Set together with
+    # workflow_execution_id for chatflow runs; set alone (workflow_execution_id None)
+    # for Agent v2 chat ask_human forms, which have no workflow run.
+    conversation_id: str | None = None
 
 
 class HumanInputFormRecipientEntity(Protocol):
@@ -217,6 +221,9 @@ class HumanInputFormRecord:
     recipient_id: str | None
     recipient_type: RecipientType | None
     access_token: str | None
+    # ENG-635: Agent v2 chat owner (NULL for workflow-owned forms). Trailing +
+    # defaulted so existing record constructions stay source-compatible.
+    conversation_id: str | None = None
 
     @property
     def submitted(self) -> bool:
@@ -232,6 +239,7 @@ class HumanInputFormRecord:
         return cls(
             form_id=form_model.id,
             workflow_run_id=form_model.workflow_run_id,
+            conversation_id=form_model.conversation_id,
             node_id=form_model.node_id,
             tenant_id=form_model.tenant_id,
             app_id=form_model.app_id,
@@ -433,8 +441,15 @@ class HumanInputFormRepositoryImpl:
         if not app_id:
             raise ValueError("app_id is required to create a human input form")
         workflow_execution_id = params.workflow_execution_id or self._workflow_execution_id
-        if params.form_kind == HumanInputFormKind.RUNTIME and workflow_execution_id is None:
-            raise ValueError("workflow_execution_id is required for runtime human input forms")
+        # A RUNTIME form must be owned by at least one of: a workflow run (workflow /
+        # Human-Input / agent node) or a conversation turn (ENG-635: Agent v2 chat
+        # ask_human; chatflow runs set both — workflow_run_id and conversation_id).
+        if (
+            params.form_kind == HumanInputFormKind.RUNTIME
+            and workflow_execution_id is None
+            and params.conversation_id is None
+        ):
+            raise ValueError("a runtime human input form requires a workflow_execution_id or conversation_id")
 
         with session_factory.create_session() as session, session.begin():
             # Generate unique form ID
@@ -456,6 +471,7 @@ class HumanInputFormRepositoryImpl:
                 tenant_id=self._tenant_id,
                 app_id=app_id,
                 workflow_run_id=workflow_execution_id,
+                conversation_id=params.conversation_id,
                 form_kind=params.form_kind,
                 node_id=params.node_id,
                 form_definition=form_definition.model_dump_json(),

api/core/tools/__base/tool.py

@@ -66,20 +66,21 @@ class Tool(ABC):
             message_id=message_id,
         )
 
-        if isinstance(result, ToolInvokeMessage):
+        match result:
+            case ToolInvokeMessage():
 
-            def single_generator() -> Generator[ToolInvokeMessage, None, None]:
-                yield result
+                def single_generator() -> Generator[ToolInvokeMessage, None, None]:
+                    yield result
 
-            return single_generator()
-        elif isinstance(result, list):
+                return single_generator()
+            case list():
 
-            def generator() -> Generator[ToolInvokeMessage, None, None]:
-                yield from result
+                def generator() -> Generator[ToolInvokeMessage, None, None]:
+                    yield from result
 
-            return generator()
-        else:
-            return result
+                return generator()
+            case _:
+                return result
 
     def _transform_tool_parameters_type(self, tool_parameters: dict[str, Any]) -> dict[str, Any]:
         """

api/core/workflow/node_factory.py

@@ -334,6 +334,7 @@ class DifyNodeFactory(NodeFactory):
                 self.graph_runtime_state.variable_pool,
                 SystemVariableKey.WORKFLOW_EXECUTION_ID,
             ),
+            conversation_id_getter=self._conversation_id,
         )
         self._tool_runtime = DifyToolNodeRuntime(self._dify_context)
         self._http_request_file_manager = file_manager

api/core/workflow/node_runtime.py

@@ -710,10 +710,12 @@ class DifyHumanInputNodeRuntime(HumanInputNodeRuntimeProtocol):
         run_context: Mapping[str, Any] | DifyRunContext,
         *,
         workflow_execution_id_getter: Callable[[], str | None] | None = None,
+        conversation_id_getter: Callable[[], str | None] | None = None,
         form_repository: HumanInputFormRepository | None = None,
     ) -> None:
         self._run_context = resolve_dify_run_context(run_context)
         self._workflow_execution_id_getter = workflow_execution_id_getter
+        self._conversation_id_getter = conversation_id_getter
         self._form_repository = form_repository
         self._file_reference_factory = DifyFileReferenceFactory(self._run_context)
 
@@ -762,6 +764,7 @@ class DifyHumanInputNodeRuntime(HumanInputNodeRuntimeProtocol):
         return DifyHumanInputNodeRuntime(
             self._run_context,
             workflow_execution_id_getter=self._workflow_execution_id_getter,
+            conversation_id_getter=self._conversation_id_getter,
             form_repository=form_repository,
         )
 
@@ -799,6 +802,9 @@ class DifyHumanInputNodeRuntime(HumanInputNodeRuntimeProtocol):
         repo = self.build_form_repository()
         params = FormCreateParams(
             workflow_execution_id=self._workflow_execution_id_getter() if self._workflow_execution_id_getter else None,
+            # A chatflow (advanced-chat) run carries a conversation; tag the form with
+            # it too so it is queryable per conversation. None for a pure workflow run.
+            conversation_id=self._conversation_id_getter() if self._conversation_id_getter else None,
             node_id=node_id,
             form_config=node_data,
             rendered_content=rendered_content,

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

@@ -24,13 +24,16 @@ from clients.agent_backend import (
     extract_runtime_layer_specs,
 )
 from core.app.entities.app_invoke_entities import DIFY_RUN_CONTEXT_KEY, DifyRunContext
+from core.repositories.human_input_repository import HumanInputFormRepository, HumanInputFormRepositoryImpl
 from core.workflow.system_variables import SystemVariableKey, get_system_text
-from graphon.entities.pause_reason import SchedulingPause
+from graphon.entities.pause_reason import HumanInputRequired, SchedulingPause
 from graphon.enums import BuiltinNodeTypes, WorkflowNodeExecutionMetadataKey, WorkflowNodeExecutionStatus
 from graphon.node_events import NodeEventBase, NodeRunResult, PauseRequestedEvent, StreamCompletedEvent
 from graphon.nodes.base.node import Node
-from models.agent_config_entities import WorkflowNodeJobConfig
+from models.agent_config_entities import AgentSoulConfig, WorkflowNodeJobConfig
 
+from .ask_human_hitl import AskHumanFormBuildError, build_ask_human_pause_reason
+from .ask_human_resume import build_deferred_tool_results, resolve_ask_human_form
 from .binding_resolver import WorkflowAgentBindingError, WorkflowAgentBindingResolver
 from .entities import DifyAgentNodeData
 from .output_adapter import WorkflowAgentOutputAdapter
@@ -117,6 +120,12 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
             self.graph_runtime_state.variable_pool,
             SystemVariableKey.WORKFLOW_EXECUTION_ID,
         )
+        # Set on chatflow (advanced-chat) runs; None for a pure workflow run. Lets an
+        # ask_human form be tagged with its conversation in addition to workflow_run_id.
+        conversation_id = get_system_text(
+            self.graph_runtime_state.variable_pool,
+            SystemVariableKey.CONVERSATION_ID,
+        )
         inputs: dict[str, Any] = {}
         process_data: dict[str, Any] = {}
         metadata: dict[str, Any] = {
@@ -168,6 +177,33 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
         )
         outputs_by_name = {o.name: o for o in effective_outputs}
 
+        # ──── ENG-638: resume after a submitted/timed-out ask_human form ────
+        # graphon re-executes this _run when the outer workflow resumes. If a
+        # pending ask_human form is now terminal, thread the human's answer into
+        # the second Agent run as deferred_tool_results; if it is somehow still
+        # waiting, re-emit the same pause defensively.
+        deferred_tool_results = None
+        if self._session_store is not None:
+            stored_session = self._session_store.load_active_session(session_scope)
+            if stored_session is not None and stored_session.pending_form_id is not None:
+                resume_outcome = resolve_ask_human_form(
+                    form_id=stored_session.pending_form_id,
+                    tenant_id=dify_ctx.tenant_id,
+                    node_id=self._node_id,
+                )
+                if resume_outcome is not None and resume_outcome.repause is not None:
+                    yield PauseRequestedEvent(reason=resume_outcome.repause)
+                    return
+                if (
+                    resume_outcome is not None
+                    and resume_outcome.deferred_result is not None
+                    and stored_session.pending_tool_call_id is not None
+                ):
+                    deferred_tool_results = build_deferred_tool_results(
+                        tool_call_id=stored_session.pending_tool_call_id,
+                        result=resume_outcome.deferred_result,
+                    )
+
         # ──── Retry loop (Stage 4 §7) ────
         attempt = 0
         while True:
@@ -188,6 +224,7 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
                         snapshot=bundle.snapshot,
                         attempt=attempt,
                         session_snapshot=session_snapshot,
+                        deferred_tool_results=deferred_tool_results,
                     )
                 )
             except WorkflowAgentRuntimeRequestBuildError as error:
@@ -251,19 +288,56 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
                 return
 
             if isinstance(terminal_event, AgentBackendDeferredToolCallInternalEvent):
+                # ENG-636: a dify.ask_human deferred call pauses the *outer*
+                # workflow through the existing HITL form path. Any other deferred
+                # tool (none today) falls back to a generic scheduling pause. The
+                # form is built *before* the snapshot is saved so its id can be
+                # persisted as the pause correlation (ENG-637).
+                try:
+                    pause_reason: HumanInputRequired | SchedulingPause | None = build_ask_human_pause_reason(
+                        deferred_tool_call=terminal_event.deferred_tool_call,
+                        node_id=self._node_id,
+                        default_node_title=bundle.agent.name or self._node_id,
+                        workflow_run_id=workflow_run_id,
+                        conversation_id=conversation_id,
+                        contacts=AgentSoulConfig.model_validate(bundle.snapshot.config_snapshot_dict).human.contacts,
+                        repository=self._build_human_input_form_repository(
+                            dify_ctx=dify_ctx, workflow_run_id=workflow_run_id
+                        ),
+                    )
+                except AskHumanFormBuildError as error:
+                    yield self._failure_event(
+                        inputs=inputs,
+                        process_data=process_data,
+                        metadata=metadata,
+                        error=str(error),
+                        error_type="agent_ask_human_form_build_error",
+                    )
+                    return
+
+                # ENG-637: persist the awaiting-form id + deferred tool_call id
+                # next to the snapshot so the resumed node can rebuild
+                # deferred_tool_results from the submitted form.
+                pending_form_id: str | None = None
+                pending_tool_call_id: str | None = None
+                if isinstance(pause_reason, HumanInputRequired):
+                    pending_form_id = pause_reason.form_id
+                    pending_tool_call_id = terminal_event.deferred_tool_call.tool_call_id
+                else:
+                    pause_reason = SchedulingPause(
+                        message=terminal_event.message
+                        or "Agent backend run requested workflow pause for external input."
+                    )
                 self._save_session_snapshot(
                     session_scope=session_scope,
                     backend_run_id=terminal_event.run_id,
                     snapshot=terminal_event.session_snapshot,
                     runtime_layer_specs=extract_runtime_layer_specs(runtime_request.request.composition),
                     metadata=metadata,
+                    pending_form_id=pending_form_id,
+                    pending_tool_call_id=pending_tool_call_id,
                 )
-                yield PauseRequestedEvent(
-                    reason=SchedulingPause(
-                        message=terminal_event.message
-                        or "Agent backend run requested workflow pause for external input."
-                    )
-                )
+                yield PauseRequestedEvent(reason=pause_reason)
                 return
 
             # Non-success terminal (failed / cancelled) skips per-output
@@ -448,6 +522,27 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
             ],
         }
 
+    def _build_human_input_form_repository(
+        self,
+        *,
+        dify_ctx: DifyRunContext,
+        workflow_run_id: str | None,
+    ) -> HumanInputFormRepository:
+        """Construct the existing HITL form repository for ask_human form creation.
+
+        Mirrors the Human Input node's repository wiring (``node_runtime``) so the
+        ask_human form shares the same delivery/debug/console behavior: a
+        submission actor is only attributed for debugger/explore surfaces.
+        """
+        invoke_source = dify_ctx.invoke_from.value
+        return HumanInputFormRepositoryImpl(
+            tenant_id=dify_ctx.tenant_id,
+            app_id=dify_ctx.app_id,
+            workflow_execution_id=workflow_run_id,
+            invoke_source=invoke_source,
+            submission_actor_id=dify_ctx.user_id if invoke_source in {"debugger", "explore"} else None,
+        )
+
     def _save_session_snapshot(
         self,
         *,
@@ -456,6 +551,8 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
         snapshot: CompositorSessionSnapshot | None,
         runtime_layer_specs: list[RuntimeLayerSpec],
         metadata: dict[str, Any],
+        pending_form_id: str | None = None,
+        pending_tool_call_id: str | None = None,
     ) -> None:
         if self._session_store is None:
             return
@@ -465,6 +562,8 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
                 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,
             )
             agent_backend = dict(metadata.get("agent_backend") or {})
             agent_backend["session_snapshot_persisted"] = snapshot is not None

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

@@ -0,0 +1,354 @@
+"""Map a ``dify.ask_human`` deferred tool call onto the existing HITL form path.
+
+ENG-636. When an Agent backend run ends with a deferred ``dify.ask_human`` tool
+call, the workflow Agent node pauses the *outer* workflow through the very same
+``HumanInputRequired`` form mechanism the Human Input node uses — reusing the
+form repository, delivery channels, and submission endpoints unchanged. This
+module is a pure translation layer: model-facing ask_human tool args become
+graphon form entities (``HumanInputNodeData`` / ``FormInputConfig`` /
+``UserActionConfig``) plus Dify delivery configs. It adds no new HITL behavior.
+
+The agent-side ``dify.ask_human`` contract is richer than the workflow form
+schema in two places, handled here without widening the form vocabulary:
+
+* ask_human fields carry a human label; graphon ``FormInputConfig`` does not.
+  Labels are rendered into ``form_content`` next to a ``{{#$output.<name>#}}``
+  marker — exactly how the Human Input node positions labelled inputs today.
+* ask_human action ids are valid identifiers of any length; graphon
+  ``UserActionConfig.id`` caps ids at 20 chars. Over-long ids are clamped
+  deterministically (stable + collision-resistant) so the form always builds;
+  the human-visible action *label* is always preserved verbatim.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, assert_never
+
+from dify_agent.layers.ask_human import (
+    AskHumanAction,
+    AskHumanField,
+    AskHumanFileField,
+    AskHumanFileListField,
+    AskHumanParagraphField,
+    AskHumanSelectField,
+    AskHumanToolArgs,
+)
+from dify_agent.protocol import DeferredToolCallPayload
+from pydantic import ValidationError
+
+from core.repositories.human_input_repository import FormCreateParams, HumanInputFormRepository
+from core.workflow.human_input_adapter import (
+    DeliveryChannelConfig,
+    EmailDeliveryConfig,
+    EmailDeliveryMethod,
+    EmailRecipients,
+    ExternalRecipient,
+    InteractiveSurfaceDeliveryMethod,
+)
+from graphon.entities.pause_reason import HumanInputRequired
+from graphon.nodes.human_input.entities import (
+    FileInputConfig,
+    FileListInputConfig,
+    FormInputConfig,
+    HumanInputNodeData,
+    ParagraphInputConfig,
+    SelectInputConfig,
+    StringListSource,
+    StringSource,
+    UserActionConfig,
+)
+from graphon.nodes.human_input.enums import ButtonStyle, TimeoutUnit, ValueSourceType
+from models.agent_config_entities import AgentHumanContactConfig
+
+# Default ask_human tool name (see ``DifyAskHumanLayerConfig.tool_name``). The
+# Agent node only knows how to translate this one deferred tool into a form.
+DEFAULT_ASK_HUMAN_TOOL_NAME = "ask_human"
+
+# Graphon ``UserActionConfig.id`` hard-caps identifiers at 20 chars.
+_MAX_ACTION_ID_LEN = 20
+# No timeout lives in the ask_human contract; reuse the Human Input node default.
+_DEFAULT_TIMEOUT_HOURS = 36
+_EMAIL_SUBJECT_MAX_LEN = 120
+
+# ``ButtonStyle`` has no "destructive"; map the ask_human destructive intent onto
+# the closest existing form style rather than extending the HITL vocabulary.
+_ACTION_STYLE_TO_BUTTON: dict[str, ButtonStyle] = {
+    "default": ButtonStyle.DEFAULT,
+    "primary": ButtonStyle.PRIMARY,
+    "destructive": ButtonStyle.ACCENT,
+}
+
+# ask_human permits zero actions (a plain acknowledgement); the form surface
+# needs at least one submit affordance.
+_DEFAULT_SUBMIT_ACTION = UserActionConfig(id="submit", title="Submit", button_style=ButtonStyle.PRIMARY)
+
+
+class AskHumanFormBuildError(ValueError):
+    """Raised when ask_human tool args cannot be mapped to a HITL form."""
+
+
+def parse_ask_human_args(raw_args: object) -> AskHumanToolArgs:
+    """Validate the raw deferred-tool ``args`` payload into ``AskHumanToolArgs``."""
+    if isinstance(raw_args, AskHumanToolArgs):
+        return raw_args
+    if isinstance(raw_args, Mapping):
+        try:
+            return AskHumanToolArgs.model_validate(dict(raw_args))
+        except ValidationError as error:
+            raise AskHumanFormBuildError(f"invalid ask_human args: {error}") from error
+    raise AskHumanFormBuildError(f"ask_human args must be a mapping, got {type(raw_args).__name__}")
+
+
+def _clamp_action_id(action_id: str) -> str:
+    """Return a stable graphon-safe (<= 20 char) action id.
+
+    ask_human ids are already valid identifiers; ids within the limit pass
+    through untouched so the resume round-trip returns the model's exact id.
+    Over-long ids are truncated with a short content hash to stay deterministic
+    and collision-resistant while remaining a valid identifier.
+    """
+    if len(action_id) <= _MAX_ACTION_ID_LEN:
+        return action_id
+    digest = hashlib.blake2b(action_id.encode("utf-8"), digest_size=3).hexdigest()
+    prefix = action_id[: _MAX_ACTION_ID_LEN - len(digest) - 1]
+    return f"{prefix}_{digest}"
+
+
+def _to_form_input(field: AskHumanField) -> FormInputConfig:
+    match field:
+        case AskHumanParagraphField():
+            default = (
+                StringSource(type=ValueSourceType.CONSTANT, value=field.default) if field.default is not None else None
+            )
+            return ParagraphInputConfig(output_variable_name=field.name, default=default)
+        case AskHumanSelectField():
+            return SelectInputConfig(
+                output_variable_name=field.name,
+                option_source=StringListSource(
+                    type=ValueSourceType.CONSTANT,
+                    value=[option.value for option in field.options],
+                ),
+            )
+        case AskHumanFileField():
+            return FileInputConfig(output_variable_name=field.name)
+        case AskHumanFileListField():
+            return FileListInputConfig(output_variable_name=field.name, number_limits=field.max_files or 0)
+        case _:  # pragma: no cover - exhaustive over the discriminated union
+            assert_never(field)
+
+
+def _to_user_actions(actions: Sequence[AskHumanAction]) -> list[UserActionConfig]:
+    if not actions:
+        return [_DEFAULT_SUBMIT_ACTION]
+    return [
+        UserActionConfig(
+            id=_clamp_action_id(action.id),
+            title=action.label,
+            button_style=_ACTION_STYLE_TO_BUTTON.get(action.style, ButtonStyle.DEFAULT),
+        )
+        for action in actions
+    ]
+
+
+def _render_form_content(args: AskHumanToolArgs) -> str:
+    """Compose the markdown body, positioning each field's label + input marker.
+
+    Graphon ``FormInputConfig`` carries no label, so the field label is written
+    into the content next to the ``{{#$output.<name>#}}`` marker that the form
+    surface replaces with the live input — identical to the Human Input node.
+    """
+    blocks: list[str] = []
+    if args.title:
+        blocks.append(f"## {args.title}")
+    blocks.append(args.question)
+    if args.markdown:
+        blocks.append(args.markdown)
+    for field in args.fields:
+        label = f"{field.label} *" if field.required else field.label
+        blocks.append(f"**{label}**\n\n{{{{#$output.{field.name}#}}}}")
+    return "\n\n".join(blocks)
+
+
+def _resolved_default_values(args: AskHumanToolArgs) -> dict[str, Any]:
+    """Pre-fill map the form surface reads, keyed by output variable name.
+
+    The graphon select input has no default field, so a select default can only
+    be conveyed here; paragraph defaults are included for a uniform pre-fill.
+    """
+    defaults: dict[str, Any] = {}
+    for field in args.fields:
+        if isinstance(field, AskHumanParagraphField | AskHumanSelectField) and field.default is not None:
+            defaults[field.name] = field.default
+    return defaults
+
+
+def ask_human_args_to_node_data(args: AskHumanToolArgs, *, node_title: str) -> HumanInputNodeData:
+    """Translate validated ask_human args into a synthetic Human Input node config."""
+    return HumanInputNodeData(
+        title=node_title,
+        form_content=_render_form_content(args),
+        inputs=[_to_form_input(field) for field in args.fields],
+        user_actions=_to_user_actions(args.actions),
+        timeout=_DEFAULT_TIMEOUT_HOURS,
+        timeout_unit=TimeoutUnit.HOUR,
+    )
+
+
+def build_delivery_methods(
+    contacts: Sequence[AgentHumanContactConfig],
+    *,
+    args: AskHumanToolArgs,
+) -> list[DeliveryChannelConfig]:
+    """Build form delivery channels: always the interactive surface, plus email to
+    the configured human contacts (the recipients chosen in Agent Soul)."""
+    methods: list[DeliveryChannelConfig] = [InteractiveSurfaceDeliveryMethod()]
+
+    seen: set[str] = set()
+    emails: list[str] = []
+    for contact in contacts:
+        email = (contact.email or "").strip()
+        if email and email not in seen:
+            seen.add(email)
+            emails.append(email)
+
+    if emails:
+        subject = (args.title or args.question).strip()[:_EMAIL_SUBJECT_MAX_LEN]
+        if args.urgency == "high":
+            subject = f"[Action needed] {subject}"
+        body = f"{args.question}\n\nOpen the request: {EmailDeliveryConfig.URL_PLACEHOLDER}"
+        methods.append(
+            EmailDeliveryMethod(
+                config=EmailDeliveryConfig(
+                    recipients=EmailRecipients(items=[ExternalRecipient(email=email) for email in emails]),
+                    subject=subject,
+                    body=body,
+                )
+            )
+        )
+    return methods
+
+
+@dataclass(frozen=True, slots=True)
+class AskHumanFormCreated:
+    """A created ask_human HITL form, owner-agnostic (workflow run or conversation)."""
+
+    form_id: str
+    args: AskHumanToolArgs
+    node_data: HumanInputNodeData
+    node_title: str
+    resolved_default_values: dict[str, Any]
+
+
+def create_ask_human_form(
+    *,
+    deferred_tool_call: DeferredToolCallPayload,
+    node_id: str,
+    default_node_title: str,
+    contacts: Sequence[AgentHumanContactConfig],
+    repository: HumanInputFormRepository,
+    workflow_run_id: str | None = None,
+    conversation_id: str | None = None,
+    display_in_ui: bool = True,
+) -> AskHumanFormCreated:
+    """Create a HITL form from an ask_human deferred call (caller verified tool_name).
+
+    The form is owned by exactly one of ``workflow_run_id`` (workflow Agent node)
+    or ``conversation_id`` (Agent v2 chat). Raises ``AskHumanFormBuildError`` on
+    invalid args, a missing owner, or a repository failure.
+    """
+    if not workflow_run_id and not conversation_id:
+        raise AskHumanFormBuildError("an ask_human HITL form requires a workflow_run_id or conversation_id")
+
+    args = parse_ask_human_args(deferred_tool_call.args)
+    node_title = args.title or default_node_title
+    node_data = ask_human_args_to_node_data(args, node_title=node_title)
+    resolved_default_values = _resolved_default_values(args)
+
+    try:
+        form = repository.create_form(
+            FormCreateParams(
+                workflow_execution_id=workflow_run_id,
+                conversation_id=conversation_id,
+                node_id=node_id,
+                form_config=node_data,
+                # No workflow-variable placeholders to resolve — the content is
+                # fully model-authored, so rendered == template.
+                rendered_content=node_data.form_content,
+                delivery_methods=build_delivery_methods(contacts, args=args),
+                display_in_ui=display_in_ui,
+                resolved_default_values=resolved_default_values,
+            )
+        )
+    except ValueError as error:
+        raise AskHumanFormBuildError(f"failed to create ask_human HITL form: {error}") from error
+
+    return AskHumanFormCreated(
+        form_id=form.id,
+        args=args,
+        node_data=node_data,
+        node_title=node_title,
+        resolved_default_values=resolved_default_values,
+    )
+
+
+def build_ask_human_pause_reason(
+    *,
+    deferred_tool_call: DeferredToolCallPayload,
+    node_id: str,
+    default_node_title: str,
+    workflow_run_id: str | None,
+    contacts: Sequence[AgentHumanContactConfig],
+    repository: HumanInputFormRepository,
+    conversation_id: str | None = None,
+    expected_tool_name: str = DEFAULT_ASK_HUMAN_TOOL_NAME,
+    display_in_ui: bool = True,
+) -> HumanInputRequired | None:
+    """Create a workflow HITL form for an ask_human call and return its pause reason.
+
+    Returns ``None`` when the deferred call is *not* the ask_human tool, letting
+    the caller fall back to a generic scheduling pause. Raises
+    ``AskHumanFormBuildError`` when the call is ask_human but its args or the form
+    cannot be built — the caller should surface that as a node failure rather
+    than a silent, unresumable pause.
+    """
+    if deferred_tool_call.tool_name != expected_tool_name:
+        return None
+    if not workflow_run_id:
+        raise AskHumanFormBuildError("workflow_run_id is required to create an ask_human HITL form")
+
+    created = create_ask_human_form(
+        deferred_tool_call=deferred_tool_call,
+        node_id=node_id,
+        default_node_title=default_node_title,
+        contacts=contacts,
+        repository=repository,
+        workflow_run_id=workflow_run_id,
+        # A chatflow agent node also belongs to a conversation; tag the form so it is
+        # queryable per conversation. None for a pure workflow run (workflow_run_id only).
+        conversation_id=conversation_id,
+        display_in_ui=display_in_ui,
+    )
+    return HumanInputRequired(
+        form_id=created.form_id,
+        form_content=created.node_data.form_content,
+        inputs=list(created.node_data.inputs),
+        actions=list(created.node_data.user_actions),
+        node_id=node_id,
+        node_title=created.node_title,
+        resolved_default_values=created.resolved_default_values,
+    )
+
+
+__all__ = [
+    "DEFAULT_ASK_HUMAN_TOOL_NAME",
+    "AskHumanFormBuildError",
+    "AskHumanFormCreated",
+    "ask_human_args_to_node_data",
+    "build_ask_human_pause_reason",
+    "build_delivery_methods",
+    "create_ask_human_form",
+    "parse_ask_human_args",
+]

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

@@ -0,0 +1,159 @@
+"""Resume an Agent run after a dify.ask_human HITL form reaches a terminal state.
+
+ENG-638. When the outer workflow resumes (the human submitted the form, or it
+timed out), graphon re-executes the Agent node's ``_run``. This module reads the
+correlated HITL form (by ``pending_form_id``) and maps it back into the
+agent-side ``dify.ask_human`` contract so the node can start a *second* Agent run
+that carries the human's answer:
+
+* submitted  -> AskHumanToolResult(status="submitted", action, values)
+* timeout / expired -> AskHumanToolResult(status="timeout")
+* still waiting (defensive: the host resumed us early) -> re-emit the same
+  HumanInputRequired pause rebuilt from the stored form definition.
+
+It only *reads* existing HITL form state — it never mutates the form or the HITL
+submission flow. The DB read (``resolve_ask_human_form``) is kept thin so the
+mapping (``map_form_to_outcome``) stays pure and unit-testable.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from dify_agent.layers.ask_human import (
+    AskHumanResultStatus,
+    AskHumanSelectedAction,
+    AskHumanToolResult,
+)
+from dify_agent.protocol import DeferredToolResultsPayload
+from pydantic import JsonValue
+from sqlalchemy import select
+
+from core.db.session_factory import session_factory
+from graphon.entities.pause_reason import HumanInputRequired
+from graphon.nodes.human_input.entities import FormDefinition
+from graphon.nodes.human_input.enums import HumanInputFormStatus
+from models.human_input import HumanInputForm
+
+# A WAITING form has not been answered yet; the other terminal states map onto
+# the agent-facing result status. EXPIRED (global timeout) and TIMEOUT
+# (node-level) both surface to the model as "timeout" so it can react.
+_FORM_STATUS_TO_RESULT: dict[HumanInputFormStatus, AskHumanResultStatus] = {
+    HumanInputFormStatus.SUBMITTED: "submitted",
+    HumanInputFormStatus.TIMEOUT: "timeout",
+    HumanInputFormStatus.EXPIRED: "timeout",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class AskHumanResumeOutcome:
+    """Result of inspecting a correlated ask_human form on workflow resume.
+
+    Exactly one of ``deferred_result`` / ``repause`` is set:
+    * ``deferred_result`` — the form reached a terminal state; start the second run.
+    * ``repause`` — the form is still waiting; re-emit this pause defensively.
+    """
+
+    deferred_result: AskHumanToolResult | None = None
+    repause: HumanInputRequired | None = None
+
+
+def resolve_ask_human_form(*, form_id: str, tenant_id: str, node_id: str) -> AskHumanResumeOutcome | None:
+    """Load the correlated form and map it to a resume outcome.
+
+    Returns ``None`` when the form no longer exists (correlation lost) — the
+    caller should fall back to a normal (non-resume) Agent run.
+    """
+    with session_factory.create_session() as session:
+        form = session.scalar(
+            select(HumanInputForm).where(
+                HumanInputForm.id == form_id,
+                HumanInputForm.tenant_id == tenant_id,
+            )
+        )
+        if form is None:
+            return None
+        return map_form_to_outcome(
+            status=form.status,
+            selected_action_id=form.selected_action_id,
+            submitted_data=form.submitted_data,
+            rendered_content=form.rendered_content,
+            form_definition=form.form_definition,
+            form_id=form.id,
+            node_id=node_id,
+        )
+
+
+def map_form_to_outcome(
+    *,
+    status: HumanInputFormStatus,
+    selected_action_id: str | None,
+    submitted_data: str | None,
+    rendered_content: str,
+    form_definition: str,
+    form_id: str,
+    node_id: str,
+) -> AskHumanResumeOutcome:
+    """Map a terminal (or still-waiting) HITL form to a resume outcome. Pure."""
+    definition = FormDefinition.model_validate_json(form_definition)
+    if status == HumanInputFormStatus.WAITING:
+        return AskHumanResumeOutcome(repause=_rebuild_pause(definition=definition, form_id=form_id, node_id=node_id))
+
+    result_status = _FORM_STATUS_TO_RESULT.get(status, "unavailable")
+    if result_status != "submitted":
+        return AskHumanResumeOutcome(deferred_result=AskHumanToolResult(status=result_status))
+    return AskHumanResumeOutcome(
+        deferred_result=AskHumanToolResult(
+            status="submitted",
+            action=_selected_action(selected_action_id=selected_action_id, definition=definition),
+            values=_submitted_values(submitted_data),
+            rendered_content=rendered_content,
+        )
+    )
+
+
+def build_deferred_tool_results(*, tool_call_id: str, result: AskHumanToolResult) -> DeferredToolResultsPayload:
+    """Wrap an ask_human result as the deferred-tool-results payload for resume."""
+    return DeferredToolResultsPayload(calls={tool_call_id: result.model_dump(mode="json")})
+
+
+def _submitted_values(submitted_data: str | None) -> dict[str, JsonValue]:
+    if not submitted_data:
+        return {}
+    parsed = json.loads(submitted_data)
+    if not isinstance(parsed, dict):
+        return {}
+    return {str(key): value for key, value in parsed.items()}
+
+
+def _selected_action(*, selected_action_id: str | None, definition: FormDefinition) -> AskHumanSelectedAction | None:
+    if selected_action_id is None:
+        return None
+    # The form's user_action title is the verbatim ask_human action label set at
+    # form-build time; fall back to the id only if the action is somehow missing.
+    label = next(
+        (action.title for action in definition.user_actions if action.id == selected_action_id),
+        selected_action_id,
+    )
+    return AskHumanSelectedAction(id=selected_action_id, label=label)
+
+
+def _rebuild_pause(*, definition: FormDefinition, form_id: str, node_id: str) -> HumanInputRequired:
+    return HumanInputRequired(
+        form_id=form_id,
+        form_content=definition.rendered_content or definition.form_content,
+        inputs=list(definition.inputs),
+        actions=list(definition.user_actions),
+        node_id=node_id,
+        node_title=definition.node_title or node_id,
+        resolved_default_values=dict(definition.default_values),
+    )
+
+
+__all__ = [
+    "AskHumanResumeOutcome",
+    "build_deferred_tool_results",
+    "map_form_to_outcome",
+    "resolve_ask_human_form",
+]

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

@@ -15,20 +15,28 @@ SUPPORTED_AGENT_BACKEND_FEATURES = frozenset(
         "tools.cli_tools",
         "env",
         "sandbox",
+        # ENG-623: exposed at runtime as the dify.drive declaration layer
+        # (an index the agent pulls through the back proxy).
+        "skills_files",
+        # ENG-635: human involvement is exposed at runtime as the dify.ask_human
+        # deferred tool; a call pauses via the existing HITL form mechanism.
+        "human",
     }
 )
 
 RESERVED_AGENT_BACKEND_FEATURES = frozenset(
     {
-        "skills_files",
         "knowledge",
-        "human",
         "memory",
     }
 )
 
 
-def build_runtime_feature_manifest(agent_soul: AgentSoulConfig) -> dict[str, Any]:
+def build_runtime_feature_manifest(
+    agent_soul: AgentSoulConfig,
+    *,
+    drive_manifest_enabled: bool = False,
+) -> dict[str, Any]:
     """Describe PRD capabilities supported by or still reserved from Agent backend runtime."""
     warnings: list[dict[str, str]] = []
     soul_dump = agent_soul.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
@@ -46,11 +54,40 @@ def build_runtime_feature_manifest(agent_soul: AgentSoulConfig) -> dict[str, Any
                 }
             )
 
+    has_skills_files = bool(agent_soul.skills_files.skills or agent_soul.skills_files.files)
+    if has_skills_files and not drive_manifest_enabled:
+        warnings.append(
+            {
+                "section": "agent_soul.skills_files",
+                "code": "drive_manifest_disabled",
+                "message": (
+                    "skills_files is configured but AGENT_DRIVE_MANIFEST_ENABLED is off; "
+                    "the drive declaration layer is not injected into this run."
+                ),
+            }
+        )
+    for skill in agent_soul.skills_files.skills:
+        if not skill.skill_md_key:
+            warnings.append(
+                {
+                    "section": "agent_soul.skills_files",
+                    "code": "skill_ref_dangling",
+                    "message": (
+                        f"skill_ref_dangling: skill '{skill.name or skill.id or 'unknown'}' has no drive key; "
+                        "re-standardize it to expose it at runtime."
+                    ),
+                }
+            )
+
     reserved_status = dict.fromkeys(sorted(RESERVED_AGENT_BACKEND_FEATURES), "reserved_not_executed")
+    reserved_status["skills_files"] = (
+        "supported_by_drive_manifest" if drive_manifest_enabled else "drive_manifest_disabled"
+    )
     reserved_status["tools.dify_tools"] = "supported_when_config_valid"
     reserved_status["tools.cli_tools"] = "supported_by_shell_bootstrap"
     reserved_status["env"] = "supported_by_shell_bootstrap"
     reserved_status["sandbox"] = "forwarded_to_shell_layer_config"
+    reserved_status["human"] = "supported_by_ask_human_hitl" if agent_soul.human.contacts else "not_configured"
 
     return {
         "supported": sorted(SUPPORTED_AGENT_BACKEND_FEATURES),

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

@@ -5,6 +5,12 @@ from dataclasses import dataclass
 from typing import Any, Literal, Protocol, assert_never, cast
 
 from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.layers.ask_human import DifyAskHumanLayerConfig
+from dify_agent.layers.drive import (
+    DifyDriveFileConfig,
+    DifyDriveLayerConfig,
+    DifyDriveSkillConfig,
+)
 from dify_agent.layers.execution_context import (
     DifyExecutionContextInvokeFrom,
     DifyExecutionContextLayerConfig,
@@ -17,7 +23,7 @@ from dify_agent.layers.shell import (
     DifyShellSandboxConfig,
     DifyShellSecretRefConfig,
 )
-from dify_agent.protocol import CreateRunRequest
+from dify_agent.protocol import CreateRunRequest, DeferredToolResultsPayload
 from pydantic import BaseModel
 
 from clients.agent_backend import (
@@ -98,6 +104,9 @@ class WorkflowAgentRuntimeBuildContext:
     # idempotency key so the backend treats each retry as a fresh request.
     attempt: int = 0
     session_snapshot: CompositorSessionSnapshot | None = None
+    # ENG-638: set when resuming after a submitted ask_human HITL form; threads
+    # the human's answer back into the second Agent run keyed by tool_call_id.
+    deferred_tool_results: DeferredToolResultsPayload | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -169,6 +178,11 @@ class WorkflowAgentRuntimeRequestBuilder:
                 "cli_tool_count": len(agent_soul.tools.cli_tools),
             }
 
+        drive_config: DifyDriveLayerConfig | None = None
+        if dify_config.AGENT_DRIVE_MANIFEST_ENABLED:
+            drive_config, drive_warnings = build_drive_layer_config(agent_soul, agent_id=context.agent.id)
+            append_runtime_warnings(metadata, drive_warnings)
+
         request = self._request_builder.build_for_workflow_node(
             AgentBackendWorkflowNodeRunInput(
                 model=AgentBackendModelConfig(
@@ -206,9 +220,12 @@ class WorkflowAgentRuntimeRequestBuilder:
                 user_prompt=user_prompt,
                 output=self._build_output_config(node_job.declared_outputs),
                 tools=tools_layer,
+                drive_config=drive_config,
+                ask_human_config=build_ask_human_layer_config(agent_soul),
                 include_shell=dify_config.AGENT_SHELL_ENABLED,
                 shell_config=build_shell_layer_config(agent_soul),
                 session_snapshot=context.session_snapshot,
+                deferred_tool_results=context.deferred_tool_results,
                 idempotency_key=self._idempotency_key(context),
                 metadata=metadata,
             )
@@ -269,7 +286,10 @@ class WorkflowAgentRuntimeRequestBuilder:
             "agent_config_snapshot_id": context.snapshot.id,
             "binding_id": context.binding.id,
             "workflow_node_job_mode": node_job.mode.value,
-            "runtime_support": build_runtime_feature_manifest(agent_soul),
+            "runtime_support": build_runtime_feature_manifest(
+                agent_soul,
+                drive_manifest_enabled=dify_config.AGENT_DRIVE_MANIFEST_ENABLED,
+            ),
         }
 
     def _build_workflow_context_prompt(
@@ -482,6 +502,103 @@ def build_shell_layer_config(agent_soul: AgentSoulConfig) -> DifyShellLayerConfi
     )
 
 
+def build_ask_human_layer_config(agent_soul: AgentSoulConfig) -> DifyAskHumanLayerConfig | None:
+    """Enable the dify.ask_human deferred tool when the soul configures human involvement.
+
+    HITL is opt-in: only when at least one human contact is configured does the
+    model get the ``ask_human`` tool (recipients for the resulting form come from
+    those contacts, ENG-635). Returns ``None`` to leave the tool off entirely.
+    The tool/field guardrails use the layer defaults; ``human.tools`` semantics are
+    out of scope this round.
+    """
+    if not agent_soul.human.contacts:
+        return None
+    return DifyAskHumanLayerConfig()
+
+
+def append_runtime_warnings(metadata: dict[str, Any], warnings: list[dict[str, str]]) -> None:
+    """Merge build-time warnings into the metadata runtime-support manifest."""
+    if not warnings:
+        return
+    manifest = metadata.setdefault("runtime_support", {})
+    if isinstance(manifest, dict):
+        existing = manifest.setdefault("unsupported_runtime_warnings", [])
+        if isinstance(existing, list):
+            existing.extend(warnings)
+
+
+def build_drive_layer_config(
+    agent_soul: AgentSoulConfig,
+    *,
+    agent_id: str | None,
+) -> tuple[DifyDriveLayerConfig | None, list[dict[str, str]]]:
+    """Catalog the soul's drive-backed Skills & Files into the dify.drive declaration.
+
+    Returns ``(config, warnings)`` — ``config is None`` means nothing to inject
+    (no skills/files configured, or no agent identity to address the drive by).
+    Refs that predate standardization (no drive key) are skipped with a warning
+    instead of failing the run, so historic souls keep running.
+    """
+    skill_refs = agent_soul.skills_files.skills
+    file_refs = agent_soul.skills_files.files
+    if not skill_refs and not file_refs:
+        return None, []
+
+    warnings: list[dict[str, str]] = []
+    if not agent_id:
+        warnings.append(
+            {
+                "section": "agent_soul.skills_files",
+                "code": "skill_ref_dangling",
+                "message": "skills_files is configured but the run has no bound agent to address a drive by.",
+            }
+        )
+        return None, warnings
+
+    skills: list[DifyDriveSkillConfig] = []
+    for skill in skill_refs:
+        if not skill.skill_md_key:
+            warnings.append(
+                {
+                    "section": "agent_soul.skills_files",
+                    "code": "skill_ref_dangling",
+                    "message": (
+                        f"skill_ref_dangling: skill '{skill.name or skill.id or 'unknown'}' has no drive key; "
+                        "re-standardize it to expose it at runtime."
+                    ),
+                }
+            )
+            continue
+        skills.append(
+            DifyDriveSkillConfig(
+                name=skill.name or skill.skill_md_key.split("/", 1)[0],
+                description=skill.description or "",
+                skill_md_key=skill.skill_md_key,
+                archive_key=skill.full_archive_key,
+            )
+        )
+
+    files: list[DifyDriveFileConfig] = []
+    for file in file_refs:
+        if not file.drive_key:
+            # Plain upload references (pre-ENG-625) are not drive-backed; they are
+            # simply invisible to the manifest rather than a defect worth warning on.
+            continue
+        size = file.get("size")
+        files.append(
+            DifyDriveFileConfig(
+                name=file.name or file.drive_key.rsplit("/", 1)[-1],
+                key=file.drive_key,
+                size=size if isinstance(size, int) else None,
+                mime_type=file.type,
+            )
+        )
+
+    if not skills and not files:
+        return None, warnings
+    return DifyDriveLayerConfig(drive_ref=f"agent-{agent_id}", skills=skills, files=files), warnings
+
+
 def _cli_tool_enabled(item: object) -> bool:
     """A CLI tool is bootstrapped unless explicitly disabled (default is enabled)."""
     data = _plain_mapping(item)

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

@@ -47,12 +47,20 @@ class StoredWorkflowAgentSession:
     session_snapshot: CompositorSessionSnapshot
     backend_run_id: str | None
     runtime_layer_specs: list[RuntimeLayerSpec] = field(default_factory=list)
+    # ENG-637: set while the session is paused on a dify.ask_human deferred call.
+    pending_form_id: str | None = None
+    pending_tool_call_id: str | None = None
 
 
 class WorkflowAgentRuntimeSessionStore:
     """Stores Agent backend session snapshots for workflow Agent node re-entry."""
 
     def load_active_snapshot(self, scope: WorkflowAgentSessionScope) -> 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: WorkflowAgentSessionScope) -> StoredWorkflowAgentSession | None:
+        """Load the active session row including any pending ask_human correlation."""
         if scope.workflow_run_id is None:
             return None
 
@@ -69,7 +77,14 @@ class WorkflowAgentRuntimeSessionStore:
             )
             if row is None:
                 return None
-            return CompositorSessionSnapshot.model_validate_json(row.session_snapshot)
+            return StoredWorkflowAgentSession(
+                scope=scope,
+                session_snapshot=CompositorSessionSnapshot.model_validate_json(row.session_snapshot),
+                backend_run_id=row.backend_run_id,
+                runtime_layer_specs=_deserialize_specs(row.composition_layer_specs),
+                pending_form_id=row.pending_form_id,
+                pending_tool_call_id=row.pending_tool_call_id,
+            )
 
     def list_active_sessions(self, *, workflow_run_id: str) -> list[StoredWorkflowAgentSession]:
         with session_factory.create_session() as session:
@@ -109,6 +124,8 @@ class WorkflowAgentRuntimeSessionStore:
         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:
         if scope.workflow_run_id is None or snapshot is None:
             return
@@ -141,6 +158,8 @@ class WorkflowAgentRuntimeSessionStore:
                     session_snapshot=snapshot_json,
                     composition_layer_specs=specs_json,
                     status=WorkflowAgentRuntimeSessionStatus.ACTIVE,
+                    pending_form_id=pending_form_id,
+                    pending_tool_call_id=pending_tool_call_id,
                 )
                 session.add(row)
             else:
@@ -151,6 +170,9 @@ class WorkflowAgentRuntimeSessionStore:
                 row.composition_layer_specs = specs_json
                 row.status = WorkflowAgentRuntimeSessionStatus.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.commit()
 
     def mark_cleaned(self, *, scope: WorkflowAgentSessionScope, backend_run_id: str | None = None) -> None:

api/extensions/ext_celery.py

@@ -153,6 +153,7 @@ def init_app(app: DifyApp) -> Celery:
         "tasks.trigger_processing_tasks",  # async trigger processing
         "tasks.generate_summary_index_task",  # summary index generation
         "tasks.regenerate_summary_index_task",  # summary index regeneration
+        "tasks.app_generate.resume_agent_app_task",  # ENG-635: Agent v2 chat ask_human resume
     ]
     day = dify_config.CELERY_BEAT_SCHEDULER_TIME
 

api/extensions/ext_commands.py

@@ -5,6 +5,7 @@ def init_app(app: DifyApp):
     from commands import (
         add_qdrant_index,
         archive_workflow_runs,
+        backfill_plugin_auto_upgrade,
         clean_expired_messages,
         clean_workflow_runs,
         cleanup_orphaned_draft_variables,
@@ -53,6 +54,7 @@ def init_app(app: DifyApp):
         upgrade_db,
         fix_app_site_missing,
         migrate_data_for_plugin,
+        backfill_plugin_auto_upgrade,
         extract_plugins,
         extract_unique_plugins,
         install_plugins,

api/fields/agent_fields.py

@@ -44,7 +44,11 @@ class AgentConfigSnapshotSummaryResponse(ResponseModel):
 class AgentPublishedReferenceResponse(ResponseModel):
     app_id: str
     app_name: str
+    app_icon_type: str | None = None
+    app_icon: str | None = None
+    app_icon_background: str | None = None
     app_mode: str
+    app_updated_at: int | None = None
     workflow_id: str
     workflow_version: str
     node_ids: list[str] = Field(default_factory=list)

api/migrations/versions/2026_06_15_1052-c167a72a00eb_add_ask_human_pause_correlation_to_.py

@@ -0,0 +1,32 @@
+"""add ask_human pause correlation to agent_runtime_sessions
+
+Revision ID: c167a72a00eb
+Revises: c4d5e6f7a8b9
+Create Date: 2026-06-15 10:52:15.736666
+
+"""
+from alembic import op
+import models as models
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = 'c167a72a00eb'
+down_revision = 'c4d5e6f7a8b9'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ENG-637: correlate a paused dify.ask_human session to its awaiting HITL
+    # form and the deferred tool_call id, so the resumed Agent node can rebuild
+    # deferred_tool_results from the submitted form. Both columns are nullable
+    # and NULL whenever the session is not paused on human input.
+    with op.batch_alter_table('agent_runtime_sessions', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('pending_form_id', models.types.StringUUID(), nullable=True))
+        batch_op.add_column(sa.Column('pending_tool_call_id', sa.String(length=255), nullable=True))
+
+
+def downgrade():
+    with op.batch_alter_table('agent_runtime_sessions', schema=None) as batch_op:
+        batch_op.drop_column('pending_tool_call_id')
+        batch_op.drop_column('pending_form_id')

api/migrations/versions/2026_06_15_1100-b7c2d9e8a1f4_add_tenant_last_opened_at.py

@@ -0,0 +1,26 @@
+"""add tenant account join last opened at
+
+Revision ID: b7c2d9e8a1f4
+Revises: 9f4b7c2d1a80
+Create Date: 2026-06-05 11:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "b7c2d9e8a1f4"
+down_revision = "9f4b7c2d1a80"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    with op.batch_alter_table("tenant_account_joins", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("last_opened_at", sa.DateTime(), nullable=True))
+
+
+def downgrade():
+    with op.batch_alter_table("tenant_account_joins", schema=None) as batch_op:
+        batch_op.drop_column("last_opened_at")

api/migrations/versions/2026_06_15_1110-d2f1a4b8c3e0_add_conversation_id_to_human_input_forms.py

@@ -0,0 +1,29 @@
+"""add conversation_id to human_input_forms for agent v2 chat hitl
+
+Revision ID: d2f1a4b8c3e0
+Revises: c167a72a00eb
+Create Date: 2026-06-15 11:10:00.000000
+
+"""
+from alembic import op
+import models as models
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = 'd2f1a4b8c3e0'
+down_revision = 'c167a72a00eb'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ENG-635: Agent v2 chat ask_human forms are owned by a conversation turn
+    # instead of a workflow run (the new Agent App has no workflow_run_id).
+    # Nullable; existing workflow-owned forms keep conversation_id NULL.
+    with op.batch_alter_table('human_input_forms', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('conversation_id', models.types.StringUUID(), nullable=True))
+
+
+def downgrade():
+    with op.batch_alter_table('human_input_forms', schema=None) as batch_op:
+        batch_op.drop_column('conversation_id')

api/migrations/versions/2026_06_15_1200-f6a7b8c9d012_add_plugin_auto_upgrade_category.py

@@ -0,0 +1,42 @@
+"""add plugin auto upgrade category
+
+Revision ID: f6a7b8c9d012
+Revises: b7c2d9e8a1f4
+Create Date: 2026-05-15 12:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "f6a7b8c9d012"
+down_revision = "b7c2d9e8a1f4"
+branch_labels = None
+depends_on = None
+
+
+LEGACY_CATEGORY = "tool"
+UNIQUE_CONSTRAINT_NAME = "unique_tenant_plugin_auto_upgrade_strategy"
+UPGRADE_TIME_INDEX_NAME = "idx_tenant_plugin_auto_upgrade_strategy_time"
+STRATEGY_TABLE_NAME = "tenant_plugin_auto_upgrade_strategies"
+
+
+def upgrade():
+    with op.batch_alter_table(STRATEGY_TABLE_NAME, schema=None) as batch_op:
+        batch_op.add_column(
+            sa.Column("category", sa.String(length=32), server_default=LEGACY_CATEGORY, nullable=False)
+        )
+        batch_op.drop_constraint(UNIQUE_CONSTRAINT_NAME, type_="unique")
+        batch_op.create_unique_constraint(UNIQUE_CONSTRAINT_NAME, ["tenant_id", "category"])
+        batch_op.create_index(UPGRADE_TIME_INDEX_NAME, ["upgrade_time_of_day"])
+
+
+def downgrade():
+    op.execute(sa.text(f"DELETE FROM {STRATEGY_TABLE_NAME} WHERE category != '{LEGACY_CATEGORY}'"))
+
+    with op.batch_alter_table(STRATEGY_TABLE_NAME, schema=None) as batch_op:
+        batch_op.drop_index(UPGRADE_TIME_INDEX_NAME)
+        batch_op.drop_constraint(UNIQUE_CONSTRAINT_NAME, type_="unique")
+        batch_op.drop_column("category")
+        batch_op.create_unique_constraint(UNIQUE_CONSTRAINT_NAME, ["tenant_id"])

api/migrations/versions/2026_06_15_1300-f5e8a9c0d2b3_add_learn_dify_flag_to_recommended_apps.py

@@ -0,0 +1,26 @@
+"""add learn dify flag to recommended apps
+
+Revision ID: f5e8a9c0d2b3
+Revises: f6a7b8c9d012
+Create Date: 2026-05-18 15:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "f5e8a9c0d2b3"
+down_revision = "f6a7b8c9d012"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    with op.batch_alter_table("recommended_apps", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("is_learn_dify", sa.Boolean(), server_default=sa.text("false"), nullable=False))
+
+
+def downgrade():
+    with op.batch_alter_table("recommended_apps", schema=None) as batch_op:
+        batch_op.drop_column("is_learn_dify")

api/migrations/versions/2026_06_15_1400-c4d5e6f7a8b9_add_app_stars.py

@@ -0,0 +1,38 @@
+"""add app stars
+
+Revision ID: c4d5e6f7a8b9
+Revises: f5e8a9c0d2b3
+Create Date: 2026-06-08 12:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+import models.types
+
+# revision identifiers, used by Alembic.
+revision = "c4d5e6f7a8b9"
+down_revision = "f5e8a9c0d2b3"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "app_stars",
+        sa.Column("id", models.types.StringUUID(), nullable=False),
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False),
+        sa.Column("app_id", models.types.StringUUID(), nullable=False),
+        sa.Column("account_id", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name="app_star_pkey"),
+        sa.UniqueConstraint("tenant_id", "account_id", "app_id", name="app_star_tenant_account_app_unique"),
+    )
+    with op.batch_alter_table("app_stars", schema=None) as batch_op:
+        batch_op.create_index("app_star_tenant_account_idx", ["tenant_id", "account_id"], unique=False)
+        batch_op.create_index("app_star_app_idx", ["app_id"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_table("app_stars")

api/models/__init__.py

@@ -73,6 +73,7 @@ from .model import (
     AppMCPServer,
     AppMode,
     AppModelConfig,
+    AppStar,
     Conversation,
     DatasetRetrieverResource,
     DifySetup,
@@ -175,6 +176,7 @@ __all__ = [
     "AppMCPServer",
     "AppMode",
     "AppModelConfig",
+    "AppStar",
     "AppTrigger",
     "AppTriggerStatus",
     "AppTriggerType",

api/models/account.py

@@ -301,6 +301,7 @@ class TenantAccountJoin(TypeBase):
     updated_at: Mapped[datetime] = mapped_column(
         DateTime, server_default=func.current_timestamp(), nullable=False, init=False, onupdate=func.current_timestamp()
     )
+    last_opened_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True, default=None)
 
 
 class AccountIntegrate(TypeBase):
@@ -389,6 +390,14 @@ class TenantPluginPermission(TypeBase):
 
 
 class TenantPluginAutoUpgradeStrategy(TypeBase):
+    class PluginCategory(enum.StrEnum):
+        TOOL = "tool"
+        MODEL = "model"
+        EXTENSION = "extension"
+        AGENT_STRATEGY = "agent-strategy"
+        DATASOURCE = "datasource"
+        TRIGGER = "trigger"
+
     class StrategySetting(enum.StrEnum):
         DISABLED = "disabled"
         FIX_ONLY = "fix_only"
@@ -402,13 +411,20 @@ class TenantPluginAutoUpgradeStrategy(TypeBase):
     __tablename__ = "tenant_plugin_auto_upgrade_strategies"
     __table_args__ = (
         sa.PrimaryKeyConstraint("id", name="tenant_plugin_auto_upgrade_strategy_pkey"),
-        sa.UniqueConstraint("tenant_id", name="unique_tenant_plugin_auto_upgrade_strategy"),
+        sa.UniqueConstraint("tenant_id", "category", name="unique_tenant_plugin_auto_upgrade_strategy"),
+        sa.Index("idx_tenant_plugin_auto_upgrade_strategy_time", "upgrade_time_of_day"),
     )
 
     id: Mapped[str] = mapped_column(
         StringUUID, insert_default=lambda: str(uuid4()), default_factory=lambda: str(uuid4()), init=False
     )
     tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    category: Mapped[PluginCategory] = mapped_column(
+        EnumText(PluginCategory, length=32),
+        nullable=False,
+        server_default="tool",
+        default=PluginCategory.TOOL,
+    )
     strategy_setting: Mapped[StrategySetting] = mapped_column(
         EnumText(StrategySetting, length=16),
         nullable=False,

api/models/agent.py

@@ -38,6 +38,8 @@ class AgentScope(StrEnum):
 class AgentSource(StrEnum):
     """Origin that created or imported the Agent."""
 
+    # Created directly as a reusable Agent Roster asset.
+    ROSTER = "roster"
     # Created from an Agent App composer.
     AGENT_APP = "agent_app"
     # Created from a Workflow Agent Composer flow.
@@ -396,6 +398,12 @@ class AgentRuntimeSession(DefaultFieldsMixin, Base):
         default=AgentRuntimeSessionStatus.ACTIVE,
     )
     cleaned_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    # ENG-637: when a run pauses for a dify.ask_human deferred call, these link
+    # the session to the awaiting HITL form and the deferred tool_call_id, so a
+    # resumed node can map the submitted form back into deferred_tool_results.
+    # Both NULL whenever the session is not paused on human input.
+    pending_form_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
+    pending_tool_call_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
 
 
 # Back-compat alias for the shipped workflow lifecycle code (PR #36724).

api/models/agent_config_entities.py

@@ -99,6 +99,10 @@ class AgentFileRefConfig(AgentFlexibleConfig):
     transfer_method: str | None = Field(default=None, max_length=64)
     url: str | None = None
     remote_url: str | None = None
+    # Drive key once the file is committed to the agent drive ("files/<name>",
+    # ENG-625). Files without it are plain upload references and stay invisible
+    # to the runtime drive manifest.
+    drive_key: str | None = Field(default=None, max_length=512)
 
 
 class AgentSkillRefConfig(AgentFlexibleConfig):
@@ -107,6 +111,16 @@ class AgentSkillRefConfig(AgentFlexibleConfig):
     description: str | None = None
     file_id: str | None = Field(default=None, max_length=255)
     path: str | None = None
+    # Standardization outputs (ENG-594) — previously riding along via
+    # ``extra="allow"``, promoted to the explicit schema because the runtime
+    # drive manifest (ENG-623) keys off them.
+    skill_md_key: str | None = Field(default=None, max_length=512)
+    skill_md_file_id: str | None = Field(default=None, max_length=255)
+    full_archive_key: str | None = Field(default=None, max_length=512)
+    full_archive_file_id: str | None = Field(default=None, max_length=255)
+    # Zip member path listing from standardization (ENG-371): lets infer-tools
+    # show the model strong signals like ``scripts/*.sh`` without unpacking.
+    manifest_files: list[str] | None = None
 
 
 class AgentPermissionConfig(BaseModel):
@@ -175,6 +189,10 @@ class AgentCliToolConfig(AgentFlexibleConfig):
     risk_accepted: bool = False
     approved: bool = False
     risk_level: AgentCliToolRiskLevel | None = None
+    # Slug of the skill an infer-tools suggestion came from (ENG-371); drives
+    # the "inferred from <skill>" badge. Plain provenance metadata — saving an
+    # inferred tool still passes every composer validation rule.
+    inferred_from: str | None = Field(default=None, max_length=255)
 
 
 class AgentKnowledgeDatasetConfig(AgentFlexibleConfig):

api/models/human_input.py

@@ -40,6 +40,13 @@ class HumanInputForm(DefaultFieldsMixin, Base):
     tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
     app_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
     workflow_run_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
+    # ENG-635: a RUNTIME form is tagged with its owning workflow run and/or its
+    # conversation. Workflow / Human-Input / agent-node forms always set
+    # workflow_run_id, and ALSO set conversation_id when the run has a conversation
+    # (chatflow / advanced-chat). Agent v2 chat ask_human forms set only
+    # conversation_id (the new Agent App has no workflow_run_id). At least one is set;
+    # resume routing prefers workflow_run_id when both are present.
+    conversation_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
     form_kind: Mapped[HumanInputFormKind] = mapped_column(
         EnumText(HumanInputFormKind),
         nullable=False,

api/models/model.py

@@ -397,6 +397,12 @@ class App(Base):
     __tablename__ = "apps"
     __table_args__ = (sa.PrimaryKeyConstraint("id", name="app_pkey"), sa.Index("app_tenant_id_idx", "tenant_id"))
 
+    if TYPE_CHECKING:
+        # Response-only attributes attached by app list/detail enrichers.
+        access_mode: str | None
+        has_draft_trigger: bool
+        is_starred: bool
+
     id: Mapped[str] = mapped_column(StringUUID, default=lambda: str(uuid4()))
     tenant_id: Mapped[str] = mapped_column(StringUUID)
     name: Mapped[str] = mapped_column(String(255))
@@ -654,6 +660,28 @@ class App(Base):
         return None
 
 
+class AppStar(Base):
+    """Account-scoped star marker for apps in a workspace."""
+
+    __tablename__ = "app_stars"
+    __table_args__ = (
+        sa.PrimaryKeyConstraint("id", name="app_star_pkey"),
+        sa.UniqueConstraint("tenant_id", "account_id", "app_id", name="app_star_tenant_account_app_unique"),
+        sa.Index("app_star_tenant_account_idx", "tenant_id", "account_id"),
+        sa.Index("app_star_app_idx", "app_id"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, default=lambda: str(uuidv7()))
+    tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    app_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    account_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(sa.DateTime, nullable=False, server_default=func.current_timestamp())
+
+    @override
+    def __repr__(self) -> str:
+        return f"<AppStar app_id={self.app_id} account_id={self.account_id}>"
+
+
 class AppModelConfig(TypeBase):
     __tablename__ = "app_model_configs"
     __table_args__ = (sa.PrimaryKeyConstraint("id", name="app_model_config_pkey"), sa.Index("app_app_id_idx", "app_id"))
@@ -907,6 +935,9 @@ class RecommendedApp(TypeBase):
     custom_disclaimer: Mapped[str] = mapped_column(LongText, default="")
     position: Mapped[int] = mapped_column(sa.Integer, nullable=False, default=0)
     is_listed: Mapped[bool] = mapped_column(sa.Boolean, nullable=False, default=True)
+    is_learn_dify: Mapped[bool] = mapped_column(
+        sa.Boolean, nullable=False, server_default=sa.text("false"), default=False
+    )
     install_count: Mapped[int] = mapped_column(sa.Integer, nullable=False, default=0)
     language: Mapped[str] = mapped_column(
         String(255),
@@ -1178,12 +1209,12 @@ class Conversation(Base):
     def inputs(self, value: Mapping[str, Any]):
         inputs = dict(value)
         for k, v in inputs.items():
-            if isinstance(v, File):
-                inputs[k] = v.model_dump()
-            elif isinstance(v, list):
-                v_list = v
-                if all(isinstance(item, File) for item in v_list):
-                    inputs[k] = [item.model_dump() for item in v_list if isinstance(item, File)]
+            match v:
+                case File():
+                    inputs[k] = v.model_dump()
+                case list():
+                    if all(isinstance(item, File) for item in v):
+                        inputs[k] = [item.model_dump() for item in v if isinstance(item, File)]
         self._inputs = inputs
 
     @property

api/providers/vdb/vdb-tidb-on-qdrant/src/dify_vdb_tidb_on_qdrant/tidb_service.py

@@ -1,7 +1,8 @@
 import logging
 import time
 import uuid
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
+from typing import Any
 
 import httpx
 from httpx import DigestAuth
@@ -24,7 +25,7 @@ _tidb_http_client: httpx.Client = get_pooled_http_client(
 
 class TidbService:
     @staticmethod
-    def extract_qdrant_endpoint(cluster_response: dict) -> str | None:
+    def extract_qdrant_endpoint(cluster_response: Mapping[str, Any]) -> str | None:
         """Extract the qdrant endpoint URL from a Get Cluster API response.
 
         Reads ``endpoints.public.host`` (e.g. ``gateway01.xx.tidbcloud.com``),

api/schedule/check_upgradable_plugin_task.py

@@ -73,6 +73,7 @@ def check_upgradable_plugin_task():
                 strategy.upgrade_mode,
                 strategy.exclude_plugins,
                 strategy.include_plugins,
+                strategy.category,
             )
 
         # Only sleep if batch_interval_time > 0.0001 AND current batch is not the last one

api/services/account_service.py

@@ -70,6 +70,7 @@ from services.errors.account import (
 )
 from services.errors.workspace import WorkSpaceNotAllowedCreateError, WorkspacesLimitExceededError
 from services.feature_service import FeatureService
+from services.plugin.plugin_auto_upgrade_service import PluginAutoUpgradeService
 from tasks.delete_account_task import delete_account_task
 from tasks.mail_account_deletion_task import send_account_deletion_verification_code
 from tasks.mail_change_mail_task import (
@@ -263,6 +264,7 @@ class AccountService:
 
             account.set_tenant_id(available_ta.tenant_id)
             available_ta.current = True
+            available_ta.last_opened_at = naive_utc_now()
             db.session.commit()
 
         AccountService._refresh_account_last_active(account)
@@ -1167,15 +1169,17 @@ class TenantService:
         db.session.add(tenant)
         db.session.commit()
 
-        plugin_upgrade_strategy = TenantPluginAutoUpgradeStrategy(
-            tenant_id=tenant.id,
-            strategy_setting=TenantPluginAutoUpgradeStrategy.StrategySetting.FIX_ONLY,
-            upgrade_time_of_day=0,
-            upgrade_mode=TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE,
-            exclude_plugins=[],
-            include_plugins=[],
-        )
-        db.session.add(plugin_upgrade_strategy)
+        for category in TenantPluginAutoUpgradeStrategy.PluginCategory:
+            plugin_upgrade_strategy = TenantPluginAutoUpgradeStrategy(
+                tenant_id=tenant.id,
+                category=category,
+                strategy_setting=PluginAutoUpgradeService.default_strategy_setting_for_category(category),
+                upgrade_time_of_day=PluginAutoUpgradeService.default_upgrade_time_of_day(tenant.id),
+                upgrade_mode=TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE,
+                exclude_plugins=[],
+                include_plugins=[],
+            )
+            db.session.add(plugin_upgrade_strategy)
         db.session.commit()
 
         tenant.encrypt_public_key = generate_key_pair(tenant.id)
@@ -1447,6 +1451,7 @@ class TenantService:
                 .values(current=False)
             )
             tenant_account_join.current = True
+            tenant_account_join.last_opened_at = naive_utc_now()
             # Set the current tenant for the account
             account.set_tenant_id(tenant_account_join.tenant_id)
             db.session.commit()

api/services/agent/composer_service.py

@@ -12,6 +12,7 @@ from models.agent import (
     AgentConfigRevision,
     AgentConfigRevisionOperation,
     AgentConfigSnapshot,
+    AgentDriveFile,
     AgentKind,
     AgentScope,
     AgentSource,
@@ -20,6 +21,7 @@ from models.agent import (
     WorkflowAgentNodeBinding,
 )
 from models.agent_config_entities import (
+    AgentFileRefConfig,
     DeclaredOutputConfig,
 )
 from models.agent_config_entities import (
@@ -28,7 +30,12 @@ from models.agent_config_entities import (
 from models.workflow import Workflow
 from services.agent.agent_soul_state import agent_soul_has_model
 from services.agent.composer_validator import ComposerConfigValidator
-from services.agent.errors import AgentNameConflictError, AgentNotFoundError, AgentVersionNotFoundError
+from services.agent.errors import (
+    AgentNameConflictError,
+    AgentNotFoundError,
+    AgentVersionNotFoundError,
+    InvalidComposerConfigError,
+)
 from services.entities.agent_entities import (
     AgentSoulConfig,
     ComposerCandidatesResponse,
@@ -99,6 +106,21 @@ class AgentComposerService:
         workflow = cls._get_draft_workflow(tenant_id=tenant_id, app_id=app_id)
         binding = cls._get_workflow_binding(tenant_id=tenant_id, workflow_id=workflow.id, node_id=node_id)
 
+        # ENG-623 §4.4: drive-backed refs must point at real drive rows before the
+        # soul is persisted. Only strategies that write the soul onto an *existing*
+        # agent are checked — new-agent strategies create a fresh (empty) drive, so
+        # any carried drive key would be flagged on the next save instead.
+        if (
+            payload.agent_soul is not None
+            and binding is not None
+            and binding.agent_id
+            and payload.save_strategy
+            in (ComposerSaveStrategy.SAVE_TO_CURRENT_VERSION, ComposerSaveStrategy.SAVE_AS_NEW_VERSION)
+        ):
+            cls._require_drive_refs_resolved(
+                tenant_id=tenant_id, agent_id=binding.agent_id, agent_soul=payload.agent_soul
+            )
+
         match payload.save_strategy:
             case ComposerSaveStrategy.NODE_JOB_ONLY:
                 binding = cls._save_node_job_only(
@@ -220,6 +242,9 @@ class AgentComposerService:
                 db.session.rollback()
                 raise AgentNameConflictError() from exc
 
+        # ENG-623 §4.4: dangling drive-backed refs are rejected before persisting.
+        cls._require_drive_refs_resolved(tenant_id=tenant_id, agent_id=agent.id, agent_soul=payload.agent_soul)
+
         if payload.save_strategy == ComposerSaveStrategy.SAVE_AS_NEW_VERSION or not agent.active_config_snapshot_id:
             version = cls._create_config_version(
                 tenant_id=tenant_id,
@@ -252,8 +277,18 @@ class AgentComposerService:
         return state
 
     @classmethod
-    def collect_validation_findings(cls, *, tenant_id: str, payload: ComposerSavePayload) -> dict[str, Any]:
-        """ENG-617 soft findings, with DB-backed dataset existence for placeholders."""
+    def collect_validation_findings(
+        cls,
+        *,
+        tenant_id: str,
+        payload: ComposerSavePayload,
+        agent_id: str | None = None,
+    ) -> dict[str, Any]:
+        """ENG-617 soft findings, with DB-backed dataset existence for placeholders.
+
+        With ``agent_id`` the drive-backed skill/file refs are also checked against
+        the agent drive (ENG-623 §4.4) and dangling ones surface as warnings.
+        """
         from services.agent.prompt_mentions import MentionKind, parse_prompt_mentions
 
         mentioned_ids: set[str] = set()
@@ -266,7 +301,242 @@ class AgentComposerService:
         existing_dataset_ids: set[str] | None = None
         if mentioned_ids:
             existing_dataset_ids = set(cls._dataset_rows(tenant_id=tenant_id, dataset_ids=sorted(mentioned_ids)))
-        return ComposerConfigValidator.collect_soft_findings(payload, existing_dataset_ids=existing_dataset_ids)
+        findings = ComposerConfigValidator.collect_soft_findings(payload, existing_dataset_ids=existing_dataset_ids)
+        if agent_id and payload.agent_soul is not None:
+            findings["warnings"].extend(
+                cls._drive_ref_findings(tenant_id=tenant_id, agent_id=agent_id, agent_soul=payload.agent_soul)
+            )
+        return findings
+
+    @classmethod
+    def remove_drive_refs(
+        cls,
+        *,
+        tenant_id: str,
+        agent_id: str,
+        account_id: str,
+        skill_slug: str | None = None,
+        file_key: str | None = None,
+        app_id: str | None = None,
+        node_id: str | None = None,
+    ) -> str | None:
+        """Drop the soul refs backed by a drive skill/file before the drive rows go.
+
+        Soul-first ordering (ENG-625 D5): a mid-failure leaves harmless orphan KV
+        rows that an idempotent DELETE retry cleans, instead of a soul ref that
+        keeps failing dangling-ref validation. Returns the new config version id,
+        or ``None`` when the soul held no matching ref (idempotent re-delete).
+        """
+        if (skill_slug is None) == (file_key is None):
+            raise ValueError("remove_drive_refs requires exactly one of skill_slug or file_key")
+        agent = db.session.scalar(select(Agent).where(Agent.tenant_id == tenant_id, Agent.id == agent_id).limit(1))
+        if agent is None or not agent.active_config_snapshot_id:
+            return None
+        current_snapshot = cls._require_version(
+            tenant_id=tenant_id, agent_id=agent.id, version_id=agent.active_config_snapshot_id
+        )
+        agent_soul = AgentSoulConfig.model_validate(current_snapshot.config_snapshot_dict)
+
+        removed_display: str | None = None
+        if skill_slug is not None:
+            kept_skills = []
+            for skill in agent_soul.skills_files.skills:
+                slug = (skill.skill_md_key or "").split("/", 1)[0] or (skill.path or "").strip("/")
+                if slug == skill_slug:
+                    removed_display = skill.name or skill.id or skill_slug
+                    continue
+                kept_skills.append(skill)
+            if removed_display is None:
+                return None
+            agent_soul.skills_files.skills = kept_skills
+            note = f"Removed skill '{removed_display}' from the drive."
+        else:
+            kept_files = []
+            for file in agent_soul.skills_files.files:
+                if file.drive_key == file_key:
+                    removed_display = file.name or file.drive_key
+                    continue
+                kept_files.append(file)
+            if removed_display is None:
+                return None
+            agent_soul.skills_files.files = kept_files
+            note = f"Removed file '{removed_display}' from the drive."
+
+        version = cls._update_current_version(
+            current_snapshot=current_snapshot,
+            account_id=account_id,
+            agent_soul=agent_soul,
+            operation=AgentConfigRevisionOperation.SAVE_CURRENT_VERSION,
+            version_note=note,
+        )
+        agent.active_config_snapshot_id = version.id
+        agent.updated_by = account_id
+        cls._sync_draft_binding_snapshot(
+            tenant_id=tenant_id,
+            app_id=app_id,
+            node_id=node_id,
+            agent_id=agent_id,
+            snapshot_id=version.id,
+            account_id=account_id,
+        )
+        db.session.commit()
+        return version.id
+
+    @classmethod
+    def add_drive_file_ref(
+        cls,
+        *,
+        tenant_id: str,
+        agent_id: str,
+        account_id: str,
+        file_ref: AgentFileRefConfig,
+        app_id: str | None = None,
+        node_id: str | None = None,
+    ) -> str | None:
+        """Add or replace one drive-backed file ref in the active Agent Soul.
+
+        ``POST /agent/files`` is an ADD FILE user action, not just a low-level
+        drive commit. The committed file must be present in ``skills_files.files``
+        because runtime ``dify.drive`` is built from the active Agent Soul.
+        """
+        if not file_ref.drive_key:
+            raise ValueError("file_ref.drive_key is required")
+        agent = db.session.scalar(select(Agent).where(Agent.tenant_id == tenant_id, Agent.id == agent_id).limit(1))
+        if agent is None or not agent.active_config_snapshot_id:
+            return None
+        current_snapshot = cls._require_version(
+            tenant_id=tenant_id, agent_id=agent.id, version_id=agent.active_config_snapshot_id
+        )
+        agent_soul = AgentSoulConfig.model_validate(current_snapshot.config_snapshot_dict)
+        kept_files = [item for item in agent_soul.skills_files.files if item.drive_key != file_ref.drive_key]
+        kept_files.append(file_ref)
+        agent_soul.skills_files.files = kept_files
+
+        display = file_ref.name or file_ref.drive_key
+        version = cls._update_current_version(
+            current_snapshot=current_snapshot,
+            account_id=account_id,
+            agent_soul=agent_soul,
+            operation=AgentConfigRevisionOperation.SAVE_CURRENT_VERSION,
+            version_note=f"Added file '{display}' to the drive.",
+        )
+        agent.active_config_snapshot_id = version.id
+        agent.active_config_has_model = agent_soul_has_model(agent_soul)
+        agent.updated_by = account_id
+        cls._sync_draft_binding_snapshot(
+            tenant_id=tenant_id,
+            app_id=app_id,
+            node_id=node_id,
+            agent_id=agent_id,
+            snapshot_id=version.id,
+            account_id=account_id,
+        )
+        db.session.commit()
+        return version.id
+
+    @classmethod
+    def resolve_bound_agent_id(cls, *, tenant_id: str, app_id: str) -> str | None:
+        """The Agent App's bound roster agent id, if any (validate-endpoint context)."""
+        return db.session.scalar(
+            select(Agent.id)
+            .where(
+                Agent.tenant_id == tenant_id,
+                Agent.app_id == app_id,
+                Agent.scope == AgentScope.ROSTER,
+                Agent.status == AgentStatus.ACTIVE,
+            )
+            .order_by(Agent.created_at.desc())
+            .limit(1)
+        )
+
+    @classmethod
+    def resolve_workflow_node_agent_id(cls, *, tenant_id: str, app_id: str, node_id: str) -> str | None:
+        """The draft workflow node binding's agent id, if any (validate-endpoint context)."""
+        try:
+            workflow = cls._get_draft_workflow(tenant_id=tenant_id, app_id=app_id)
+        except ValueError:
+            return None
+        binding = cls._get_workflow_binding(tenant_id=tenant_id, workflow_id=workflow.id, node_id=node_id)
+        return binding.agent_id if binding else None
+
+    @classmethod
+    def _sync_draft_binding_snapshot(
+        cls,
+        *,
+        tenant_id: str,
+        app_id: str | None,
+        node_id: str | None,
+        agent_id: str,
+        snapshot_id: str,
+        account_id: str,
+    ) -> None:
+        """Keep workflow node bindings on the new active snapshot after direct drive edits."""
+        if not app_id or not node_id:
+            return
+        try:
+            workflow = cls._get_draft_workflow(tenant_id=tenant_id, app_id=app_id)
+        except ValueError:
+            return
+        binding = cls._get_workflow_binding(tenant_id=tenant_id, workflow_id=workflow.id, node_id=node_id)
+        if binding is None or binding.agent_id != agent_id:
+            return
+        binding.current_snapshot_id = snapshot_id
+        binding.updated_by = account_id
+
+    @classmethod
+    def _drive_ref_findings(
+        cls,
+        *,
+        tenant_id: str,
+        agent_id: str,
+        agent_soul: AgentSoulConfig,
+    ) -> list[dict[str, str | None]]:
+        """Drive-backed refs whose keys have no row in the agent drive (ENG-623 §4.4).
+
+        Each finding message starts with its stable code token
+        (``skill_ref_dangling`` / ``file_ref_dangling``) in the ENG-616/617 style.
+        """
+        wanted_keys: dict[str, tuple[str, str]] = {}
+        for skill in agent_soul.skills_files.skills:
+            if skill.skill_md_key:
+                wanted_keys[skill.skill_md_key] = ("skill_ref_dangling", skill.name or skill.id or "unknown")
+        for file in agent_soul.skills_files.files:
+            if file.drive_key:
+                wanted_keys[file.drive_key] = ("file_ref_dangling", file.name or file.id or "unknown")
+        if not wanted_keys:
+            return []
+
+        existing_keys = set(
+            db.session.scalars(
+                select(AgentDriveFile.key).where(
+                    AgentDriveFile.tenant_id == tenant_id,
+                    AgentDriveFile.agent_id == agent_id,
+                    AgentDriveFile.key.in_(sorted(wanted_keys)),
+                )
+            )
+        )
+        findings: list[dict[str, str | None]] = []
+        for key, (code, display) in wanted_keys.items():
+            if key in existing_keys:
+                continue
+            kind = "skill" if code == "skill_ref_dangling" else "file"
+            findings.append(
+                {
+                    "code": code,
+                    "surface": "agent_soul",
+                    "kind": kind,
+                    "id": key,
+                    "message": f"{code}: {kind} '{display}' has no drive entry for key '{key}'.",
+                }
+            )
+        return findings
+
+    @classmethod
+    def _require_drive_refs_resolved(cls, *, tenant_id: str, agent_id: str, agent_soul: AgentSoulConfig) -> None:
+        """Hard save-time guard: dangling drive-backed refs are rejected (400)."""
+        findings = cls._drive_ref_findings(tenant_id=tenant_id, agent_id=agent_id, agent_soul=agent_soul)
+        if findings:
+            raise InvalidComposerConfigError("; ".join(str(finding["message"]) for finding in findings))
 
     @classmethod
     def get_workflow_candidates(cls, *, tenant_id: str, app_id: str, node_id: str, user_id: str) -> dict[str, Any]:

api/services/agent/roster_service.py

@@ -19,7 +19,7 @@ from models.agent import (
 )
 from models.agent_config_entities import AgentSoulConfig
 from models.enums import AppStatus
-from models.model import App
+from models.model import App, AppMode
 from models.workflow import Workflow
 from services.agent.agent_soul_state import agent_soul_has_model
 from services.agent.composer_validator import ComposerConfigValidator
@@ -37,7 +37,11 @@ class AgentReferencingWorkflow(TypedDict):
 
     app_id: str
     app_name: str
+    app_icon_type: str | None
+    app_icon: str | None
+    app_icon_background: str | None
     app_mode: str
+    app_updated_at: int | None
     workflow_id: str
     workflow_version: str
     node_ids: list[str]
@@ -213,7 +217,7 @@ class AgentRosterService:
         tenant_id: str,
         account_id: str,
         payload: RosterAgentCreatePayload,
-        source: AgentSource = AgentSource.AGENT_APP,
+        source: AgentSource = AgentSource.ROSTER,
     ) -> Agent:
         ComposerConfigValidator.validate_agent_soul(payload.agent_soul)
 
@@ -278,6 +282,7 @@ class AgentRosterService:
         app_id: str,
         name: str,
         description: str = "",
+        role: str = "",
         icon_type: Any = None,
         icon: str | None = None,
         icon_background: str | None = None,
@@ -294,7 +299,7 @@ class AgentRosterService:
             tenant_id=tenant_id,
             name=name,
             description=description,
-            role="",
+            role=role,
             icon_type=icon_type,
             icon=icon,
             icon_background=icon_background,
@@ -337,6 +342,21 @@ class AgentRosterService:
         self._session.flush()
         return agent
 
+    def load_app_backing_agents_by_app_id(self, *, tenant_id: str, app_ids: list[str]) -> dict[str, Agent]:
+        """Return active app-backed Agents keyed by Agent App id."""
+        if not app_ids:
+            return {}
+        agents = self._session.scalars(
+            select(Agent).where(
+                Agent.tenant_id == tenant_id,
+                Agent.app_id.in_(app_ids),
+                Agent.scope == AgentScope.ROSTER,
+                Agent.source == AgentSource.AGENT_APP,
+                Agent.status == AgentStatus.ACTIVE,
+            )
+        ).all()
+        return {agent.app_id: agent for agent in agents if agent.app_id}
+
     def get_app_backing_agent(self, *, tenant_id: str, app_id: str) -> Agent | None:
         """Return the roster Agent that backs the given Agent App, if any."""
         return self._session.scalar(
@@ -349,6 +369,43 @@ class AgentRosterService:
             )
         )
 
+    def get_agent_app_model(self, *, tenant_id: str, agent_id: str) -> App:
+        """Resolve the Agent App hidden behind an app-backed Agent id.
+
+        The public /agent route uses Agent ids, while the runtime and legacy app
+        APIs still operate on App ids internally. Only app-backed roster Agents
+        are accepted here; workflow-only Agents and historical standalone roster
+        Agents are not Agent App resources.
+        """
+        agent = self._session.scalar(
+            select(Agent)
+            .where(
+                Agent.tenant_id == tenant_id,
+                Agent.id == agent_id,
+                Agent.scope == AgentScope.ROSTER,
+                Agent.source == AgentSource.AGENT_APP,
+                Agent.app_id.is_not(None),
+                Agent.status == AgentStatus.ACTIVE,
+            )
+            .limit(1)
+        )
+        if agent is None or agent.app_id is None:
+            raise AgentNotFoundError()
+
+        app = self._session.scalar(
+            select(App)
+            .where(
+                App.tenant_id == tenant_id,
+                App.id == agent.app_id,
+                App.mode == AppMode.AGENT,
+                App.status == AppStatus.NORMAL,
+            )
+            .limit(1)
+        )
+        if app is None:
+            raise AgentNotFoundError()
+        return app
+
     def list_workflows_referencing_app_agent(self, *, tenant_id: str, app_id: str) -> list[AgentReferencingWorkflow]:
         """List the workflow apps that reference this Agent App's bound Agent.
 
@@ -403,12 +460,36 @@ class AgentRosterService:
         agent.updated_by = account_id
         self._session.commit()
 
+    @staticmethod
+    def _visible_version_operations(agent: Agent) -> set[AgentConfigRevisionOperation]:
+        if agent.source == AgentSource.AGENT_APP:
+            return {AgentConfigRevisionOperation.SAVE_NEW_VERSION}
+        return {
+            AgentConfigRevisionOperation.CREATE_VERSION,
+            AgentConfigRevisionOperation.SAVE_NEW_VERSION,
+            AgentConfigRevisionOperation.SAVE_NEW_AGENT,
+            AgentConfigRevisionOperation.SAVE_TO_ROSTER,
+        }
+
     def list_agent_versions(self, *, tenant_id: str, agent_id: str) -> list[dict[str, Any]]:
-        self._get_agent(tenant_id=tenant_id, agent_id=agent_id, roster_only=True)
+        agent = self._get_agent(tenant_id=tenant_id, agent_id=agent_id, roster_only=True)
+        visible_version_ids = (
+            select(AgentConfigRevision.current_snapshot_id)
+            .where(
+                AgentConfigRevision.tenant_id == tenant_id,
+                AgentConfigRevision.agent_id == agent_id,
+                AgentConfigRevision.operation.in_(self._visible_version_operations(agent)),
+            )
+            .subquery()
+        )
         versions = list(
             self._session.scalars(
                 select(AgentConfigSnapshot)
-                .where(AgentConfigSnapshot.tenant_id == tenant_id, AgentConfigSnapshot.agent_id == agent_id)
+                .where(
+                    AgentConfigSnapshot.tenant_id == tenant_id,
+                    AgentConfigSnapshot.agent_id == agent_id,
+                    AgentConfigSnapshot.id.in_(select(visible_version_ids.c.current_snapshot_id)),
+                )
                 .order_by(AgentConfigSnapshot.version.desc())
             ).all()
         )
@@ -419,7 +500,19 @@ class AgentRosterService:
         ]
 
     def get_agent_version_detail(self, *, tenant_id: str, agent_id: str, version_id: str) -> dict[str, Any]:
-        self._get_agent(tenant_id=tenant_id, agent_id=agent_id, roster_only=True)
+        agent = self._get_agent(tenant_id=tenant_id, agent_id=agent_id, roster_only=True)
+        visible_revision_id = self._session.scalar(
+            select(AgentConfigRevision.id)
+            .where(
+                AgentConfigRevision.tenant_id == tenant_id,
+                AgentConfigRevision.agent_id == agent_id,
+                AgentConfigRevision.current_snapshot_id == version_id,
+                AgentConfigRevision.operation.in_(self._visible_version_operations(agent)),
+            )
+            .limit(1)
+        )
+        if not visible_revision_id:
+            raise AgentVersionNotFoundError()
         version = self._get_version(tenant_id=tenant_id, agent_id=agent_id, version_id=version_id)
         revisions = list(
             self._session.scalars(
@@ -520,7 +613,11 @@ class AgentRosterService:
                 AgentReferencingWorkflow(
                     app_id=binding.app_id,
                     app_name=app.name,
+                    app_icon_type=(icon_type.value if (icon_type := getattr(app, "icon_type", None)) else None),
+                    app_icon=getattr(app, "icon", None),
+                    app_icon_background=getattr(app, "icon_background", None),
                     app_mode=str(app.mode),
+                    app_updated_at=to_timestamp(getattr(app, "updated_at", None)),
                     workflow_id=binding.workflow_id,
                     workflow_version=binding.workflow_version,
                     node_ids=[],
@@ -533,7 +630,7 @@ class AgentRosterService:
             references = list(by_workflow.values())
             for reference in references:
                 reference["node_ids"] = sorted(set(reference["node_ids"]))
-            references.sort(key=lambda item: (item["app_name"].lower(), item["workflow_id"]))
+            references.sort(key=lambda item: (-(item["app_updated_at"] or 0), item["app_name"].lower()))
             result[agent_id] = references
         return result
 

api/services/agent/skill_package_service.py

@@ -70,6 +70,7 @@ class SkillManifest(BaseModel):
                 "size": self.size,
                 "hash": self.hash,
                 "entry_path": self.entry_path,
+                "manifest_files": self.files,
             }
         )
 

api/services/agent/skill_standardize_service.py

@@ -112,6 +112,8 @@ class SkillStandardizeService:
                 "skill_md_key": skill_md_key,
                 "full_archive_file_id": archive_tool_file.id,
                 "full_archive_key": archive_key,
+                # ENG-371: zip member listing — strong signals (scripts/*.sh) for infer-tools.
+                "manifest_files": manifest.files,
             }
         )
         return {

api/services/agent/skill_tool_inference_service.py

@@ -0,0 +1,215 @@
+"""Infer CLI tool + ENV suggestions from a standardized skill (ENG-371).
+
+Reads the skill's SKILL.md from the agent drive, asks the tenant's default
+reasoning model once (a plain LLM call, never an agent run), and returns
+*draft* suggestions only — nothing is persisted here. The frontend prefills
+the TOOLS box (``inferred from <skill>`` badge) and the Pre-Authorize ENV
+panel, and saving still goes through the composer's full shell/env/secret/
+dangerous-command validation, so inference opens no bypass.
+
+ENV suggestions carry only ``key`` + ``reason`` — the model never produces a
+value; users fill those in themselves and the runtime injects ``$VAR`` only.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import json_repair
+from pydantic import BaseModel, Field, ValidationError
+from sqlalchemy import select
+
+from core.errors.error import ProviderTokenNotInitError
+from core.model_manager import ModelManager
+from extensions.ext_database import db
+from graphon.model_runtime.entities.message_entities import SystemPromptMessage, UserPromptMessage
+from graphon.model_runtime.entities.model_entities import ModelType
+from models.agent import Agent
+from models.agent_config_entities import AgentSoulConfig
+from services.agent_drive_service import AgentDriveError, AgentDriveService
+
+logger = logging.getLogger(__name__)
+
+
+class SkillToolInferenceError(Exception):
+    """Stable-code error for the infer-tools endpoint."""
+
+    def __init__(self, code: str, message: str, *, status_code: int = 400) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class EnvSuggestion(BaseModel):
+    key: str
+    reason: str = ""
+    secret_likely: bool = False
+
+
+class CliToolSuggestion(BaseModel):
+    name: str
+    description: str = ""
+    command: str = ""
+    install_commands: list[str] = Field(default_factory=list)
+    env_suggestions: list[EnvSuggestion] = Field(default_factory=list)
+    inferred_from: str = ""
+
+
+class SkillToolInferenceResult(BaseModel):
+    inferable: bool
+    cli_tools: list[CliToolSuggestion] = Field(default_factory=list)
+    reason: str | None = None
+
+
+_SYSTEM_PROMPT = """\
+You analyze an agent skill document (SKILL.md) and infer which command-line \
+tools the skill depends on at runtime, so a user can pre-install them in the \
+agent's sandbox.
+
+Rules:
+- Only suggest tools the document explicitly uses or clearly requires; never guess.
+- For each tool give: name, a one-line reason-style description referencing the \
+document, the base command, and install commands for a Debian-based sandbox \
+(apt-get / pip / npm).
+- If a step needs an environment variable (an API key, token, endpoint), add it \
+to env_suggestions with the variable key and the reason. NEVER produce a value. \
+Mark secret_likely=true for credentials.
+- If the document describes no external command-line dependency, return \
+{"inferable": false, "cli_tools": [], "reason": "<one short sentence why>"}.
+
+Respond with JSON only, matching exactly:
+{"inferable": bool,
+ "cli_tools": [{"name": str, "description": str, "command": str,
+                "install_commands": [str], "env_suggestions":
+                [{"key": str, "reason": str, "secret_likely": bool}]}],
+ "reason": str | null}
+"""
+
+
+class SkillToolInferenceService:
+    """Single-shot LLM inference over a drive-stored SKILL.md."""
+
+    def __init__(self, *, drive_service: AgentDriveService | None = None) -> None:
+        self._drive = drive_service or AgentDriveService()
+
+    def infer(self, *, tenant_id: str, agent_id: str, slug: str) -> dict[str, Any]:
+        skill_md = self._load_skill_md(tenant_id=tenant_id, agent_id=agent_id, slug=slug)
+        manifest_files = self._manifest_files_from_soul(tenant_id=tenant_id, agent_id=agent_id, slug=slug)
+
+        user_prompt = f"SKILL.md of skill '{slug}':\n\n{skill_md}"
+        if manifest_files:
+            listing = "\n".join(manifest_files[:200])
+            user_prompt += f"\n\nFiles inside the skill package:\n{listing}"
+
+        raw = self._invoke(tenant_id=tenant_id, user_prompt=user_prompt)
+        try:
+            result = self._parse(raw)
+        except (ValidationError, ValueError):
+            logger.warning("skill tool inference output unparsable, retrying once")
+            raw = self._invoke(tenant_id=tenant_id, user_prompt=user_prompt)
+            try:
+                result = self._parse(raw)
+            except (ValidationError, ValueError) as exc:
+                raise SkillToolInferenceError(
+                    "inference_failed",
+                    "inference_failed: the model output could not be parsed into tool suggestions.",
+                    status_code=422,
+                ) from exc
+
+        for tool in result.cli_tools:
+            tool.inferred_from = slug
+        return result.model_dump(mode="json")
+
+    def _load_skill_md(self, *, tenant_id: str, agent_id: str, slug: str) -> str:
+        try:
+            preview = self._drive.preview(tenant_id=tenant_id, agent_id=agent_id, key=f"{slug}/SKILL.md")
+        except AgentDriveError as exc:
+            if exc.code == "drive_key_not_found":
+                raise SkillToolInferenceError(
+                    "skill_not_found", f"skill_not_found: no drive entry for skill '{slug}'.", status_code=404
+                ) from exc
+            raise SkillToolInferenceError(exc.code, exc.message, status_code=exc.status_code) from exc
+        if preview["binary"] or not preview["text"]:
+            raise SkillToolInferenceError(
+                "skill_not_found", f"skill_not_found: SKILL.md of '{slug}' is not readable text.", status_code=404
+            )
+        return str(preview["text"])
+
+    @staticmethod
+    def _manifest_files_from_soul(*, tenant_id: str, agent_id: str, slug: str) -> list[str]:
+        """The zip path listing standardize persisted onto the ref, if present.
+
+        Degrades to an empty list (SKILL.md-only inference) for refs that
+        predate ``manifest_files``.
+        """
+        agent = db.session.scalar(select(Agent).where(Agent.tenant_id == tenant_id, Agent.id == agent_id).limit(1))
+        if agent is None or not agent.active_config_snapshot_id:
+            return []
+        from models.agent import AgentConfigSnapshot
+
+        snapshot = db.session.scalar(
+            select(AgentConfigSnapshot).where(
+                AgentConfigSnapshot.tenant_id == tenant_id,
+                AgentConfigSnapshot.agent_id == agent_id,
+                AgentConfigSnapshot.id == agent.active_config_snapshot_id,
+            )
+        )
+        if snapshot is None:
+            return []
+        soul = AgentSoulConfig.model_validate(snapshot.config_snapshot_dict)
+        for skill in soul.skills_files.skills:
+            ref_slug = (skill.skill_md_key or "").split("/", 1)[0] or (skill.path or "").strip("/")
+            if ref_slug != slug:
+                continue
+            files = skill.get("manifest_files")
+            if isinstance(files, list):
+                return [str(item) for item in files]
+        return []
+
+    @staticmethod
+    def _invoke(*, tenant_id: str, user_prompt: str) -> str:
+        try:
+            model_manager = ModelManager.for_tenant(tenant_id=tenant_id)
+            model_instance = model_manager.get_default_model_instance(tenant_id=tenant_id, model_type=ModelType.LLM)
+        except ProviderTokenNotInitError as exc:
+            raise SkillToolInferenceError(
+                "default_model_not_configured",
+                "default_model_not_configured: the workspace has no default reasoning model.",
+                status_code=400,
+            ) from exc
+        try:
+            response = model_instance.invoke_llm(
+                prompt_messages=[
+                    SystemPromptMessage(content=_SYSTEM_PROMPT),
+                    UserPromptMessage(content=user_prompt),
+                ],
+                model_parameters={"temperature": 0.1},
+                stream=False,
+            )
+        except Exception as exc:
+            raise SkillToolInferenceError(
+                "inference_failed", f"inference_failed: model invocation failed: {exc}", status_code=422
+            ) from exc
+        return response.message.get_text_content()
+
+    @staticmethod
+    def _parse(raw: str) -> SkillToolInferenceResult:
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            parsed = json_repair.loads(raw)
+        if not isinstance(parsed, dict):
+            raise ValueError("model output is not a JSON object")
+        return SkillToolInferenceResult.model_validate(parsed)
+
+
+__all__ = [
+    "CliToolSuggestion",
+    "EnvSuggestion",
+    "SkillToolInferenceError",
+    "SkillToolInferenceResult",
+    "SkillToolInferenceService",
+]

api/services/agent/workflow_publish_service.py

@@ -1,14 +1,23 @@
 from __future__ import annotations
 
+import copy
 from collections.abc import Mapping
-from typing import Any
+from typing import Any, cast
 
+from pydantic import ValidationError
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from core.workflow.nodes.agent_v2.validators import WorkflowAgentNodeValidator
-from models.agent import Agent, AgentScope, AgentStatus, WorkflowAgentBindingType, WorkflowAgentNodeBinding
-from models.agent_config_entities import WorkflowNodeJobConfig
+from models.agent import (
+    Agent,
+    AgentConfigSnapshot,
+    AgentScope,
+    AgentStatus,
+    WorkflowAgentBindingType,
+    WorkflowAgentNodeBinding,
+)
+from models.agent_config_entities import DeclaredOutputConfig, WorkflowNodeJobConfig
 from models.workflow import Workflow
 
 
@@ -17,6 +26,43 @@ class WorkflowAgentPublishService:
 
     _DRAFT_WORKFLOW_VERSION = Workflow.VERSION_DRAFT
     _AGENT_BINDING_KEY = "agent_binding"
+    _AGENT_TASK_KEY = "agent_task"
+    _AGENT_DECLARED_OUTPUTS_KEY = "agent_declared_outputs"
+
+    @classmethod
+    def project_draft_bindings_to_graph(cls, *, session: Session, draft_workflow: Workflow) -> dict[str, Any]:
+        """Return draft graph with persisted Agent node job config projected into node data.
+
+        Workflow draft graph is the front-end's editing source of truth, while
+        runtime/publish reads WorkflowAgentNodeBinding.node_job_config. This
+        response-only projection keeps reads aligned without writing binding
+        details back into the stored graph JSON.
+        """
+        graph = cast(dict[str, Any], copy.deepcopy(draft_workflow.graph_dict))
+        agent_nodes = dict(WorkflowAgentNodeValidator.iter_agent_v2_nodes(graph))
+        if not agent_nodes:
+            return graph
+
+        bindings = session.scalars(
+            select(WorkflowAgentNodeBinding).where(
+                WorkflowAgentNodeBinding.tenant_id == draft_workflow.tenant_id,
+                WorkflowAgentNodeBinding.app_id == draft_workflow.app_id,
+                WorkflowAgentNodeBinding.workflow_id == draft_workflow.id,
+                WorkflowAgentNodeBinding.workflow_version == cls._DRAFT_WORKFLOW_VERSION,
+                WorkflowAgentNodeBinding.node_id.in_(list(agent_nodes.keys())),
+            )
+        ).all()
+        for binding in bindings:
+            node_data = agent_nodes.get(binding.node_id)
+            if not isinstance(node_data, dict):
+                continue
+            node_job = WorkflowNodeJobConfig.model_validate(binding.node_job_config_dict)
+            if node_job.workflow_prompt is not None:
+                node_data[cls._AGENT_TASK_KEY] = node_job.workflow_prompt
+            node_data[cls._AGENT_DECLARED_OUTPUTS_KEY] = [
+                output.model_dump(mode="json") for output in node_job.declared_outputs
+            ]
+        return graph
 
     @classmethod
     def validate_agent_nodes_for_publish(cls, *, session: Session, draft_workflow: Workflow) -> None:
@@ -27,7 +73,7 @@ class WorkflowAgentPublishService:
         WorkflowAgentNodeValidator.validate_draft_workflow(session=session, workflow=draft_workflow)
 
     @classmethod
-    def sync_roster_agent_bindings_for_draft(
+    def sync_agent_bindings_for_draft(
         cls,
         *,
         session: Session,
@@ -57,10 +103,11 @@ class WorkflowAgentPublishService:
                 continue
             if not isinstance(binding_payload, Mapping):
                 raise ValueError(f"Workflow Agent node {node_id} has invalid agent_binding.")
-            cls._sync_roster_agent_binding_for_node(
+            cls._sync_agent_binding_for_node(
                 session=session,
                 draft_workflow=draft_workflow,
                 node_id=node_id,
+                node_data=node_data,
                 node_binding=binding_payload,
                 existing_binding=existing_by_node_id.get(node_id),
                 account_id=account_id,
@@ -68,23 +115,93 @@ class WorkflowAgentPublishService:
         session.flush()
 
     @classmethod
-    def _sync_roster_agent_binding_for_node(
+    def sync_roster_agent_bindings_for_draft(
+        cls,
+        *,
+        session: Session,
+        draft_workflow: Workflow,
+        account_id: str,
+    ) -> None:
+        cls.sync_agent_bindings_for_draft(
+            session=session,
+            draft_workflow=draft_workflow,
+            account_id=account_id,
+        )
+
+    @classmethod
+    def _sync_agent_binding_for_node(
         cls,
         *,
         session: Session,
         draft_workflow: Workflow,
         node_id: str,
+        node_data: Mapping[str, Any],
         node_binding: Mapping[str, Any],
         existing_binding: WorkflowAgentNodeBinding | None,
         account_id: str,
     ) -> None:
         binding_type = node_binding.get("binding_type")
-        if binding_type != WorkflowAgentBindingType.ROSTER_AGENT.value:
-            raise ValueError(f"Workflow Agent node {node_id} only supports roster_agent graph binding.")
         agent_id = node_binding.get("agent_id")
         if not isinstance(agent_id, str) or not agent_id:
-            raise ValueError(f"Workflow Agent node {node_id} roster_agent binding requires agent_id.")
+            raise ValueError(f"Workflow Agent node {node_id} agent binding requires agent_id.")
 
+        if binding_type == WorkflowAgentBindingType.ROSTER_AGENT.value:
+            agent, current_snapshot_id = cls._resolve_roster_agent_graph_binding(
+                session=session,
+                draft_workflow=draft_workflow,
+                node_id=node_id,
+                agent_id=agent_id,
+            )
+            resolved_binding_type = WorkflowAgentBindingType.ROSTER_AGENT
+        elif binding_type == WorkflowAgentBindingType.INLINE_AGENT.value:
+            raw_current_snapshot_id = node_binding.get("current_snapshot_id")
+            if not isinstance(raw_current_snapshot_id, str) or not raw_current_snapshot_id:
+                raise ValueError(f"Workflow Agent node {node_id} inline_agent binding requires current_snapshot_id.")
+            current_snapshot_id = raw_current_snapshot_id
+            agent = cls._resolve_inline_agent_graph_binding(
+                session=session,
+                draft_workflow=draft_workflow,
+                node_id=node_id,
+                agent_id=agent_id,
+                current_snapshot_id=current_snapshot_id,
+            )
+            resolved_binding_type = WorkflowAgentBindingType.INLINE_AGENT
+        else:
+            raise ValueError(f"Workflow Agent node {node_id} has unsupported agent_binding type.")
+
+        binding = existing_binding
+        node_job_config = cls._node_job_config_from_node_data(
+            existing_binding=existing_binding,
+            node_data=node_data,
+        )
+        if binding is None:
+            binding = WorkflowAgentNodeBinding(
+                tenant_id=draft_workflow.tenant_id,
+                app_id=draft_workflow.app_id,
+                workflow_id=draft_workflow.id,
+                workflow_version=cls._DRAFT_WORKFLOW_VERSION,
+                node_id=node_id,
+                node_job_config=node_job_config,
+                created_by=account_id,
+            )
+            session.add(binding)
+        else:
+            binding.node_job_config = node_job_config
+
+        binding.binding_type = resolved_binding_type
+        binding.agent_id = agent.id
+        binding.current_snapshot_id = current_snapshot_id
+        binding.updated_by = account_id
+
+    @classmethod
+    def _resolve_roster_agent_graph_binding(
+        cls,
+        *,
+        session: Session,
+        draft_workflow: Workflow,
+        node_id: str,
+        agent_id: str,
+    ) -> tuple[Agent, str]:
         agent = session.scalar(
             select(Agent)
             .where(
@@ -97,28 +214,86 @@ class WorkflowAgentPublishService:
         )
         if agent is None:
             raise ValueError(f"Workflow Agent node {node_id} references an unavailable roster agent.")
+        if agent.scope != AgentScope.ROSTER:
+            raise ValueError(f"Workflow Agent node {node_id} roster_agent binding must reference a roster agent.")
         if not agent.active_config_snapshot_id:
             raise ValueError(f"Workflow Agent node {node_id} roster agent has no active config snapshot.")
+        return agent, agent.active_config_snapshot_id
 
-        binding = existing_binding
-        if binding is None:
-            binding = WorkflowAgentNodeBinding(
-                tenant_id=draft_workflow.tenant_id,
-                app_id=draft_workflow.app_id,
-                workflow_id=draft_workflow.id,
-                workflow_version=cls._DRAFT_WORKFLOW_VERSION,
-                node_id=node_id,
-                node_job_config=WorkflowNodeJobConfig(),
-                created_by=account_id,
+    @classmethod
+    def _resolve_inline_agent_graph_binding(
+        cls,
+        *,
+        session: Session,
+        draft_workflow: Workflow,
+        node_id: str,
+        agent_id: str,
+        current_snapshot_id: str,
+    ) -> Agent:
+        agent = session.scalar(
+            select(Agent)
+            .where(
+                Agent.tenant_id == draft_workflow.tenant_id,
+                Agent.id == agent_id,
+                Agent.scope == AgentScope.WORKFLOW_ONLY,
+                Agent.app_id == draft_workflow.app_id,
+                Agent.workflow_id == draft_workflow.id,
+                Agent.workflow_node_id == node_id,
+                Agent.status == AgentStatus.ACTIVE,
             )
-            session.add(binding)
-        elif not binding.node_job_config:
-            binding.node_job_config = WorkflowNodeJobConfig()
+            .limit(1)
+        )
+        if agent is None:
+            raise ValueError(f"Workflow Agent node {node_id} references an unavailable inline agent.")
+        if (
+            agent.scope != AgentScope.WORKFLOW_ONLY
+            or agent.app_id != draft_workflow.app_id
+            or agent.workflow_id != draft_workflow.id
+            or agent.workflow_node_id != node_id
+        ):
+            raise ValueError(f"Workflow Agent node {node_id} inline_agent binding does not belong to this node.")
 
-        binding.binding_type = WorkflowAgentBindingType.ROSTER_AGENT
-        binding.agent_id = agent.id
-        binding.current_snapshot_id = agent.active_config_snapshot_id
-        binding.updated_by = account_id
+        snapshot = session.scalar(
+            select(AgentConfigSnapshot)
+            .where(
+                AgentConfigSnapshot.tenant_id == draft_workflow.tenant_id,
+                AgentConfigSnapshot.agent_id == agent.id,
+                AgentConfigSnapshot.id == current_snapshot_id,
+            )
+            .limit(1)
+        )
+        if snapshot is None or snapshot.agent_id != agent.id:
+            raise ValueError(f"Workflow Agent node {node_id} references a missing inline agent config snapshot.")
+        return agent
+
+    @classmethod
+    def _node_job_config_from_node_data(
+        cls,
+        *,
+        existing_binding: WorkflowAgentNodeBinding | None,
+        node_data: Mapping[str, Any],
+    ) -> WorkflowNodeJobConfig:
+        if existing_binding and existing_binding.node_job_config:
+            node_job = WorkflowNodeJobConfig.model_validate(existing_binding.node_job_config_dict)
+        else:
+            node_job = WorkflowNodeJobConfig()
+
+        agent_task = node_data.get(cls._AGENT_TASK_KEY)
+        if isinstance(agent_task, str):
+            node_job.workflow_prompt = agent_task
+
+        declared_outputs_payload = node_data.get(cls._AGENT_DECLARED_OUTPUTS_KEY)
+        if declared_outputs_payload is not None:
+            if not isinstance(declared_outputs_payload, list):
+                raise ValueError("Workflow Agent node agent_declared_outputs must be a list.")
+            try:
+                node_job.declared_outputs = [
+                    DeclaredOutputConfig.model_validate(output) for output in declared_outputs_payload
+                ]
+            except ValidationError as exc:
+                raise ValueError("Workflow Agent node has invalid agent_declared_outputs.") from exc
+
+        return node_job
 
     @classmethod
     def copy_agent_node_bindings_to_published(

api/services/agent_drive_service.py

@@ -131,6 +131,7 @@ class AgentDriveService:
                     "mime_type": row.mime_type,
                     "file_kind": row.file_kind.value,
                     "file_id": row.file_id,
+                    "created_at": int(row.created_at.timestamp()) if row.created_at else None,
                 }
                 if include_download_url:
                     item["download_url"] = self._resolve_download_url(
@@ -169,6 +170,52 @@ class AgentDriveService:
             self._delete_storage(storage_key)
         return committed
 
+    def delete(
+        self,
+        *,
+        tenant_id: str,
+        agent_id: str,
+        prefix: str | None = None,
+        key: str | None = None,
+    ) -> list[str]:
+        """Delete drive entries by exact ``key`` or by ``prefix`` (ENG-625 D5).
+
+        Drive-owned values get their backing record + storage object cleaned via
+        the same ``_cleanup_value`` path commit-overwrite uses; shared values only
+        lose the KV row. Idempotent: deleting nothing returns ``[]``.
+        """
+        if (prefix is None) == (key is None):
+            raise AgentDriveError("invalid_delete_scope", "delete requires exactly one of prefix or key")
+        removed_keys: list[str] = []
+        pending_storage_deletes: list[str] = []
+        with session_factory.create_session() as session:
+            self._assert_agent_belongs_to_tenant(session, tenant_id=tenant_id, agent_id=agent_id)
+            stmt = select(AgentDriveFile).where(
+                AgentDriveFile.tenant_id == tenant_id,
+                AgentDriveFile.agent_id == agent_id,
+            )
+            if key is not None:
+                stmt = stmt.where(AgentDriveFile.key == normalize_drive_key(key))
+            else:
+                stmt = stmt.where(AgentDriveFile.key.startswith(normalize_drive_key(prefix or "")))
+            rows = list(session.scalars(stmt))
+            for row in rows:
+                if row.value_owned_by_drive:
+                    self._cleanup_value(
+                        session,
+                        tenant_id=tenant_id,
+                        file_kind=row.file_kind,
+                        file_id=row.file_id,
+                        exclude_row_id=row.id,
+                        pending_storage_deletes=pending_storage_deletes,
+                    )
+                removed_keys.append(row.key)
+                session.delete(row)
+            session.commit()
+        for storage_key in pending_storage_deletes:
+            self._delete_storage(storage_key)
+        return removed_keys
+
     def _commit_one(
         self,
         session: Session,
@@ -338,7 +385,12 @@ class AgentDriveService:
             logger.warning("failed to delete drive storage object %s", storage_key, exc_info=True)
 
     @staticmethod
-    def _resolve_download_url(*, tenant_id: str, file_kind: AgentDriveFileKind, file_id: str) -> str | None:
+    def _resolve_download_url(
+        *, tenant_id: str, file_kind: AgentDriveFileKind, file_id: str, for_external: bool = False
+    ) -> str | None:
+        """Signed URL for a drive value. ``for_external`` selects the audience:
+        the inner manifest hands agents *internal* URLs, while the console
+        inspector must hand browsers *external* ones — never mix the two."""
         if file_kind == AgentDriveFileKind.TOOL_FILE:
             mapping: dict[str, Any] = {"transfer_method": "tool_file", "tool_file_id": file_id}
         else:
@@ -349,10 +401,86 @@ class AgentDriveService:
             # No FileAccessScope bound -> drive-owned: the builders still filter by
             # tenant_id, so resolution is tenant-scoped without user-level checks.
             file = file_factory.build_from_mapping(mapping=mapping, tenant_id=tenant_id, access_controller=controller)
-            return runtime.resolve_file_url(file=file, for_external=False)
+            return runtime.resolve_file_url(file=file, for_external=for_external)
         except ValueError:
             return None
 
+    # ── console drive inspector (ENG-624) ────────────────────────────────────
+
+    # SKILL.md is the primary preview use case; 64 KiB covers it with headroom
+    # while keeping the console payload bounded.
+    PREVIEW_MAX_BYTES = 64 * 1024
+
+    def _require_row(self, session: Session, *, tenant_id: str, agent_id: str, key: str) -> AgentDriveFile:
+        row = session.scalar(
+            select(AgentDriveFile).where(
+                AgentDriveFile.tenant_id == tenant_id,
+                AgentDriveFile.agent_id == agent_id,
+                AgentDriveFile.key == normalize_drive_key(key),
+            )
+        )
+        if row is None:
+            raise AgentDriveError("drive_key_not_found", "no drive entry for this key", status_code=404)
+        return row
+
+    def _storage_key_for_row(self, session: Session, *, tenant_id: str, row: AgentDriveFile) -> str:
+        if row.file_kind == AgentDriveFileKind.TOOL_FILE:
+            tool_file = session.scalar(
+                select(ToolFile).where(ToolFile.id == row.file_id, ToolFile.tenant_id == tenant_id)
+            )
+            if tool_file is None:
+                raise AgentDriveError("drive_key_not_found", "drive value record is missing", status_code=404)
+            return tool_file.file_key
+        upload_file = session.scalar(
+            select(UploadFile).where(UploadFile.id == row.file_id, UploadFile.tenant_id == tenant_id)
+        )
+        if upload_file is None:
+            raise AgentDriveError("drive_key_not_found", "drive value record is missing", status_code=404)
+        return upload_file.key
+
+    def preview(self, *, tenant_id: str, agent_id: str, key: str) -> dict[str, Any]:
+        """Truncated text preview of one drive value (binary-safe, never 500s on size)."""
+        with session_factory.create_session() as session:
+            self._assert_agent_belongs_to_tenant(session, tenant_id=tenant_id, agent_id=agent_id)
+            row = self._require_row(session, tenant_id=tenant_id, agent_id=agent_id, key=key)
+            storage_key = self._storage_key_for_row(session, tenant_id=tenant_id, row=row)
+            size = row.size
+
+        data = bytearray()
+        for chunk in storage.load_stream(storage_key):
+            data.extend(chunk)
+            if len(data) > self.PREVIEW_MAX_BYTES:
+                break
+        truncated = len(data) > self.PREVIEW_MAX_BYTES
+        sample = bytes(data[: self.PREVIEW_MAX_BYTES])
+        # Same semantics as the sandbox read endpoint: NUL or undecodable -> binary.
+        if b"\x00" in sample:
+            return {"key": row.key, "size": size, "truncated": truncated, "binary": True, "text": None}
+        try:
+            text = sample.decode("utf-8")
+        except UnicodeDecodeError:
+            if truncated:
+                # A multi-byte char may sit on the cut point; retry without the tail.
+                try:
+                    text = sample[:-3].decode("utf-8", errors="strict")
+                except UnicodeDecodeError:
+                    return {"key": row.key, "size": size, "truncated": truncated, "binary": True, "text": None}
+            else:
+                return {"key": row.key, "size": size, "truncated": truncated, "binary": True, "text": None}
+        return {"key": row.key, "size": size, "truncated": truncated, "binary": False, "text": text}
+
+    def download_url(self, *, tenant_id: str, agent_id: str, key: str) -> str:
+        """External signed URL for a browser download of one drive value."""
+        with session_factory.create_session() as session:
+            self._assert_agent_belongs_to_tenant(session, tenant_id=tenant_id, agent_id=agent_id)
+            row = self._require_row(session, tenant_id=tenant_id, agent_id=agent_id, key=key)
+            url = self._resolve_download_url(
+                tenant_id=tenant_id, file_kind=row.file_kind, file_id=row.file_id, for_external=True
+            )
+        if url is None:
+            raise AgentDriveError("drive_key_not_found", "drive value cannot be resolved", status_code=404)
+        return url
+
 
 __all__ = [
     "AgentDriveError",

api/services/app_service.py

@@ -1,7 +1,8 @@
 import json
 import logging
 from collections.abc import Sequence
-from typing import Any, Literal, TypedDict, cast, override
+from datetime import datetime
+from typing import Any, Literal, NotRequired, TypedDict, cast, override
 
 import sqlalchemy as sa
 from flask_sqlalchemy.pagination import Pagination
@@ -22,8 +23,8 @@ from graphon.model_runtime.entities.model_entities import ModelPropertyKey, Mode
 from graphon.model_runtime.model_providers.base.large_language_model import LargeLanguageModel
 from libs.datetime_utils import naive_utc_now
 from libs.login import current_user
-from models import Account
-from models.agent import AgentIconType
+from models import Account, AppStar
+from models.agent import Agent, AgentIconType, AgentScope, AgentSource, AgentStatus
 from models.model import App, AppMode, AppModelConfig, IconType, Site
 from models.tools import ApiToolProvider
 from services.billing_service import BillingService
@@ -35,23 +36,34 @@ from tasks.remove_app_and_related_data_task import remove_app_and_related_data_t
 
 logger = logging.getLogger(__name__)
 
+AppListSortBy = Literal["last_modified", "recently_created", "earliest_created"]
 
-class AppListParams(BaseModel):
+
+class AppListBaseParams(BaseModel):
     page: int = Field(default=1, ge=1)
     limit: int = Field(default=20, ge=1, le=100)
     mode: Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"] = "all"
+    sort_by: AppListSortBy = "last_modified"
     name: str | None = None
     tag_ids: list[str] | None = None
     creator_ids: list[str] | None = None
     is_created_by_me: bool | None = None
+
+
+class AppListParams(AppListBaseParams):
     status: str | None = None
     openapi_visible: bool = False
 
 
+class StarredAppListParams(AppListBaseParams):
+    pass
+
+
 class CreateAppParams(BaseModel):
     name: str = Field(min_length=1)
     description: str | None = None
     mode: Literal["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"]
+    agent_role: str = Field(default="", max_length=255)
     icon_type: str | None = None
     icon: str | None = None
     icon_background: str | None = None
@@ -61,6 +73,85 @@ class CreateAppParams(BaseModel):
 
 
 class AppService:
+    @staticmethod
+    def _build_app_list_filters(
+        user_id: str, tenant_id: str, params: AppListBaseParams
+    ) -> list[sa.ColumnElement[bool]]:
+        filters = [App.tenant_id == tenant_id, App.is_universal == False]
+
+        if params.mode == "workflow":
+            filters.append(App.mode == AppMode.WORKFLOW)
+        elif params.mode == "completion":
+            filters.append(App.mode == AppMode.COMPLETION)
+        elif params.mode == "chat":
+            filters.append(App.mode == AppMode.CHAT)
+        elif params.mode == "advanced-chat":
+            filters.append(App.mode == AppMode.ADVANCED_CHAT)
+        elif params.mode == "agent-chat":
+            filters.append(App.mode == AppMode.AGENT_CHAT)
+        elif params.mode == "agent":
+            filters.append(App.mode == AppMode.AGENT)
+        elif params.mode == "all":
+            filters.append(App.mode != AppMode.AGENT)
+
+        if isinstance(params, AppListParams):
+            if params.status:
+                filters.append(App.status == params.status)
+            # OpenAPI surface visibility gate. Pushed into the query so
+            # `pagination.total` reflects only apps the openapi caller can
+            # actually reach; post-filtering by enable_api after the page
+            # arrives would make `total` page-dependent.
+            if params.openapi_visible:
+                filters.append(App.enable_api.is_(True))
+
+        if params.is_created_by_me:
+            filters.append(App.created_by == user_id)
+        if params.creator_ids:
+            filters.append(App.created_by.in_(params.creator_ids))
+        if params.name:
+            from libs.helper import escape_like_pattern
+
+            name = params.name[:30]
+            escaped_name = escape_like_pattern(name)
+            filters.append(App.name.ilike(f"%{escaped_name}%", escape="\\"))
+        if params.tag_ids and len(params.tag_ids) > 0:
+            target_ids = TagService.get_target_ids_by_tag_ids("app", tenant_id, params.tag_ids, match_all=True)
+            if target_ids and len(target_ids) > 0:
+                filters.append(App.id.in_(target_ids))
+            else:
+                return []
+
+        return filters
+
+    @staticmethod
+    def _build_app_list_order_by(sort_by: AppListSortBy) -> sa.ColumnElement[Any]:
+        return {
+            "last_modified": App.updated_at.desc(),
+            "recently_created": App.created_at.desc(),
+            "earliest_created": App.created_at.asc(),
+        }[sort_by]
+
+    @staticmethod
+    def get_starred_app_ids(
+        session: Session | scoped_session,
+        *,
+        tenant_id: str,
+        account_id: str,
+        app_ids: Sequence[str],
+    ) -> set[str]:
+        """Return app IDs starred by this account within the tenant."""
+        if not app_ids:
+            return set()
+
+        starred_app_ids = session.scalars(
+            select(AppStar.app_id).where(
+                AppStar.tenant_id == tenant_id,
+                AppStar.account_id == account_id,
+                AppStar.app_id.in_(list(app_ids)),
+            )
+        ).all()
+        return set(starred_app_ids)
+
     @staticmethod
     def get_app_by_id(
         session: Session | scoped_session,
@@ -108,61 +199,104 @@ class AppService:
 
     def get_paginate_apps(self, user_id: str, tenant_id: str, params: AppListParams) -> Pagination | None:
         """
-        Get app list with pagination
+        Get app list with pagination, filters, and explicit sort order.
         :param user_id: user id
         :param tenant_id: tenant id
         :param params: query parameters
         :return:
         """
-        filters = [App.tenant_id == tenant_id, App.is_universal == False]
+        filters = self._build_app_list_filters(user_id, tenant_id, params)
+        if not filters:
+            return None
 
-        if params.mode == "workflow":
-            filters.append(App.mode == AppMode.WORKFLOW)
-        elif params.mode == "completion":
-            filters.append(App.mode == AppMode.COMPLETION)
-        elif params.mode == "chat":
-            filters.append(App.mode == AppMode.CHAT)
-        elif params.mode == "advanced-chat":
-            filters.append(App.mode == AppMode.ADVANCED_CHAT)
-        elif params.mode == "agent-chat":
-            filters.append(App.mode == AppMode.AGENT_CHAT)
-        elif params.mode == "agent":
-            filters.append(App.mode == AppMode.AGENT)
-
-        if params.status:
-            filters.append(App.status == params.status)
-        # OpenAPI surface visibility gate. Pushed into the query so
-        # `pagination.total` reflects only apps the openapi caller can
-        # actually reach — post-filtering by enable_api after the page
-        # arrives would make `total` page-dependent.
-        if params.openapi_visible:
-            filters.append(App.enable_api.is_(True))
-        if params.is_created_by_me:
-            filters.append(App.created_by == user_id)
-        if params.creator_ids:
-            filters.append(App.created_by.in_(params.creator_ids))
-        if params.name:
-            from libs.helper import escape_like_pattern
-
-            name = params.name[:30]
-            escaped_name = escape_like_pattern(name)
-            filters.append(App.name.ilike(f"%{escaped_name}%", escape="\\"))
-        if params.tag_ids and len(params.tag_ids) > 0:
-            target_ids = TagService.get_target_ids_by_tag_ids("app", tenant_id, params.tag_ids, match_all=True)
-            if target_ids and len(target_ids) > 0:
-                filters.append(App.id.in_(target_ids))
-            else:
-                return None
+        order_by = self._build_app_list_order_by(params.sort_by)
 
         app_models = db.paginate(
-            sa.select(App).where(*filters).order_by(App.created_at.desc()),
+            sa.select(App).where(*filters).order_by(order_by),
             page=params.page,
             per_page=params.limit,
             error_out=False,
         )
 
+        app_ids = [str(app.id) for app in app_models.items]
+        starred_app_ids = self.get_starred_app_ids(
+            db.session,
+            tenant_id=tenant_id,
+            account_id=user_id,
+            app_ids=app_ids,
+        )
+        for app in app_models.items:
+            app.is_starred = str(app.id) in starred_app_ids
+
         return app_models
 
+    def get_paginate_starred_apps(
+        self, user_id: str, tenant_id: str, params: StarredAppListParams
+    ) -> Pagination | None:
+        """
+        Get apps starred by the current account with pagination, filters, and explicit sort order.
+        """
+        filters = self._build_app_list_filters(user_id, tenant_id, params)
+        if not filters:
+            return None
+
+        order_by = self._build_app_list_order_by(params.sort_by)
+        app_models = db.paginate(
+            sa.select(App)
+            .join(
+                AppStar,
+                sa.and_(
+                    AppStar.tenant_id == App.tenant_id,
+                    AppStar.app_id == App.id,
+                    AppStar.account_id == user_id,
+                ),
+            )
+            .where(AppStar.tenant_id == tenant_id, *filters)
+            .order_by(order_by),
+            page=params.page,
+            per_page=params.limit,
+            error_out=False,
+        )
+
+        for app in app_models.items:
+            app.is_starred = True
+
+        return app_models
+
+    @staticmethod
+    def star_app(session: Session, *, app: App, account_id: str) -> None:
+        """Create the account's app star if it does not already exist."""
+        existing_star = session.scalar(
+            select(AppStar)
+            .where(
+                AppStar.tenant_id == app.tenant_id,
+                AppStar.app_id == app.id,
+                AppStar.account_id == account_id,
+            )
+            .limit(1)
+        )
+        if existing_star:
+            return
+
+        session.add(AppStar(tenant_id=app.tenant_id, app_id=app.id, account_id=account_id))
+
+    @staticmethod
+    def unstar_app(session: Session, *, app: App, account_id: str) -> None:
+        """Remove the account's app star if present."""
+        existing_star = session.scalar(
+            select(AppStar)
+            .where(
+                AppStar.tenant_id == app.tenant_id,
+                AppStar.app_id == app.id,
+                AppStar.account_id == account_id,
+            )
+            .limit(1)
+        )
+        if not existing_star:
+            return
+
+        session.delete(existing_star)
+
     def create_app(self, tenant_id: str, params: CreateAppParams, account: Account) -> App:
         """
         Create app
@@ -281,6 +415,7 @@ class AppService:
                 app_id=app.id,
                 name=params.name,
                 description=params.description or "",
+                role=params.agent_role,
                 icon_type=icon_type,
                 icon=params.icon,
                 icon_background=params.icon_background,
@@ -376,6 +511,66 @@ class AppService:
         icon_background: str
         use_icon_as_answer_icon: bool
         max_active_requests: int
+        role: NotRequired[str | None]
+
+    @staticmethod
+    def _get_backing_agent_for_update(app: App) -> Agent | None:
+        if app.mode != AppMode.AGENT:
+            return None
+        return db.session.scalar(
+            select(Agent).where(
+                Agent.tenant_id == app.tenant_id,
+                Agent.app_id == app.id,
+                Agent.scope == AgentScope.ROSTER,
+                Agent.source == AgentSource.AGENT_APP,
+                Agent.status == AgentStatus.ACTIVE,
+            )
+        )
+
+    @staticmethod
+    def _to_agent_icon_type(icon_type: IconType | str | None) -> AgentIconType | None:
+        if icon_type is None:
+            return None
+        value = icon_type.value if isinstance(icon_type, IconType) else icon_type
+        return AgentIconType(value)
+
+    def _sync_backing_agent_identity(
+        self,
+        app: App,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        icon_type: IconType | str | None = None,
+        icon: str | None = None,
+        icon_background: str | None = None,
+        role: str | None = None,
+        account_id: str | None = None,
+        updated_at: datetime | None = None,
+    ) -> None:
+        """Keep the Roster identity aligned with its Agent App shell.
+
+        Agent Soul remains versioned through Composer. This helper only mirrors
+        user-facing identity fields so Roster and Agent Console do not drift.
+        """
+        agent = self._get_backing_agent_for_update(app)
+        if agent is None:
+            return
+
+        if name is not None:
+            agent.name = name
+        if description is not None:
+            agent.description = description
+        if icon_type is not None:
+            agent.icon_type = self._to_agent_icon_type(icon_type)
+        if icon is not None:
+            agent.icon = icon
+        if icon_background is not None:
+            agent.icon_background = icon_background
+        if role is not None:
+            agent.role = role
+        agent.updated_by = account_id
+        if updated_at is not None:
+            agent.updated_at = updated_at
 
     def update_app(self, app: App, args: ArgsDict) -> App:
         """
@@ -400,6 +595,17 @@ class AppService:
         app.max_active_requests = args.get("max_active_requests")
         app.updated_by = current_user.id
         app.updated_at = naive_utc_now()
+        self._sync_backing_agent_identity(
+            app,
+            name=app.name,
+            description=app.description,
+            icon_type=app.icon_type,
+            icon=app.icon,
+            icon_background=app.icon_background,
+            role=args.get("role"),
+            account_id=current_user.id,
+            updated_at=app.updated_at,
+        )
         db.session.commit()
 
         app_was_updated.send(app)
@@ -417,6 +623,12 @@ class AppService:
         app.name = name
         app.updated_by = current_user.id
         app.updated_at = naive_utc_now()
+        self._sync_backing_agent_identity(
+            app,
+            name=app.name,
+            account_id=current_user.id,
+            updated_at=app.updated_at,
+        )
         db.session.commit()
 
         app_was_updated.send(app)
@@ -441,6 +653,14 @@ class AppService:
             app.icon_type = icon_type if isinstance(icon_type, IconType) else IconType(icon_type)
         app.updated_by = current_user.id
         app.updated_at = naive_utc_now()
+        self._sync_backing_agent_identity(
+            app,
+            icon_type=app.icon_type,
+            icon=app.icon,
+            icon_background=app.icon_background,
+            account_id=current_user.id,
+            updated_at=app.updated_at,
+        )
         db.session.commit()
 
         app_was_updated.send(app)
@@ -493,6 +713,16 @@ class AppService:
         """
         app_was_deleted.send(app)
 
+        backing_agent = self._get_backing_agent_for_update(app)
+        if backing_agent is not None:
+            now = naive_utc_now()
+            account_id = getattr(current_user, "id", None)
+            backing_agent.status = AgentStatus.ARCHIVED
+            backing_agent.archived_by = account_id
+            backing_agent.archived_at = now
+            backing_agent.updated_by = account_id
+            backing_agent.updated_at = now
+
         db.session.delete(app)
         db.session.commit()
 

api/services/auth/jina.py

@@ -43,10 +43,16 @@ class JinaAuth(ApiKeyAuthBase):
 
     def _handle_error(self, response):
         if response.status_code in {402, 409, 500}:
-            error_message = response.json().get("error", "Unknown error occurred")
+            try:
+                error_message = response.json().get("error", "Unknown error occurred")
+            except ValueError:
+                error_message = response.text or "Unknown error occurred"
             raise Exception(f"Failed to authorize. Status code: {response.status_code}. Error: {error_message}")
         else:
             if response.text:
-                error_message = json.loads(response.text).get("error", "Unknown error occurred")
+                try:
+                    error_message = json.loads(response.text).get("error", "Unknown error occurred")
+                except ValueError:
+                    error_message = response.text
                 raise Exception(f"Failed to authorize. Status code: {response.status_code}. Error: {error_message}")
             raise Exception(f"Unexpected error occurred while trying to authorize. Status code: {response.status_code}")

api/services/auth/jina/jina.py

@@ -43,10 +43,16 @@ class JinaAuth(ApiKeyAuthBase):
 
     def _handle_error(self, response):
         if response.status_code in {402, 409, 500}:
-            error_message = response.json().get("error", "Unknown error occurred")
+            try:
+                error_message = response.json().get("error", "Unknown error occurred")
+            except ValueError:
+                error_message = response.text or "Unknown error occurred"
             raise Exception(f"Failed to authorize. Status code: {response.status_code}. Error: {error_message}")
         else:
             if response.text:
-                error_message = json.loads(response.text).get("error", "Unknown error occurred")
+                try:
+                    error_message = json.loads(response.text).get("error", "Unknown error occurred")
+                except ValueError:
+                    error_message = response.text
                 raise Exception(f"Failed to authorize. Status code: {response.status_code}. Error: {error_message}")
             raise Exception(f"Unexpected error occurred while trying to authorize. Status code: {response.status_code}")

api/services/auth/watercrawl/watercrawl.py

@@ -37,10 +37,16 @@ class WatercrawlAuth(ApiKeyAuthBase):
 
     def _handle_error(self, response):
         if response.status_code in {402, 409, 500}:
-            error_message = response.json().get("error", "Unknown error occurred")
+            try:
+                error_message = response.json().get("error", "Unknown error occurred")
+            except ValueError:
+                error_message = response.text or "Unknown error occurred"
             raise Exception(f"Failed to authorize. Status code: {response.status_code}. Error: {error_message}")
         else:
             if response.text:
-                error_message = json.loads(response.text).get("error", "Unknown error occurred")
+                try:
+                    error_message = json.loads(response.text).get("error", "Unknown error occurred")
+                except ValueError:
+                    error_message = response.text
                 raise Exception(f"Failed to authorize. Status code: {response.status_code}. Error: {error_message}")
             raise Exception(f"Unexpected error occurred while trying to authorize. Status code: {response.status_code}")

api/services/entities/model_provider_entities.py

@@ -192,6 +192,27 @@ class SimpleProviderEntityResponse(BaseModel):
         return self
 
 
+class ProviderEntityResponse(BaseModel):
+    """Runtime provider response with codegen-safe model pricing schemas."""
+
+    provider: str
+    provider_name: str = ""
+    label: I18nObject
+    description: I18nObject | None = None
+    icon_small: I18nObject | None = None
+    icon_small_dark: I18nObject | None = None
+    background: str | None = None
+    help: ProviderHelpEntity | None = None
+    supported_model_types: Sequence[ModelType]
+    configurate_methods: list[ConfigurateMethod]
+    models: list[AIModelEntityResponse] = []
+    provider_credential_schema: ProviderCredentialSchema | None = None
+    model_credential_schema: ModelCredentialSchema | None = None
+    position: dict[str, list[str]] | None = {}
+
+    model_config = ConfigDict(from_attributes=True, protected_namespaces=())
+
+
 class DefaultModelResponse(BaseModel):
     """
     Default model entity.

api/services/human_input_service.py

@@ -223,9 +223,12 @@ class HumanInputService:
 
         if result.form_kind != HumanInputFormKind.RUNTIME:
             return
-        if result.workflow_run_id is None:
-            return
-        self.enqueue_resume(result.workflow_run_id)
+        # A RUNTIME form is owned by a workflow run (workflow Agent node) or a
+        # conversation (ENG-635: Agent v2 chat). Route the resume accordingly.
+        if result.workflow_run_id is not None:
+            self.enqueue_resume(result.workflow_run_id)
+        elif result.conversation_id is not None:
+            self.enqueue_agent_app_resume(conversation_id=result.conversation_id, form_id=result.form_id)
 
     def ensure_form_active(self, form: Form) -> None:
         if form.submitted:
@@ -286,6 +289,22 @@ class HumanInputService:
 
         logger.warning("App mode %s does not support resume for workflow run %s", app.mode, workflow_run_id)
 
+    def enqueue_agent_app_resume(self, *, conversation_id: str, form_id: str) -> None:
+        """ENG-635: resume an Agent v2 chat after its ask_human form is submitted.
+
+        Enqueues a background turn for the conversation; the Agent App runner
+        continues the agent run, threading the human's reply into the request as
+        ``deferred_tool_results``.
+        """
+        from tasks.app_generate.resume_agent_app_task import resume_agent_app_execution
+
+        try:
+            resume_agent_app_execution.apply_async(
+                kwargs={"conversation_id": conversation_id, "form_id": form_id},
+            )
+        except Exception:  # pragma: no cover
+            logger.exception("Failed to enqueue Agent App resume for conversation %s form %s", conversation_id, form_id)
+
     def _load_variable_pool_for_form(self, form: Form) -> ReadOnlyVariablePool | None:
         workflow_run_id = form.workflow_run_id
         if workflow_run_id is None:

api/services/plugin/plugin_auto_upgrade_service.py

@@ -1,18 +1,295 @@
+"""Manage tenant plugin auto-upgrade strategies.
+
+The storage is category-scoped: each tenant can have one strategy per plugin
+category. Public mutation helpers require an explicit category so callers do
+not accidentally overwrite every plugin type with one workspace-level policy.
+"""
+
+import logging
+from dataclasses import dataclass
+from hashlib import sha256
+
 from sqlalchemy import select
+from sqlalchemy.orm import Session
 
 from core.db.session_factory import session_factory
+from core.plugin.impl.plugin import PluginInstaller
 from models.account import TenantPluginAutoUpgradeStrategy
 
+logger = logging.getLogger(__name__)
+
+PluginCategory = TenantPluginAutoUpgradeStrategy.PluginCategory
+PLUGIN_CATEGORIES = tuple(PluginCategory)
+SECONDS_PER_DAY = 24 * 60 * 60
+AUTO_UPGRADE_CHECK_SLOT_SECONDS = 15 * 60
+AUTO_UPGRADE_CHECK_SLOT_COUNT = SECONDS_PER_DAY // AUTO_UPGRADE_CHECK_SLOT_SECONDS
+
+
+@dataclass(frozen=True)
+class PluginAutoUpgradeBackfillResult:
+    created_count: int
+    normalized: bool
+
 
 class PluginAutoUpgradeService:
     @staticmethod
-    def get_strategy(tenant_id: str) -> TenantPluginAutoUpgradeStrategy | None:
-        with session_factory.create_session() as session:
-            return session.scalar(
-                select(TenantPluginAutoUpgradeStrategy)
-                .where(TenantPluginAutoUpgradeStrategy.tenant_id == tenant_id)
-                .limit(1)
+    def default_strategy_setting_for_category(
+        category: PluginCategory,
+    ) -> TenantPluginAutoUpgradeStrategy.StrategySetting:
+        if category == PluginCategory.MODEL:
+            return TenantPluginAutoUpgradeStrategy.StrategySetting.LATEST
+        return TenantPluginAutoUpgradeStrategy.StrategySetting.FIX_ONLY
+
+    @staticmethod
+    def default_upgrade_time_of_day(tenant_id: str) -> int:
+        """Spread default checks across 15-minute aligned slots by tenant."""
+        hash_input = tenant_id.encode()
+        slot = int.from_bytes(sha256(hash_input).digest()[:8], "big") % AUTO_UPGRADE_CHECK_SLOT_COUNT
+        return slot * AUTO_UPGRADE_CHECK_SLOT_SECONDS
+
+    @staticmethod
+    def _coerce_category(category: object) -> PluginCategory | None:
+        """Accept daemon enum/string categories and ignore unknown values."""
+        category_value = getattr(category, "value", category)
+        if category_value is None:
+            return None
+
+        try:
+            return PluginCategory(str(category_value))
+        except ValueError:
+            return None
+
+    @staticmethod
+    def _get_installed_plugin_categories(tenant_id: str) -> dict[str, PluginCategory]:
+        """Build a plugin_id -> category map for splitting legacy include/exclude lists."""
+        installed_plugins = PluginInstaller().list_plugins(tenant_id)
+        plugin_categories: dict[str, PluginCategory] = {}
+
+        for plugin in installed_plugins:
+            plugin_category = PluginAutoUpgradeService._coerce_category(plugin.declaration.category)
+            if plugin_category is not None:
+                plugin_categories[plugin.plugin_id] = plugin_category
+
+        return plugin_categories
+
+    @staticmethod
+    def _filter_plugin_ids_for_category(
+        plugin_ids: list[str],
+        category: PluginCategory,
+        plugin_categories: dict[str, PluginCategory],
+    ) -> list[str]:
+        return [plugin_id for plugin_id in plugin_ids if plugin_categories.get(plugin_id) == category]
+
+    @staticmethod
+    def _log_unknown_plugin_ids(
+        tenant_id: str,
+        field_name: str,
+        plugin_ids: list[str],
+        plugin_categories: dict[str, PluginCategory],
+    ) -> None:
+        unknown_plugin_ids = [plugin_id for plugin_id in plugin_ids if plugin_id not in plugin_categories]
+        if not unknown_plugin_ids:
+            return
+
+        logger.warning(
+            "Skipped unknown plugin IDs while backfilling plugin auto-upgrade strategies: "
+            "tenant_id=%s, field=%s, plugin_ids=%s",
+            tenant_id,
+            field_name,
+            unknown_plugin_ids,
+        )
+
+    @staticmethod
+    def _has_default_strategy(strategy: TenantPluginAutoUpgradeStrategy) -> bool:
+        return (
+            strategy.strategy_setting == TenantPluginAutoUpgradeStrategy.StrategySetting.FIX_ONLY
+            and strategy.upgrade_time_of_day == 0
+            and strategy.upgrade_mode == TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE
+            and not strategy.exclude_plugins
+            and not strategy.include_plugins
+        )
+
+    @staticmethod
+    def _strategy_setting_for_category(
+        source_strategy: TenantPluginAutoUpgradeStrategy,
+        category: PluginCategory,
+        source_has_default_strategy: bool,
+    ) -> TenantPluginAutoUpgradeStrategy.StrategySetting:
+        # Only pure legacy defaults adopt the new model=latest default. User-edited
+        # strategies keep their original setting across all categories.
+        if source_has_default_strategy:
+            return PluginAutoUpgradeService.default_strategy_setting_for_category(category)
+        return source_strategy.strategy_setting
+
+    @staticmethod
+    def _upgrade_time_of_day_for_category(
+        tenant_id: str,
+        source_strategy: TenantPluginAutoUpgradeStrategy,
+        source_has_default_strategy: bool,
+    ) -> int:
+        # Pure legacy defaults are spread by tenant so all default rows do not
+        # concentrate in the same scheduler window. User-edited schedules keep their time.
+        if source_has_default_strategy:
+            return PluginAutoUpgradeService.default_upgrade_time_of_day(tenant_id)
+        return source_strategy.upgrade_time_of_day
+
+    @staticmethod
+    def backfill_strategy_categories(
+        tenant_id: str,
+    ) -> PluginAutoUpgradeBackfillResult:
+        """Create missing category strategies and split include/exclude lists when needed.
+
+        The historical row is treated as the workspace-level source strategy.
+        New category rows copy it first, then plugin lists are narrowed by real
+        plugin category when the source strategy contains include/exclude IDs.
+        """
+        with session_factory.create_session() as session, session.begin():
+            strategies = list(
+                session.scalars(
+                    select(TenantPluginAutoUpgradeStrategy).where(
+                        TenantPluginAutoUpgradeStrategy.tenant_id == tenant_id
+                    )
+                ).all()
             )
+            if not strategies:
+                return PluginAutoUpgradeBackfillResult(created_count=0, normalized=False)
+
+            # Schema migration marks the historical workspace-level row as tool.
+            source_strategy = next(
+                (strategy for strategy in strategies if strategy.category == PluginCategory.TOOL),
+                strategies[0],
+            )
+            source_has_default_strategy = PluginAutoUpgradeService._has_default_strategy(source_strategy)
+            strategies_by_category = {strategy.category: strategy for strategy in strategies}
+            exclude_plugins = source_strategy.exclude_plugins
+            include_plugins = source_strategy.include_plugins
+            should_split_plugin_lists = bool(exclude_plugins or include_plugins)
+            # Query daemon only for tenants that actually customized plugin lists.
+            plugin_categories = (
+                PluginAutoUpgradeService._get_installed_plugin_categories(tenant_id)
+                if should_split_plugin_lists
+                else {}
+            )
+            if should_split_plugin_lists:
+                PluginAutoUpgradeService._log_unknown_plugin_ids(
+                    tenant_id,
+                    "exclude_plugins",
+                    exclude_plugins,
+                    plugin_categories,
+                )
+                PluginAutoUpgradeService._log_unknown_plugin_ids(
+                    tenant_id,
+                    "include_plugins",
+                    include_plugins,
+                    plugin_categories,
+                )
+
+            created_count = 0
+            for category in PLUGIN_CATEGORIES:
+                strategy = strategies_by_category.get(category)
+                if strategy is None:
+                    # Start from the legacy workspace-level behavior before narrowing lists.
+                    strategy = TenantPluginAutoUpgradeStrategy(
+                        tenant_id=tenant_id,
+                        category=category,
+                        strategy_setting=PluginAutoUpgradeService._strategy_setting_for_category(
+                            source_strategy, category, source_has_default_strategy
+                        ),
+                        upgrade_time_of_day=PluginAutoUpgradeService._upgrade_time_of_day_for_category(
+                            tenant_id, source_strategy, source_has_default_strategy
+                        ),
+                        upgrade_mode=source_strategy.upgrade_mode,
+                        exclude_plugins=source_strategy.exclude_plugins.copy(),
+                        include_plugins=source_strategy.include_plugins.copy(),
+                    )
+                    session.add(strategy)
+                    created_count += 1
+                elif source_has_default_strategy:
+                    strategy.strategy_setting = PluginAutoUpgradeService.default_strategy_setting_for_category(
+                        strategy.category
+                    )
+                    strategy.upgrade_time_of_day = PluginAutoUpgradeService.default_upgrade_time_of_day(tenant_id)
+
+                if not should_split_plugin_lists:
+                    continue
+
+                # Narrow include/exclude lists to the current category after all rows exist.
+                strategy.exclude_plugins = PluginAutoUpgradeService._filter_plugin_ids_for_category(
+                    exclude_plugins,
+                    strategy.category,
+                    plugin_categories,
+                )
+                strategy.include_plugins = PluginAutoUpgradeService._filter_plugin_ids_for_category(
+                    include_plugins,
+                    strategy.category,
+                    plugin_categories,
+                )
+
+            return PluginAutoUpgradeBackfillResult(created_count=created_count, normalized=should_split_plugin_lists)
+
+    @staticmethod
+    def _get_strategy(
+        session: Session,
+        tenant_id: str,
+        category: PluginCategory,
+    ) -> TenantPluginAutoUpgradeStrategy | None:
+        return session.scalar(
+            select(TenantPluginAutoUpgradeStrategy)
+            .where(
+                TenantPluginAutoUpgradeStrategy.tenant_id == tenant_id,
+                TenantPluginAutoUpgradeStrategy.category == category,
+            )
+            .limit(1)
+        )
+
+    @staticmethod
+    def get_strategy(
+        tenant_id: str,
+        category: PluginCategory,
+    ) -> TenantPluginAutoUpgradeStrategy | None:
+        with session_factory.create_session() as session:
+            return PluginAutoUpgradeService._get_strategy(session, tenant_id, category)
+
+    @staticmethod
+    def get_strategies(tenant_id: str) -> list[TenantPluginAutoUpgradeStrategy]:
+        with session_factory.create_session() as session:
+            return list(
+                session.scalars(
+                    select(TenantPluginAutoUpgradeStrategy).where(
+                        TenantPluginAutoUpgradeStrategy.tenant_id == tenant_id
+                    )
+                ).all()
+            )
+
+    @staticmethod
+    def _change_strategy(
+        session: Session,
+        tenant_id: str,
+        category: PluginCategory,
+        strategy_setting: TenantPluginAutoUpgradeStrategy.StrategySetting,
+        upgrade_time_of_day: int,
+        upgrade_mode: TenantPluginAutoUpgradeStrategy.UpgradeMode,
+        exclude_plugins: list[str],
+        include_plugins: list[str],
+    ) -> None:
+        exist_strategy = PluginAutoUpgradeService._get_strategy(session, tenant_id, category)
+        if not exist_strategy:
+            strategy = TenantPluginAutoUpgradeStrategy(
+                tenant_id=tenant_id,
+                category=category,
+                strategy_setting=strategy_setting,
+                upgrade_time_of_day=upgrade_time_of_day,
+                upgrade_mode=upgrade_mode,
+                exclude_plugins=exclude_plugins,
+                include_plugins=include_plugins,
+            )
+            session.add(strategy)
+        else:
+            exist_strategy.strategy_setting = strategy_setting
+            exist_strategy.upgrade_time_of_day = upgrade_time_of_day
+            exist_strategy.upgrade_mode = upgrade_mode
+            exist_strategy.exclude_plugins = exclude_plugins
+            exist_strategy.include_plugins = include_plugins
 
     @staticmethod
     def change_strategy(
@@ -22,64 +299,72 @@ class PluginAutoUpgradeService:
         upgrade_mode: TenantPluginAutoUpgradeStrategy.UpgradeMode,
         exclude_plugins: list[str],
         include_plugins: list[str],
+        category: PluginCategory,
     ) -> bool:
         with session_factory.create_session() as session, session.begin():
-            exist_strategy = session.scalar(
-                select(TenantPluginAutoUpgradeStrategy)
-                .where(TenantPluginAutoUpgradeStrategy.tenant_id == tenant_id)
-                .limit(1)
+            PluginAutoUpgradeService._change_strategy(
+                session,
+                tenant_id=tenant_id,
+                category=category,
+                strategy_setting=strategy_setting,
+                upgrade_time_of_day=upgrade_time_of_day,
+                upgrade_mode=upgrade_mode,
+                exclude_plugins=exclude_plugins,
+                include_plugins=include_plugins,
             )
-            if not exist_strategy:
-                strategy = TenantPluginAutoUpgradeStrategy(
-                    tenant_id=tenant_id,
-                    strategy_setting=strategy_setting,
-                    upgrade_time_of_day=upgrade_time_of_day,
-                    upgrade_mode=upgrade_mode,
-                    exclude_plugins=exclude_plugins,
-                    include_plugins=include_plugins,
-                )
-                session.add(strategy)
-            else:
-                exist_strategy.strategy_setting = strategy_setting
-                exist_strategy.upgrade_time_of_day = upgrade_time_of_day
-                exist_strategy.upgrade_mode = upgrade_mode
-                exist_strategy.exclude_plugins = exclude_plugins
-                exist_strategy.include_plugins = include_plugins
 
             return True
 
     @staticmethod
-    def exclude_plugin(tenant_id: str, plugin_id: str) -> bool:
-        with session_factory.create_session() as session, session.begin():
-            exist_strategy = session.scalar(
-                select(TenantPluginAutoUpgradeStrategy)
-                .where(TenantPluginAutoUpgradeStrategy.tenant_id == tenant_id)
-                .limit(1)
+    def _exclude_plugin(
+        session: Session,
+        tenant_id: str,
+        category: PluginCategory,
+        plugin_id: str,
+    ) -> None:
+        """Remove one plugin from automatic updates for a single category strategy."""
+        exist_strategy = PluginAutoUpgradeService._get_strategy(session, tenant_id, category)
+        if not exist_strategy:
+            PluginAutoUpgradeService._change_strategy(
+                session,
+                tenant_id,
+                category,
+                TenantPluginAutoUpgradeStrategy.StrategySetting.FIX_ONLY,
+                0,
+                TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE,
+                [plugin_id],
+                [],
             )
-            if not exist_strategy:
-                # create for this tenant
-                PluginAutoUpgradeService.change_strategy(
-                    tenant_id,
-                    TenantPluginAutoUpgradeStrategy.StrategySetting.FIX_ONLY,
-                    0,
-                    TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE,
-                    [plugin_id],
-                    [],
-                )
-                return True
-            else:
-                if exist_strategy.upgrade_mode == TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE:
-                    if plugin_id not in exist_strategy.exclude_plugins:
-                        new_exclude_plugins = exist_strategy.exclude_plugins.copy()
-                        new_exclude_plugins.append(plugin_id)
-                        exist_strategy.exclude_plugins = new_exclude_plugins
-                elif exist_strategy.upgrade_mode == TenantPluginAutoUpgradeStrategy.UpgradeMode.PARTIAL:
-                    if plugin_id in exist_strategy.include_plugins:
-                        new_include_plugins = exist_strategy.include_plugins.copy()
-                        new_include_plugins.remove(plugin_id)
-                        exist_strategy.include_plugins = new_include_plugins
-                elif exist_strategy.upgrade_mode == TenantPluginAutoUpgradeStrategy.UpgradeMode.ALL:
-                    exist_strategy.upgrade_mode = TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE
-                    exist_strategy.exclude_plugins = [plugin_id]
+        else:
+            if exist_strategy.upgrade_mode == TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE:
+                # In exclude mode, disabling one plugin means adding it to exclude_plugins.
+                if plugin_id not in exist_strategy.exclude_plugins:
+                    new_exclude_plugins = exist_strategy.exclude_plugins.copy()
+                    new_exclude_plugins.append(plugin_id)
+                    exist_strategy.exclude_plugins = new_exclude_plugins
+            elif exist_strategy.upgrade_mode == TenantPluginAutoUpgradeStrategy.UpgradeMode.PARTIAL:
+                # In partial mode, disabling one plugin means removing it from include_plugins.
+                if plugin_id in exist_strategy.include_plugins:
+                    new_include_plugins = exist_strategy.include_plugins.copy()
+                    new_include_plugins.remove(plugin_id)
+                    exist_strategy.include_plugins = new_include_plugins
+            elif exist_strategy.upgrade_mode == TenantPluginAutoUpgradeStrategy.UpgradeMode.ALL:
+                # In all mode, switch to exclude mode so only this plugin is skipped.
+                exist_strategy.upgrade_mode = TenantPluginAutoUpgradeStrategy.UpgradeMode.EXCLUDE
+                exist_strategy.exclude_plugins = [plugin_id]
 
-                return True
+    @staticmethod
+    def exclude_plugin(
+        tenant_id: str,
+        plugin_id: str,
+        category: PluginCategory,
+    ) -> bool:
+        with session_factory.create_session() as session, session.begin():
+            PluginAutoUpgradeService._exclude_plugin(
+                session,
+                tenant_id,
+                category,
+                plugin_id,
+            )
+
+            return True

api/services/rag_pipeline/rag_pipeline_transform_service.py

@@ -8,6 +8,7 @@ from uuid import uuid4
 import yaml
 from flask_login import current_user
 from sqlalchemy import select
+from sqlalchemy.orm import scoped_session
 
 from configs import dify_config
 from constants import DOCUMENT_EXTENSIONS
@@ -28,8 +29,8 @@ logger = logging.getLogger(__name__)
 
 
 class RagPipelineTransformService:
-    def transform_dataset(self, dataset_id: str):
-        dataset = db.session.get(Dataset, dataset_id)
+    def transform_dataset(self, dataset_id: str, session: scoped_session):
+        dataset = session.get(Dataset, dataset_id)
         if not dataset:
             raise ValueError("Dataset not found")
         if dataset.pipeline_id and dataset.runtime_mode == DatasetRuntimeMode.RAG_PIPELINE:
@@ -94,9 +95,9 @@ class RagPipelineTransformService:
         dataset.pipeline_id = pipeline.id
 
         # deal document data
-        self._deal_document_data(dataset)
+        self._deal_document_data(dataset, session)
 
-        db.session.commit()
+        session.commit()
         return {
             "pipeline_id": pipeline.id,
             "dataset_id": dataset_id,
@@ -310,13 +311,13 @@ class RagPipelineTransformService:
             "status": "success",
         }
 
-    def _deal_document_data(self, dataset: Dataset):
+    def _deal_document_data(self, dataset: Dataset, session: scoped_session):
         file_node_id = "1752479895761"
         notion_node_id = "1752489759475"
         jina_node_id = "1752491761974"
         firecrawl_node_id = "1752565402678"
 
-        documents = db.session.scalars(select(Document).where(Document.dataset_id == dataset.id)).all()
+        documents = session.scalars(select(Document).where(Document.dataset_id == dataset.id)).all()
 
         for document in documents:
             data_source_info_dict = document.data_source_info_dict
@@ -326,7 +327,7 @@ class RagPipelineTransformService:
                 document.data_source_type = DataSourceType.LOCAL_FILE
                 file_id = data_source_info_dict.get("upload_file_id")
                 if file_id:
-                    file = db.session.get(UploadFile, file_id)
+                    file = session.get(UploadFile, file_id)
                     if file:
                         data_source_info = json.dumps(
                             {
@@ -350,8 +351,8 @@ class RagPipelineTransformService:
                             datasource_node_id=file_node_id,
                         )
                         document_pipeline_execution_log.created_at = document.created_at
-                        db.session.add(document)
-                        db.session.add(document_pipeline_execution_log)
+                        session.add(document)
+                        session.add(document_pipeline_execution_log)
             elif document.data_source_type == DataSourceType.NOTION_IMPORT:
                 document.data_source_type = DataSourceType.ONLINE_DOCUMENT
                 data_source_info = json.dumps(
@@ -378,8 +379,8 @@ class RagPipelineTransformService:
                     datasource_node_id=notion_node_id,
                 )
                 document_pipeline_execution_log.created_at = document.created_at
-                db.session.add(document)
-                db.session.add(document_pipeline_execution_log)
+                session.add(document)
+                session.add(document_pipeline_execution_log)
             elif document.data_source_type == DataSourceType.WEBSITE_CRAWL:
                 data_source_info = json.dumps(
                     {
@@ -406,5 +407,5 @@ class RagPipelineTransformService:
                     datasource_node_id=datasource_node_id,
                 )
                 document_pipeline_execution_log.created_at = document.created_at
-                db.session.add(document)
-                db.session.add(document_pipeline_execution_log)
+                session.add(document)
+                session.add(document_pipeline_execution_log)

api/services/recommend_app/database/database_retrieval.py

@@ -1,4 +1,4 @@
-from typing import Any, TypedDict, override
+from typing import Any, NotRequired, TypedDict, override
 
 from sqlalchemy import select
 
@@ -22,6 +22,7 @@ class RecommendedAppItemDict(TypedDict):
     categories: list[str]
     position: int
     is_listed: bool
+    can_trial: NotRequired[bool]
 
 
 class RecommendedAppsResultDict(TypedDict):
@@ -64,14 +65,47 @@ class DatabaseRecommendAppRetrieval(RecommendAppRetrievalBase):
         :param language: language
         :return:
         """
-        recommended_apps = db.session.scalars(
-            select(RecommendedApp).where(RecommendedApp.is_listed == True, RecommendedApp.language == language)
-        ).all()
+        recommended_apps = cls._fetch_listed_recommended_apps(language)
 
         if len(recommended_apps) == 0:
-            recommended_apps = db.session.scalars(
-                select(RecommendedApp).where(RecommendedApp.is_listed == True, RecommendedApp.language == languages[0])
-            ).all()
+            recommended_apps = cls._fetch_listed_recommended_apps(languages[0])
+
+        return cls._format_recommended_apps(recommended_apps, language)
+
+    @classmethod
+    def fetch_learn_dify_apps_from_db(cls, language: str) -> RecommendedAppsResultDict:
+        """
+        Fetch listed recommended apps explicitly marked for the Learn Dify section.
+        :param language: language
+        :return:
+        """
+        recommended_apps = cls._fetch_listed_recommended_apps(language, is_learn_dify=True)
+
+        if len(recommended_apps) == 0 and language != languages[0]:
+            recommended_apps = cls._fetch_listed_recommended_apps(languages[0], is_learn_dify=True)
+
+        return cls._format_recommended_apps(recommended_apps, language)
+
+    @classmethod
+    def _fetch_listed_recommended_apps(
+        cls, language: str, *, is_learn_dify: bool | None = None
+    ) -> list[RecommendedApp]:
+        filters = [RecommendedApp.is_listed.is_(True), RecommendedApp.language == language]
+        if is_learn_dify is not None:
+            filters.append(RecommendedApp.is_learn_dify.is_(is_learn_dify))
+
+        return list(db.session.scalars(select(RecommendedApp).where(*filters)).all())
+
+    @classmethod
+    def _format_recommended_apps(
+        cls, recommended_apps: list[RecommendedApp], language: str
+    ) -> RecommendedAppsResultDict:
+        """
+        Serialize DB recommended app rows into the Explore list response shape.
+        :param recommended_apps: recommended app rows
+        :param language: language used for category ordering
+        :return:
+        """
 
         categories = set()
         recommended_apps_result: list[RecommendedAppItemDict] = []

api/services/recommended_app_service.py

@@ -1,17 +1,18 @@
 from typing import Any
 
 from sqlalchemy import select
+from sqlalchemy.orm import scoped_session
 
 from configs import dify_config
-from extensions.ext_database import db
 from models.model import AccountTrialAppRecord, TrialApp
 from services.feature_service import FeatureService
+from services.recommend_app.database.database_retrieval import DatabaseRecommendAppRetrieval
 from services.recommend_app.recommend_app_factory import RecommendAppRetrievalFactory
 
 
 class RecommendedAppService:
     @classmethod
-    def get_recommended_apps_and_categories(cls, language: str):
+    def get_recommended_apps_and_categories(cls, session: scoped_session, language: str):
         """
         Get recommended apps and categories.
         :param language: language
@@ -31,15 +32,26 @@ class RecommendedAppService:
             apps = result["recommended_apps"]
             for app in apps:
                 app_id = app["app_id"]
-                trial_app_model = db.session.scalar(select(TrialApp).where(TrialApp.app_id == app_id).limit(1))
-                if trial_app_model:
-                    app["can_trial"] = True
-                else:
-                    app["can_trial"] = False
+                app["can_trial"] = cls._can_trial_app(session, app_id)
         return result
 
     @classmethod
-    def get_recommend_app_detail(cls, app_id: str) -> dict[str, Any] | None:
+    def get_learn_dify_apps(cls, session: scoped_session, language: str) -> dict[str, Any]:
+        """
+        Get database-backed recommended apps marked as Learn Dify.
+        :param language: language
+        :return:
+        """
+        result = DatabaseRecommendAppRetrieval.fetch_learn_dify_apps_from_db(language)
+
+        if FeatureService.get_system_features().enable_trial_app:
+            for app in result["recommended_apps"]:
+                app["can_trial"] = cls._can_trial_app(session, app["app_id"])
+
+        return {"recommended_apps": result["recommended_apps"]}
+
+    @classmethod
+    def get_recommend_app_detail(cls, session: scoped_session, app_id: str) -> dict[str, Any] | None:
         """
         Get recommend app detail.
         :param app_id: app id
@@ -52,28 +64,29 @@ class RecommendedAppService:
             return None
         if FeatureService.get_system_features().enable_trial_app:
             app_id = result["id"]
-            trial_app_model = db.session.scalar(select(TrialApp).where(TrialApp.app_id == app_id).limit(1))
-            if trial_app_model:
-                result["can_trial"] = True
-            else:
-                result["can_trial"] = False
+            result["can_trial"] = cls._can_trial_app(session, app_id)
         return result
 
     @classmethod
-    def add_trial_app_record(cls, app_id: str, account_id: str):
+    def add_trial_app_record(cls, session: scoped_session, app_id: str, account_id: str):
         """
         Add trial app record.
         :param app_id: app id
         :return:
         """
-        account_trial_app_record = db.session.scalar(
+        account_trial_app_record = session.scalar(
             select(AccountTrialAppRecord)
             .where(AccountTrialAppRecord.app_id == app_id, AccountTrialAppRecord.account_id == account_id)
             .limit(1)
         )
         if account_trial_app_record:
             account_trial_app_record.count += 1
-            db.session.commit()
+            session.commit()
         else:
-            db.session.add(AccountTrialAppRecord(app_id=app_id, count=1, account_id=account_id))
-            db.session.commit()
+            session.add(AccountTrialAppRecord(app_id=app_id, count=1, account_id=account_id))
+            session.commit()
+
+    @staticmethod
+    def _can_trial_app(session: scoped_session, app_id: str) -> bool:
+        trial_app_model = session.scalar(select(TrialApp).where(TrialApp.app_id == app_id).limit(1))
+        return trial_app_model is not None

api/services/snippet_dsl_service.py

@@ -6,7 +6,7 @@ from datetime import UTC, datetime
 from enum import StrEnum
 from urllib.parse import urlparse
 
-import yaml  # type: ignore
+import yaml
 from packaging import version
 from pydantic import BaseModel, Field
 from sqlalchemy import select
@@ -498,7 +498,7 @@ class SnippetDslService:
             export_data=export_data, snippet=snippet, workflow=workflow, include_secret=include_secret
         )
 
-        return yaml.dump(export_data, allow_unicode=True)  # type: ignore
+        return yaml.dump(export_data, allow_unicode=True)
 
     def _append_workflow_export_data(
         self, *, export_data: dict, snippet: CustomizedSnippet, workflow: Workflow, include_secret: bool

api/services/summary_index_service.py

@@ -123,7 +123,7 @@ class SummaryIndexService:
                 # Update existing record
                 existing_summary.summary_content = summary_content
                 existing_summary.status = status
-                existing_summary.error = None  # type: ignore[assignment]  # Clear any previous errors
+                existing_summary.error = None  # Clear any previous errors
                 # Re-enable if it was disabled
                 if not existing_summary.enabled:
                     existing_summary.enabled = True
@@ -583,7 +583,7 @@ class SummaryIndexService:
                 if existing_summary:
                     # Update existing record
                     existing_summary.status = status
-                    existing_summary.error = None  # type: ignore[assignment]  # Clear any previous errors
+                    existing_summary.error = None  # Clear any previous errors
                     if not existing_summary.enabled:
                         existing_summary.enabled = True
                         existing_summary.disabled_at = None
@@ -685,7 +685,7 @@ class SummaryIndexService:
 
                 # Update status to "generating"
                 summary_record_in_session.status = SummaryStatus.GENERATING
-                summary_record_in_session.error = None  # type: ignore[assignment]
+                summary_record_in_session.error = None
                 session.add(summary_record_in_session)
                 # Don't flush here - wait until after vectorization succeeds
 
@@ -1127,7 +1127,7 @@ class SummaryIndexService:
                     # Update summary content
                     summary_record.summary_content = summary_content
                     summary_record.status = SummaryStatus.GENERATING
-                    summary_record.error = None  # type: ignore[assignment]  # Clear any previous errors
+                    summary_record.error = None  # Clear any previous errors
                     session.add(summary_record)
                     # Flush to ensure summary_content is saved before vectorize_summary queries it
                     session.flush()

api/services/tag_service.py

@@ -6,6 +6,7 @@ from flask_login import current_user
 from pydantic import BaseModel, Field
 from sqlalchemy import delete, func, select
 from sqlalchemy.engine import CursorResult
+from sqlalchemy.orm import Session
 from werkzeug.exceptions import NotFound
 
 from extensions.ext_database import db
@@ -38,7 +39,7 @@ class TagBindingDeletePayload(BaseModel):
 
 class TagService:
     @staticmethod
-    def get_tags(tag_type: str, current_tenant_id: str, keyword: str | None = None):
+    def get_tags(session: Session, tag_type: str, current_tenant_id: str, keyword: str | None = None):
         stmt = (
             select(Tag.id, Tag.type, Tag.name, func.count(TagBinding.id).label("binding_count"))
             .outerjoin(TagBinding, Tag.id == TagBinding.tag_id)
@@ -50,7 +51,7 @@ class TagService:
             escaped_keyword = escape_like_pattern(keyword)
             stmt = stmt.where(sa.and_(Tag.name.ilike(f"%{escaped_keyword}%", escape="\\")))
         stmt = stmt.group_by(Tag.id, Tag.type, Tag.name, Tag.created_at)
-        results: list = list(db.session.execute(stmt.order_by(Tag.created_at.desc())).all())
+        results: list = list(session.execute(stmt.order_by(Tag.created_at.desc())).all())
         return results
 
     @staticmethod

api/services/workflow_service.py

@@ -323,7 +323,7 @@ class WorkflowService:
         from services.agent.workflow_publish_service import WorkflowAgentPublishService
 
         db.session.flush()
-        WorkflowAgentPublishService.sync_roster_agent_bindings_for_draft(
+        WorkflowAgentPublishService.sync_agent_bindings_for_draft(
             session=cast(Session, db.session),
             draft_workflow=workflow,
             account_id=account.id,