feat(openapi): distinguish expired OAuth bearer from invalid token

Previously an expired OAuth bearer and an unknown/invalid one both
surfaced as an indistinguishable generic 401 (and an invalid token
actually leaked a 500), so a client could not tell "session expired,
re-authenticate" apart from "never authenticated."

The resolver now raises a distinct TokenExpiredError for expired DB
rows and records a separate `expired` negative-cache marker, so a
retry within the negative-cache TTL still reports expiry instead of
collapsing into a generic miss. The auth pipeline maps the two domain
errors to unified OpenApiError responses: SessionExpired (code
`token_expired`) and InvalidBearer (code `unauthorized`), both 401.
This also fixes the latent 500 on invalid bearers.

The `token_expired` code is synced through the contract codegen into
the generated types/zod, and the difyctl error mapper branches the
401 on it. The CLI `expired_token` taxonomy member (RFC 8628
device-flow code expiry) is merged into `token_expired`; the RFC 8628
wire value is unchanged.

Closes WTA-1062

.agents/skills/component-refactoring/SKILL.md

@@ -1,440 +0,0 @@
----
-name: component-refactoring
-description: Refactor high-complexity React components in Dify frontend. Use when `pnpm analyze-component --json` shows complexity > 50 or lineCount > 300, when the user asks for code splitting, hook extraction, or complexity reduction, or when `pnpm analyze-component` warns to refactor before testing; avoid for simple/well-structured components, third-party wrappers, or when the user explicitly wants testing without refactoring.
----
-
-# Dify Component Refactoring Skill
-
-Refactor high-complexity React components in the Dify frontend codebase with the patterns and workflow below.
-
-> **Complexity Threshold**: Components with complexity > 50 (measured by `pnpm analyze-component`) should be refactored before testing.
-
-## Quick Reference
-
-### Commands (run from `web/`)
-
-Use paths relative to `web/` (e.g., `app/components/...`).
-Use `refactor-component` for refactoring prompts and `analyze-component` for testing prompts and metrics.
-
-```bash
-cd web
-
-# Generate refactoring prompt
-pnpm refactor-component <path>
-
-# Output refactoring analysis as JSON
-pnpm refactor-component <path> --json
-
-# Generate testing prompt (after refactoring)
-pnpm analyze-component <path>
-
-# Output testing analysis as JSON
-pnpm analyze-component <path> --json
-```
-
-### Complexity Analysis
-
-```bash
-# Analyze component complexity
-pnpm analyze-component <path> --json
-
-# Key metrics to check:
-# - complexity: normalized score 0-100 (target < 50)
-# - maxComplexity: highest single function complexity
-# - lineCount: total lines (target < 300)
-```
-
-### Complexity Score Interpretation
-
-| Score | Level | Action |
-|-------|-------|--------|
-| 0-25 | 🟢 Simple | Ready for testing |
-| 26-50 | 🟡 Medium | Consider minor refactoring |
-| 51-75 | 🟠 Complex | **Refactor before testing** |
-| 76-100 | 🔴 Very Complex | **Must refactor** |
-
-## Core Refactoring Patterns
-
-### Pattern 1: Extract Custom Hooks
-
-**When**: Component has complex state management, multiple `useState`/`useEffect`, or business logic mixed with UI.
-
-**Dify Convention**: Place hooks in a `hooks/` subdirectory or alongside the component as `use-<feature>.ts`.
-
-```typescript
-// ❌ Before: Complex state logic in component
-function Configuration() {
-  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
-  const [datasetConfigs, setDatasetConfigs] = useState<DatasetConfigs>(...)
-  const [completionParams, setCompletionParams] = useState<FormValue>({})
-  
-  // 50+ lines of state management logic...
-  
-  return <div>...</div>
-}
-
-// ✅ After: Extract to custom hook
-// hooks/use-model-config.ts
-export const useModelConfig = (appId: string) => {
-  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
-  const [completionParams, setCompletionParams] = useState<FormValue>({})
-  
-  // Related state management logic here
-  
-  return { modelConfig, setModelConfig, completionParams, setCompletionParams }
-}
-
-// Component becomes cleaner
-function Configuration() {
-  const { modelConfig, setModelConfig } = useModelConfig(appId)
-  return <div>...</div>
-}
-```
-
-**Dify Examples**:
-- `web/app/components/app/configuration/hooks/use-advanced-prompt-config.ts`
-- `web/app/components/app/configuration/debug/hooks.tsx`
-- `web/app/components/workflow/hooks/use-workflow.ts`
-
-### Pattern 2: Extract Sub-Components
-
-**When**: Single component has multiple UI sections, conditional rendering blocks, or repeated patterns.
-
-**Dify Convention**: Place sub-components in subdirectories or as separate files in the same directory.
-
-```typescript
-// ❌ Before: Monolithic JSX with multiple sections
-const AppInfo = () => {
-  return (
-    <div>
-      {/* 100 lines of header UI */}
-      {/* 100 lines of operations UI */}
-      {/* 100 lines of modals */}
-    </div>
-  )
-}
-
-// ✅ After: Split into focused components
-// app-info/
-//   ├── index.tsx           (orchestration only)
-//   ├── app-header.tsx      (header UI)
-//   ├── app-operations.tsx  (operations UI)
-//   └── app-modals.tsx      (modal management)
-
-const AppInfo = () => {
-  const { showModal, setShowModal } = useAppInfoModals()
-  
-  return (
-    <div>
-      <AppHeader appDetail={appDetail} />
-      <AppOperations onAction={handleAction} />
-      <AppModals show={showModal} onClose={() => setShowModal(null)} />
-    </div>
-  )
-}
-```
-
-**Dify Examples**:
-- `web/app/components/app/configuration/` directory structure
-- `web/app/components/workflow/nodes/` per-node organization
-
-### Pattern 3: Simplify Conditional Logic
-
-**When**: Deep nesting (> 3 levels), complex ternaries, or multiple `if/else` chains.
-
-```typescript
-// ❌ Before: Deeply nested conditionals
-const Template = useMemo(() => {
-  if (appDetail?.mode === AppModeEnum.CHAT) {
-    switch (locale) {
-      case LanguagesSupported[1]:
-        return <TemplateChatZh />
-      case LanguagesSupported[7]:
-        return <TemplateChatJa />
-      default:
-        return <TemplateChatEn />
-    }
-  }
-  if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) {
-    // Another 15 lines...
-  }
-  // More conditions...
-}, [appDetail, locale])
-
-// ✅ After: Use lookup tables + early returns
-const TEMPLATE_MAP = {
-  [AppModeEnum.CHAT]: {
-    [LanguagesSupported[1]]: TemplateChatZh,
-    [LanguagesSupported[7]]: TemplateChatJa,
-    default: TemplateChatEn,
-  },
-  [AppModeEnum.ADVANCED_CHAT]: {
-    [LanguagesSupported[1]]: TemplateAdvancedChatZh,
-    // ...
-  },
-}
-
-const Template = useMemo(() => {
-  const modeTemplates = TEMPLATE_MAP[appDetail?.mode]
-  if (!modeTemplates) return null
-  
-  const TemplateComponent = modeTemplates[locale] || modeTemplates.default
-  return <TemplateComponent appDetail={appDetail} />
-}, [appDetail, locale])
-```
-
-### Pattern 4: Extract API/Data Logic
-
-**When**: Component directly handles API calls, data transformation, or complex async operations.
-
-**Dify Convention**:
-- This skill is for component decomposition, not query/mutation design.
-- Do not introduce deprecated `useInvalid` / `useReset`.
-- Do not add thin passthrough `useQuery` wrappers during refactoring; only extract a custom hook when it truly orchestrates multiple queries/mutations or shared derived state.
-
-**Dify Examples**:
-- `web/service/use-workflow.ts`
-- `web/service/use-common.ts`
-- `web/service/knowledge/use-dataset.ts`
-- `web/service/knowledge/use-document.ts`
-
-### Pattern 5: Extract Modal/Dialog Management
-
-**When**: Component manages multiple modals with complex open/close states.
-
-**Dify Convention**: Modals should be extracted with their state management.
-
-```typescript
-// ❌ Before: Multiple modal states in component
-const AppInfo = () => {
-  const [showEditModal, setShowEditModal] = useState(false)
-  const [showDuplicateModal, setShowDuplicateModal] = useState(false)
-  const [showConfirmDelete, setShowConfirmDelete] = useState(false)
-  const [showSwitchModal, setShowSwitchModal] = useState(false)
-  const [showImportDSLModal, setShowImportDSLModal] = useState(false)
-  // 5+ more modal states...
-}
-
-// ✅ After: Extract to modal management hook
-type ModalType = 'edit' | 'duplicate' | 'delete' | 'switch' | 'import' | null
-
-const useAppInfoModals = () => {
-  const [activeModal, setActiveModal] = useState<ModalType>(null)
-  
-  const openModal = useCallback((type: ModalType) => setActiveModal(type), [])
-  const closeModal = useCallback(() => setActiveModal(null), [])
-  
-  return {
-    activeModal,
-    openModal,
-    closeModal,
-    isOpen: (type: ModalType) => activeModal === type,
-  }
-}
-```
-
-### Pattern 6: Extract Form Logic
-
-**When**: Complex form validation, submission handling, or field transformation.
-
-**Dify Convention**: Use `@tanstack/react-form` patterns from `web/app/components/base/form/`.
-
-```typescript
-// ✅ Use existing form infrastructure
-import { useAppForm } from '@/app/components/base/form'
-
-const ConfigForm = () => {
-  const form = useAppForm({
-    defaultValues: { name: '', description: '' },
-    onSubmit: handleSubmit,
-  })
-  
-  return <form.Provider>...</form.Provider>
-}
-```
-
-## Dify-Specific Refactoring Guidelines
-
-### 1. Context Provider Extraction
-
-**When**: Component provides complex context values with multiple states.
-
-```typescript
-// ❌ Before: Large context value object
-const value = {
-  appId, isAPIKeySet, isTrailFinished, mode, modelModeType,
-  promptMode, isAdvancedMode, isAgent, isOpenAI, isFunctionCall,
-  // 50+ more properties...
-}
-return <ConfigContext.Provider value={value}>...</ConfigContext.Provider>
-
-// ✅ After: Split into domain-specific contexts
-<ModelConfigProvider value={modelConfigValue}>
-  <DatasetConfigProvider value={datasetConfigValue}>
-    <UIConfigProvider value={uiConfigValue}>
-      {children}
-    </UIConfigProvider>
-  </DatasetConfigProvider>
-</ModelConfigProvider>
-```
-
-**Dify Reference**: `web/context/` directory structure
-
-### 2. Workflow Node Components
-
-**When**: Refactoring workflow node components (`web/app/components/workflow/nodes/`).
-
-**Conventions**:
-- Keep node logic in `use-interactions.ts`
-- Extract panel UI to separate files
-- Use `_base` components for common patterns
-
-```
-nodes/<node-type>/
-  ├── index.tsx              # Node registration
-  ├── node.tsx               # Node visual component
-  ├── panel.tsx              # Configuration panel
-  ├── use-interactions.ts    # Node-specific hooks
-  └── types.ts               # Type definitions
-```
-
-### 3. Configuration Components
-
-**When**: Refactoring app configuration components.
-
-**Conventions**:
-- Separate config sections into subdirectories
-- Use existing patterns from `web/app/components/app/configuration/`
-- Keep feature toggles in dedicated components
-
-### 4. Tool/Plugin Components
-
-**When**: Refactoring tool-related components (`web/app/components/tools/`).
-
-**Conventions**:
-- Follow existing modal patterns
-- Use service hooks from `web/service/use-tools.ts`
-- Keep provider-specific logic isolated
-
-## Refactoring Workflow
-
-### Step 1: Generate Refactoring Prompt
-
-```bash
-pnpm refactor-component <path>
-```
-
-This command will:
-- Analyze component complexity and features
-- Identify specific refactoring actions needed
-- Generate a prompt for AI assistant (auto-copied to clipboard on macOS)
-- Provide detailed requirements based on detected patterns
-
-### Step 2: Analyze Details
-
-```bash
-pnpm analyze-component <path> --json
-```
-
-Identify:
-- Total complexity score
-- Max function complexity
-- Line count
-- Features detected (state, effects, API, etc.)
-
-### Step 3: Plan
-
-Create a refactoring plan based on detected features:
-
-| Detected Feature | Refactoring Action |
-|------------------|-------------------|
-| `hasState: true` + `hasEffects: true` | Extract custom hook |
-| `hasAPI: true` | Extract data/service hook |
-| `hasEvents: true` (many) | Extract event handlers |
-| `lineCount > 300` | Split into sub-components |
-| `maxComplexity > 50` | Simplify conditional logic |
-
-### Step 4: Execute Incrementally
-
-1. **Extract one piece at a time**
-2. **Run lint, type-check, and tests after each extraction**
-3. **Verify functionality before next step**
-
-```
-For each extraction:
-  ┌────────────────────────────────────────┐
-  │ 1. Extract code                        │
-  │ 2. Run: pnpm lint:fix                  │
-  │ 3. Run: pnpm type-check                │
-  │ 4. Run: pnpm test                      │
-  │ 5. Test functionality manually         │
-  │ 6. PASS? → Next extraction             │
-  │    FAIL? → Fix before continuing       │
-  └────────────────────────────────────────┘
-```
-
-### Step 5: Verify
-
-After refactoring:
-
-```bash
-# Re-run refactor command to verify improvements
-pnpm refactor-component <path>
-
-# If complexity < 25 and lines < 200, you'll see:
-# ✅ COMPONENT IS WELL-STRUCTURED
-
-# For detailed metrics:
-pnpm analyze-component <path> --json
-
-# Target metrics:
-# - complexity < 50
-# - lineCount < 300
-# - maxComplexity < 30
-```
-
-## Common Mistakes to Avoid
-
-### ❌ Over-Engineering
-
-```typescript
-// ❌ Too many tiny hooks
-const useButtonText = () => useState('Click')
-const useButtonDisabled = () => useState(false)
-const useButtonLoading = () => useState(false)
-
-// ✅ Cohesive hook with related state
-const useButtonState = () => {
-  const [text, setText] = useState('Click')
-  const [disabled, setDisabled] = useState(false)
-  const [loading, setLoading] = useState(false)
-  return { text, setText, disabled, setDisabled, loading, setLoading }
-}
-```
-
-### ❌ Breaking Existing Patterns
-
-- Follow existing directory structures
-- Maintain naming conventions
-- Preserve export patterns for compatibility
-
-### ❌ Premature Abstraction
-
-- Only extract when there's clear complexity benefit
-- Don't create abstractions for single-use code
-- Keep refactored code in the same domain area
-
-## References
-
-### Dify Codebase Examples
-
-- **Hook extraction**: `web/app/components/app/configuration/hooks/`
-- **Component splitting**: `web/app/components/app/configuration/`
-- **Service hooks**: `web/service/use-*.ts`
-- **Workflow patterns**: `web/app/components/workflow/hooks/`
-- **Form patterns**: `web/app/components/base/form/`
-
-### Related Skills
-
-- `frontend-testing` - For testing refactored components
-- `web/docs/test.md` - Testing specification

.agents/skills/component-refactoring/references/complexity-patterns.md

@@ -1,495 +0,0 @@
-# Complexity Reduction Patterns
-
-This document provides patterns for reducing cognitive complexity in Dify React components.
-
-## Understanding Complexity
-
-### SonarJS Cognitive Complexity
-
-The `pnpm analyze-component` tool uses SonarJS cognitive complexity metrics:
-
-- **Total Complexity**: Sum of all functions' complexity in the file
-- **Max Complexity**: Highest single function complexity
-
-### What Increases Complexity
-
-| Pattern | Complexity Impact |
-|---------|-------------------|
-| `if/else` | +1 per branch |
-| Nested conditions | +1 per nesting level |
-| `switch/case` | +1 per case |
-| `for/while/do` | +1 per loop |
-| `&&`/`||` chains | +1 per operator |
-| Nested callbacks | +1 per nesting level |
-| `try/catch` | +1 per catch |
-| Ternary expressions | +1 per nesting |
-
-## Pattern 1: Replace Conditionals with Lookup Tables
-
-**Before** (complexity: ~15):
-
-```typescript
-const Template = useMemo(() => {
-  if (appDetail?.mode === AppModeEnum.CHAT) {
-    switch (locale) {
-      case LanguagesSupported[1]:
-        return <TemplateChatZh appDetail={appDetail} />
-      case LanguagesSupported[7]:
-        return <TemplateChatJa appDetail={appDetail} />
-      default:
-        return <TemplateChatEn appDetail={appDetail} />
-    }
-  }
-  if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) {
-    switch (locale) {
-      case LanguagesSupported[1]:
-        return <TemplateAdvancedChatZh appDetail={appDetail} />
-      case LanguagesSupported[7]:
-        return <TemplateAdvancedChatJa appDetail={appDetail} />
-      default:
-        return <TemplateAdvancedChatEn appDetail={appDetail} />
-    }
-  }
-  if (appDetail?.mode === AppModeEnum.WORKFLOW) {
-    // Similar pattern...
-  }
-  return null
-}, [appDetail, locale])
-```
-
-**After** (complexity: ~3):
-
-```typescript
-import type { ComponentType } from 'react'
-
-// Define lookup table outside component
-const TEMPLATE_MAP: Record<AppModeEnum, Record<string, ComponentType<TemplateProps>>> = {
-  [AppModeEnum.CHAT]: {
-    [LanguagesSupported[1]]: TemplateChatZh,
-    [LanguagesSupported[7]]: TemplateChatJa,
-    default: TemplateChatEn,
-  },
-  [AppModeEnum.ADVANCED_CHAT]: {
-    [LanguagesSupported[1]]: TemplateAdvancedChatZh,
-    [LanguagesSupported[7]]: TemplateAdvancedChatJa,
-    default: TemplateAdvancedChatEn,
-  },
-  [AppModeEnum.WORKFLOW]: {
-    [LanguagesSupported[1]]: TemplateWorkflowZh,
-    [LanguagesSupported[7]]: TemplateWorkflowJa,
-    default: TemplateWorkflowEn,
-  },
-  // ...
-}
-
-// Clean component logic
-const Template = useMemo(() => {
-  if (!appDetail?.mode) return null
-  
-  const templates = TEMPLATE_MAP[appDetail.mode]
-  if (!templates) return null
-  
-  const TemplateComponent = templates[locale] ?? templates.default
-  return <TemplateComponent appDetail={appDetail} />
-}, [appDetail, locale])
-```
-
-## Pattern 2: Use Early Returns
-
-**Before** (complexity: ~10):
-
-```typescript
-const handleSubmit = () => {
-  if (isValid) {
-    if (hasChanges) {
-      if (isConnected) {
-        submitData()
-      } else {
-        showConnectionError()
-      }
-    } else {
-      showNoChangesMessage()
-    }
-  } else {
-    showValidationError()
-  }
-}
-```
-
-**After** (complexity: ~4):
-
-```typescript
-const handleSubmit = () => {
-  if (!isValid) {
-    showValidationError()
-    return
-  }
-  
-  if (!hasChanges) {
-    showNoChangesMessage()
-    return
-  }
-  
-  if (!isConnected) {
-    showConnectionError()
-    return
-  }
-  
-  submitData()
-}
-```
-
-## Pattern 3: Extract Complex Conditions
-
-**Before** (complexity: high):
-
-```typescript
-const canPublish = (() => {
-  if (mode !== AppModeEnum.COMPLETION) {
-    if (!isAdvancedMode)
-      return true
-
-    if (modelModeType === ModelModeType.completion) {
-      if (!hasSetBlockStatus.history || !hasSetBlockStatus.query)
-        return false
-      return true
-    }
-    return true
-  }
-  return !promptEmpty
-})()
-```
-
-**After** (complexity: lower):
-
-```typescript
-// Extract to named functions
-const canPublishInCompletionMode = () => !promptEmpty
-
-const canPublishInChatMode = () => {
-  if (!isAdvancedMode) return true
-  if (modelModeType !== ModelModeType.completion) return true
-  return hasSetBlockStatus.history && hasSetBlockStatus.query
-}
-
-// Clean main logic
-const canPublish = mode === AppModeEnum.COMPLETION
-  ? canPublishInCompletionMode()
-  : canPublishInChatMode()
-```
-
-## Pattern 4: Replace Chained Ternaries
-
-**Before** (complexity: ~5):
-
-```typescript
-const statusText = serverActivated
-  ? t('status.running')
-  : serverPublished
-    ? t('status.inactive')
-    : appUnpublished
-      ? t('status.unpublished')
-      : t('status.notConfigured')
-```
-
-**After** (complexity: ~2):
-
-```typescript
-const getStatusText = () => {
-  if (serverActivated) return t('status.running')
-  if (serverPublished) return t('status.inactive')
-  if (appUnpublished) return t('status.unpublished')
-  return t('status.notConfigured')
-}
-
-const statusText = getStatusText()
-```
-
-Or use lookup:
-
-```typescript
-const STATUS_TEXT_MAP = {
-  running: 'status.running',
-  inactive: 'status.inactive',
-  unpublished: 'status.unpublished',
-  notConfigured: 'status.notConfigured',
-} as const
-
-const getStatusKey = (): keyof typeof STATUS_TEXT_MAP => {
-  if (serverActivated) return 'running'
-  if (serverPublished) return 'inactive'
-  if (appUnpublished) return 'unpublished'
-  return 'notConfigured'
-}
-
-const statusText = t(STATUS_TEXT_MAP[getStatusKey()])
-```
-
-## Pattern 5: Flatten Nested Loops
-
-**Before** (complexity: high):
-
-```typescript
-const processData = (items: Item[]) => {
-  const results: ProcessedItem[] = []
-  
-  for (const item of items) {
-    if (item.isValid) {
-      for (const child of item.children) {
-        if (child.isActive) {
-          for (const prop of child.properties) {
-            if (prop.value !== null) {
-              results.push({
-                itemId: item.id,
-                childId: child.id,
-                propValue: prop.value,
-              })
-            }
-          }
-        }
-      }
-    }
-  }
-  
-  return results
-}
-```
-
-**After** (complexity: lower):
-
-```typescript
-// Use functional approach
-const processData = (items: Item[]) => {
-  return items
-    .filter(item => item.isValid)
-    .flatMap(item =>
-      item.children
-        .filter(child => child.isActive)
-        .flatMap(child =>
-          child.properties
-            .filter(prop => prop.value !== null)
-            .map(prop => ({
-              itemId: item.id,
-              childId: child.id,
-              propValue: prop.value,
-            }))
-        )
-    )
-}
-```
-
-## Pattern 6: Extract Event Handler Logic
-
-**Before** (complexity: high in component):
-
-```typescript
-const Component = () => {
-  const handleSelect = (data: DataSet[]) => {
-    if (isEqual(data.map(item => item.id), dataSets.map(item => item.id))) {
-      hideSelectDataSet()
-      return
-    }
-
-    formattingChangedDispatcher()
-    let newDatasets = data
-    if (data.find(item => !item.name)) {
-      const newSelected = produce(data, (draft) => {
-        data.forEach((item, index) => {
-          if (!item.name) {
-            const newItem = dataSets.find(i => i.id === item.id)
-            if (newItem)
-              draft[index] = newItem
-          }
-        })
-      })
-      setDataSets(newSelected)
-      newDatasets = newSelected
-    }
-    else {
-      setDataSets(data)
-    }
-    hideSelectDataSet()
-    
-    // 40 more lines of logic...
-  }
-  
-  return <div>...</div>
-}
-```
-
-**After** (complexity: lower):
-
-```typescript
-// Extract to hook or utility
-const useDatasetSelection = (dataSets: DataSet[], setDataSets: SetState<DataSet[]>) => {
-  const normalizeSelection = (data: DataSet[]) => {
-    const hasUnloadedItem = data.some(item => !item.name)
-    if (!hasUnloadedItem) return data
-    
-    return produce(data, (draft) => {
-      data.forEach((item, index) => {
-        if (!item.name) {
-          const existing = dataSets.find(i => i.id === item.id)
-          if (existing) draft[index] = existing
-        }
-      })
-    })
-  }
-  
-  const hasSelectionChanged = (newData: DataSet[]) => {
-    return !isEqual(
-      newData.map(item => item.id),
-      dataSets.map(item => item.id)
-    )
-  }
-  
-  return { normalizeSelection, hasSelectionChanged }
-}
-
-// Component becomes cleaner
-const Component = () => {
-  const { normalizeSelection, hasSelectionChanged } = useDatasetSelection(dataSets, setDataSets)
-  
-  const handleSelect = (data: DataSet[]) => {
-    if (!hasSelectionChanged(data)) {
-      hideSelectDataSet()
-      return
-    }
-    
-    formattingChangedDispatcher()
-    const normalized = normalizeSelection(data)
-    setDataSets(normalized)
-    hideSelectDataSet()
-  }
-  
-  return <div>...</div>
-}
-```
-
-## Pattern 7: Reduce Boolean Logic Complexity
-
-**Before** (complexity: ~8):
-
-```typescript
-const toggleDisabled = hasInsufficientPermissions
-  || appUnpublished
-  || missingStartNode
-  || triggerModeDisabled
-  || (isAdvancedApp && !currentWorkflow?.graph)
-  || (isBasicApp && !basicAppConfig.updated_at)
-```
-
-**After** (complexity: ~3):
-
-```typescript
-// Extract meaningful boolean functions
-const isAppReady = () => {
-  if (isAdvancedApp) return !!currentWorkflow?.graph
-  return !!basicAppConfig.updated_at
-}
-
-const hasRequiredPermissions = () => {
-  return isCurrentWorkspaceEditor && !hasInsufficientPermissions
-}
-
-const canToggle = () => {
-  if (!hasRequiredPermissions()) return false
-  if (!isAppReady()) return false
-  if (missingStartNode) return false
-  if (triggerModeDisabled) return false
-  return true
-}
-
-const toggleDisabled = !canToggle()
-```
-
-## Pattern 8: Simplify useMemo/useCallback Dependencies
-
-**Before** (complexity: multiple recalculations):
-
-```typescript
-const payload = useMemo(() => {
-  let parameters: Parameter[] = []
-  let outputParameters: OutputParameter[] = []
-
-  if (!published) {
-    parameters = (inputs || []).map((item) => ({
-      name: item.variable,
-      description: '',
-      form: 'llm',
-      required: item.required,
-      type: item.type,
-    }))
-    outputParameters = (outputs || []).map((item) => ({
-      name: item.variable,
-      description: '',
-      type: item.value_type,
-    }))
-  }
-  else if (detail && detail.tool) {
-    parameters = (inputs || []).map((item) => ({
-      // Complex transformation...
-    }))
-    outputParameters = (outputs || []).map((item) => ({
-      // Complex transformation...
-    }))
-  }
-  
-  return {
-    icon: detail?.icon || icon,
-    label: detail?.label || name,
-    // ...more fields
-  }
-}, [detail, published, workflowAppId, icon, name, description, inputs, outputs])
-```
-
-**After** (complexity: separated concerns):
-
-```typescript
-// Separate transformations
-const useParameterTransform = (inputs: InputVar[], detail?: ToolDetail, published?: boolean) => {
-  return useMemo(() => {
-    if (!published) {
-      return inputs.map(item => ({
-        name: item.variable,
-        description: '',
-        form: 'llm',
-        required: item.required,
-        type: item.type,
-      }))
-    }
-    
-    if (!detail?.tool) return []
-    
-    return inputs.map(item => ({
-      name: item.variable,
-      required: item.required,
-      type: item.type === 'paragraph' ? 'string' : item.type,
-      description: detail.tool.parameters.find(p => p.name === item.variable)?.llm_description || '',
-      form: detail.tool.parameters.find(p => p.name === item.variable)?.form || 'llm',
-    }))
-  }, [inputs, detail, published])
-}
-
-// Component uses hook
-const parameters = useParameterTransform(inputs, detail, published)
-const outputParameters = useOutputTransform(outputs, detail, published)
-
-const payload = useMemo(() => ({
-  icon: detail?.icon || icon,
-  label: detail?.label || name,
-  parameters,
-  outputParameters,
-  // ...
-}), [detail, icon, name, parameters, outputParameters])
-```
-
-## Target Metrics After Refactoring
-
-| Metric | Target |
-|--------|--------|
-| Total Complexity | < 50 |
-| Max Function Complexity | < 30 |
-| Function Length | < 30 lines |
-| Nesting Depth | ≤ 3 levels |
-| Conditional Chains | ≤ 3 conditions |

.agents/skills/component-refactoring/references/component-splitting.md

@@ -1,477 +0,0 @@
-# Component Splitting Patterns
-
-This document provides detailed guidance on splitting large components into smaller, focused components in Dify.
-
-## When to Split Components
-
-Split a component when you identify:
-
-1. **Multiple UI sections** - Distinct visual areas with minimal coupling that can be composed independently
-1. **Conditional rendering blocks** - Large `{condition && <JSX />}` blocks
-1. **Repeated patterns** - Similar UI structures used multiple times
-1. **300+ lines** - Component exceeds manageable size
-1. **Modal clusters** - Multiple modals rendered in one component
-
-## Splitting Strategies
-
-### Strategy 1: Section-Based Splitting
-
-Identify visual sections and extract each as a component.
-
-```typescript
-// ❌ Before: Monolithic component (500+ lines)
-const ConfigurationPage = () => {
-  return (
-    <div>
-      {/* Header Section - 50 lines */}
-      <div className="header">
-        <h1>{t('configuration.title')}</h1>
-        <div className="actions">
-          {isAdvancedMode && <Badge>Advanced</Badge>}
-          <ModelParameterModal ... />
-          <AppPublisher ... />
-        </div>
-      </div>
-      
-      {/* Config Section - 200 lines */}
-      <div className="config">
-        <Config />
-      </div>
-      
-      {/* Debug Section - 150 lines */}
-      <div className="debug">
-        <Debug ... />
-      </div>
-      
-      {/* Modals Section - 100 lines */}
-      {showSelectDataSet && <SelectDataSet ... />}
-      {showHistoryModal && <EditHistoryModal ... />}
-      {showUseGPT4Confirm && <Confirm ... />}
-    </div>
-  )
-}
-
-// ✅ After: Split into focused components
-// configuration/
-//   ├── index.tsx              (orchestration)
-//   ├── configuration-header.tsx
-//   ├── configuration-content.tsx
-//   ├── configuration-debug.tsx
-//   └── configuration-modals.tsx
-
-// configuration-header.tsx
-interface ConfigurationHeaderProps {
-  isAdvancedMode: boolean
-  onPublish: () => void
-}
-
-function ConfigurationHeader({
-  isAdvancedMode,
-  onPublish,
-}: ConfigurationHeaderProps) {
-  const { t } = useTranslation()
-  
-  return (
-    <div className="header">
-      <h1>{t('configuration.title')}</h1>
-      <div className="actions">
-        {isAdvancedMode && <Badge>Advanced</Badge>}
-        <ModelParameterModal ... />
-        <AppPublisher onPublish={onPublish} />
-      </div>
-    </div>
-  )
-}
-
-// index.tsx (orchestration only)
-const ConfigurationPage = () => {
-  const { modelConfig, setModelConfig } = useModelConfig()
-  const { activeModal, openModal, closeModal } = useModalState()
-  
-  return (
-    <div>
-      <ConfigurationHeader
-        isAdvancedMode={isAdvancedMode}
-        onPublish={handlePublish}
-      />
-      <ConfigurationContent
-        modelConfig={modelConfig}
-        onConfigChange={setModelConfig}
-      />
-      {!isMobile && (
-        <ConfigurationDebug
-          inputs={inputs}
-          onSetting={handleSetting}
-        />
-      )}
-      <ConfigurationModals
-        activeModal={activeModal}
-        onClose={closeModal}
-      />
-    </div>
-  )
-}
-```
-
-### Strategy 2: Conditional Block Extraction
-
-Extract large conditional rendering blocks.
-
-```typescript
-// ❌ Before: Large conditional blocks
-const AppInfo = () => {
-  return (
-    <div>
-      {expand ? (
-        <div className="expanded">
-          {/* 100 lines of expanded view */}
-        </div>
-      ) : (
-        <div className="collapsed">
-          {/* 50 lines of collapsed view */}
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ✅ After: Separate view components
-function AppInfoExpanded({ appDetail, onAction }: AppInfoViewProps) {
-  return (
-    <div className="expanded">
-      {/* Clean, focused expanded view */}
-    </div>
-  )
-}
-
-function AppInfoCollapsed({ appDetail, onAction }: AppInfoViewProps) {
-  return (
-    <div className="collapsed">
-      {/* Clean, focused collapsed view */}
-    </div>
-  )
-}
-
-const AppInfo = () => {
-  return (
-    <div>
-      {expand
-        ? <AppInfoExpanded appDetail={appDetail} onAction={handleAction} />
-        : <AppInfoCollapsed appDetail={appDetail} onAction={handleAction} />
-      }
-    </div>
-  )
-}
-```
-
-### Strategy 3: Modal Extraction
-
-Extract modals with their trigger logic.
-
-```typescript
-// ❌ Before: Multiple modals in one component
-const AppInfo = () => {
-  const [showEdit, setShowEdit] = useState(false)
-  const [showDuplicate, setShowDuplicate] = useState(false)
-  const [showDelete, setShowDelete] = useState(false)
-  const [showSwitch, setShowSwitch] = useState(false)
-  
-  const onEdit = async (data) => { /* 20 lines */ }
-  const onDuplicate = async (data) => { /* 20 lines */ }
-  const onDelete = async () => { /* 15 lines */ }
-  
-  return (
-    <div>
-      {/* Main content */}
-      
-      {showEdit && <EditModal onConfirm={onEdit} onClose={() => setShowEdit(false)} />}
-      {showDuplicate && <DuplicateModal onConfirm={onDuplicate} onClose={() => setShowDuplicate(false)} />}
-      {showDelete && <DeleteConfirm onConfirm={onDelete} onClose={() => setShowDelete(false)} />}
-      {showSwitch && <SwitchModal ... />}
-    </div>
-  )
-}
-
-// ✅ After: Modal manager component
-// app-info-modals.tsx
-type ModalType = 'edit' | 'duplicate' | 'delete' | 'switch' | null
-
-interface AppInfoModalsProps {
-  appDetail: AppDetail
-  activeModal: ModalType
-  onClose: () => void
-  onSuccess: () => void
-}
-
-function AppInfoModals({
-  appDetail,
-  activeModal,
-  onClose,
-  onSuccess,
-}: AppInfoModalsProps) {
-  const handleEdit = async (data) => { /* logic */ }
-  const handleDuplicate = async (data) => { /* logic */ }
-  const handleDelete = async () => { /* logic */ }
-
-  return (
-    <>
-      {activeModal === 'edit' && (
-        <EditModal
-          appDetail={appDetail}
-          onConfirm={handleEdit}
-          onClose={onClose}
-        />
-      )}
-      {activeModal === 'duplicate' && (
-        <DuplicateModal
-          appDetail={appDetail}
-          onConfirm={handleDuplicate}
-          onClose={onClose}
-        />
-      )}
-      {activeModal === 'delete' && (
-        <DeleteConfirm
-          onConfirm={handleDelete}
-          onClose={onClose}
-        />
-      )}
-      {activeModal === 'switch' && (
-        <SwitchModal
-          appDetail={appDetail}
-          onClose={onClose}
-        />
-      )}
-    </>
-  )
-}
-
-// Parent component
-const AppInfo = () => {
-  const { activeModal, openModal, closeModal } = useModalState()
-  
-  return (
-    <div>
-      {/* Main content with openModal triggers */}
-      <Button onClick={() => openModal('edit')}>Edit</Button>
-      
-      <AppInfoModals
-        appDetail={appDetail}
-        activeModal={activeModal}
-        onClose={closeModal}
-        onSuccess={handleSuccess}
-      />
-    </div>
-  )
-}
-```
-
-### Strategy 4: List Item Extraction
-
-Extract repeated item rendering.
-
-```typescript
-// ❌ Before: Inline item rendering
-const OperationsList = () => {
-  return (
-    <div>
-      {operations.map(op => (
-        <div key={op.id} className="operation-item">
-          <span className="icon">{op.icon}</span>
-          <span className="title">{op.title}</span>
-          <span className="description">{op.description}</span>
-          <button onClick={() => op.onClick()}>
-            {op.actionLabel}
-          </button>
-          {op.badge && <Badge>{op.badge}</Badge>}
-          {/* More complex rendering... */}
-        </div>
-      ))}
-    </div>
-  )
-}
-
-// ✅ After: Extracted item component
-interface OperationItemProps {
-  operation: Operation
-  onAction: (id: string) => void
-}
-
-function OperationItem({ operation, onAction }: OperationItemProps) {
-  return (
-    <div className="operation-item">
-      <span className="icon">{operation.icon}</span>
-      <span className="title">{operation.title}</span>
-      <span className="description">{operation.description}</span>
-      <button onClick={() => onAction(operation.id)}>
-        {operation.actionLabel}
-      </button>
-      {operation.badge && <Badge>{operation.badge}</Badge>}
-    </div>
-  )
-}
-
-const OperationsList = () => {
-  const handleAction = useCallback((id: string) => {
-    const op = operations.find(o => o.id === id)
-    op?.onClick()
-  }, [operations])
-
-  return (
-    <div>
-      {operations.map(op => (
-        <OperationItem
-          key={op.id}
-          operation={op}
-          onAction={handleAction}
-        />
-      ))}
-    </div>
-  )
-}
-```
-
-## Directory Structure Patterns
-
-### Pattern A: Flat Structure (Simple Components)
-
-For components with 2-3 sub-components:
-
-```
-component-name/
-  ├── index.tsx           # Main component
-  ├── sub-component-a.tsx
-  ├── sub-component-b.tsx
-  └── types.ts            # Shared types
-```
-
-### Pattern B: Nested Structure (Complex Components)
-
-For components with many sub-components:
-
-```
-component-name/
-  ├── index.tsx           # Main orchestration
-  ├── types.ts            # Shared types
-  ├── hooks/
-  │   ├── use-feature-a.ts
-  │   └── use-feature-b.ts
-  ├── components/
-  │   ├── header/
-  │   │   └── index.tsx
-  │   ├── content/
-  │   │   └── index.tsx
-  │   └── modals/
-  │       └── index.tsx
-  └── utils/
-      └── helpers.ts
-```
-
-### Pattern C: Feature-Based Structure (Dify Standard)
-
-Following Dify's existing patterns:
-
-```
-configuration/
-  ├── index.tsx           # Main page component
-  ├── base/               # Base/shared components
-  │   ├── feature-panel/
-  │   ├── group-name/
-  │   └── operation-btn/
-  ├── config/             # Config section
-  │   ├── index.tsx
-  │   ├── agent/
-  │   └── automatic/
-  ├── dataset-config/     # Dataset section
-  │   ├── index.tsx
-  │   ├── card-item/
-  │   └── params-config/
-  ├── debug/              # Debug section
-  │   ├── index.tsx
-  │   └── hooks.tsx
-  └── hooks/              # Shared hooks
-      └── use-advanced-prompt-config.ts
-```
-
-## Props Design
-
-### Minimal Props Principle
-
-Pass only what's needed:
-
-```typescript
-// ❌ Bad: Passing entire objects when only some fields needed
-<ConfigHeader appDetail={appDetail} modelConfig={modelConfig} />
-
-// ✅ Good: Destructure to minimum required
-<ConfigHeader
-  appName={appDetail.name}
-  isAdvancedMode={modelConfig.isAdvanced}
-  onPublish={handlePublish}
-/>
-```
-
-### Callback Props Pattern
-
-Use callbacks for child-to-parent communication:
-
-```typescript
-// Parent
-const Parent = () => {
-  const [value, setValue] = useState('')
-  
-  return (
-    <Child
-      value={value}
-      onChange={setValue}
-      onSubmit={handleSubmit}
-    />
-  )
-}
-
-// Child
-interface ChildProps {
-  value: string
-  onChange: (value: string) => void
-  onSubmit: () => void
-}
-
-function Child({ value, onChange, onSubmit }: ChildProps) {
-  return (
-    <div>
-      <input value={value} onChange={e => onChange(e.target.value)} />
-      <button onClick={onSubmit}>Submit</button>
-    </div>
-  )
-}
-```
-
-### Render Props for Flexibility
-
-When sub-components need parent context:
-
-```typescript
-interface ListProps<T> {
-  items: T[]
-  renderItem: (item: T, index: number) => React.ReactNode
-  renderEmpty?: () => React.ReactNode
-}
-
-function List<T>({ items, renderItem, renderEmpty }: ListProps<T>) {
-  if (items.length === 0 && renderEmpty) {
-    return <>{renderEmpty()}</>
-  }
-  
-  return (
-    <div>
-      {items.map((item, index) => renderItem(item, index))}
-    </div>
-  )
-}
-
-// Usage
-<List
-  items={operations}
-  renderItem={(op, i) => <OperationItem key={i} operation={op} />}
-  renderEmpty={() => <EmptyState message="No operations" />}
-/>
-```

.agents/skills/component-refactoring/references/hook-extraction.md

@@ -1,281 +0,0 @@
-# Hook Extraction Patterns
-
-This document provides detailed guidance on extracting custom hooks from complex components in Dify.
-
-## When to Extract Hooks
-
-Extract a custom hook when you identify:
-
-1. **Coupled state groups** - Multiple `useState` hooks that are always used together
-1. **Complex effects** - `useEffect` with multiple dependencies or cleanup logic
-1. **Business logic** - Data transformations, validations, or calculations
-1. **Reusable patterns** - Logic that appears in multiple components
-
-## Extraction Process
-
-### Step 1: Identify State Groups
-
-Look for state variables that are logically related:
-
-```typescript
-// ❌ These belong together - extract to hook
-const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
-const [completionParams, setCompletionParams] = useState<FormValue>({})
-const [modelModeType, setModelModeType] = useState<ModelModeType>(...)
-
-// These are model-related state that should be in useModelConfig()
-```
-
-### Step 2: Identify Related Effects
-
-Find effects that modify the grouped state:
-
-```typescript
-// ❌ These effects belong with the state above
-useEffect(() => {
-  if (hasFetchedDetail && !modelModeType) {
-    const mode = currModel?.model_properties.mode
-    if (mode) {
-      const newModelConfig = produce(modelConfig, (draft) => {
-        draft.mode = mode
-      })
-      setModelConfig(newModelConfig)
-    }
-  }
-}, [textGenerationModelList, hasFetchedDetail, modelModeType, currModel])
-```
-
-### Step 3: Create the Hook
-
-```typescript
-// hooks/use-model-config.ts
-import type { FormValue } from '@/app/components/header/account-setting/model-provider-page/declarations'
-import type { ModelConfig } from '@/models/debug'
-import { produce } from 'immer'
-import { useEffect, useState } from 'react'
-import { ModelModeType } from '@/types/app'
-
-interface UseModelConfigParams {
-  initialConfig?: Partial<ModelConfig>
-  currModel?: { model_properties?: { mode?: ModelModeType } }
-  hasFetchedDetail: boolean
-}
-
-interface UseModelConfigReturn {
-  modelConfig: ModelConfig
-  setModelConfig: (config: ModelConfig) => void
-  completionParams: FormValue
-  setCompletionParams: (params: FormValue) => void
-  modelModeType: ModelModeType
-}
-
-export const useModelConfig = ({
-  initialConfig,
-  currModel,
-  hasFetchedDetail,
-}: UseModelConfigParams): UseModelConfigReturn => {
-  const [modelConfig, setModelConfig] = useState<ModelConfig>({
-    provider: 'langgenius/openai/openai',
-    model_id: 'gpt-3.5-turbo',
-    mode: ModelModeType.unset,
-    // ... default values
-    ...initialConfig,
-  })
-  
-  const [completionParams, setCompletionParams] = useState<FormValue>({})
-  
-  const modelModeType = modelConfig.mode
-
-  // Fill old app data missing model mode
-  useEffect(() => {
-    if (hasFetchedDetail && !modelModeType) {
-      const mode = currModel?.model_properties?.mode
-      if (mode) {
-        setModelConfig(produce(modelConfig, (draft) => {
-          draft.mode = mode
-        }))
-      }
-    }
-  }, [hasFetchedDetail, modelModeType, currModel])
-
-  return {
-    modelConfig,
-    setModelConfig,
-    completionParams,
-    setCompletionParams,
-    modelModeType,
-  }
-}
-```
-
-### Step 4: Update Component
-
-```typescript
-// Before: 50+ lines of state management
-function Configuration() {
-  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
-  // ... lots of related state and effects
-}
-
-// After: Clean component
-function Configuration() {
-  const {
-    modelConfig,
-    setModelConfig,
-    completionParams,
-    setCompletionParams,
-    modelModeType,
-  } = useModelConfig({
-    currModel,
-    hasFetchedDetail,
-  })
-  
-  // Component now focuses on UI
-}
-```
-
-## Naming Conventions
-
-### Hook Names
-
-- Use `use` prefix: `useModelConfig`, `useDatasetConfig`
-- Be specific: `useAdvancedPromptConfig` not `usePrompt`
-- Include domain: `useWorkflowVariables`, `useMCPServer`
-
-### File Names
-
-- Kebab-case: `use-model-config.ts`
-- Place in `hooks/` subdirectory when multiple hooks exist
-- Place alongside component for single-use hooks
-
-### Return Type Names
-
-- Suffix with `Return`: `UseModelConfigReturn`
-- Suffix params with `Params`: `UseModelConfigParams`
-
-## Common Hook Patterns in Dify
-
-### 1. Data Fetching / Mutation Hooks
-
-When hook extraction touches query or mutation code, do not use this reference as the source of truth for data-layer patterns.
-
-- Do not introduce deprecated `useInvalid` / `useReset`.
-- Do not extract thin passthrough `useQuery` hooks; only extract orchestration hooks.
-
-### 2. Form State Hook
-
-```typescript
-// Pattern: Form state + validation + submission
-export const useConfigForm = (initialValues: ConfigFormValues) => {
-  const [values, setValues] = useState(initialValues)
-  const [errors, setErrors] = useState<Record<string, string>>({})
-  const [isSubmitting, setIsSubmitting] = useState(false)
-
-  const validate = useCallback(() => {
-    const newErrors: Record<string, string> = {}
-    if (!values.name) newErrors.name = 'Name is required'
-    setErrors(newErrors)
-    return Object.keys(newErrors).length === 0
-  }, [values])
-
-  const handleChange = useCallback((field: string, value: any) => {
-    setValues(prev => ({ ...prev, [field]: value }))
-  }, [])
-
-  const handleSubmit = useCallback(async (onSubmit: (values: ConfigFormValues) => Promise<void>) => {
-    if (!validate()) return
-    setIsSubmitting(true)
-    try {
-      await onSubmit(values)
-    } finally {
-      setIsSubmitting(false)
-    }
-  }, [values, validate])
-
-  return { values, errors, isSubmitting, handleChange, handleSubmit }
-}
-```
-
-### 3. Modal State Hook
-
-```typescript
-// Pattern: Multiple modal management
-type ModalType = 'edit' | 'delete' | 'duplicate' | null
-
-export const useModalState = () => {
-  const [activeModal, setActiveModal] = useState<ModalType>(null)
-  const [modalData, setModalData] = useState<any>(null)
-
-  const openModal = useCallback((type: ModalType, data?: any) => {
-    setActiveModal(type)
-    setModalData(data)
-  }, [])
-
-  const closeModal = useCallback(() => {
-    setActiveModal(null)
-    setModalData(null)
-  }, [])
-
-  return {
-    activeModal,
-    modalData,
-    openModal,
-    closeModal,
-    isOpen: useCallback((type: ModalType) => activeModal === type, [activeModal]),
-  }
-}
-```
-
-### 4. Toggle/Boolean Hook
-
-```typescript
-// Pattern: Boolean state with convenience methods
-export const useToggle = (initialValue = false) => {
-  const [value, setValue] = useState(initialValue)
-
-  const toggle = useCallback(() => setValue(v => !v), [])
-  const setTrue = useCallback(() => setValue(true), [])
-  const setFalse = useCallback(() => setValue(false), [])
-
-  return [value, { toggle, setTrue, setFalse, set: setValue }] as const
-}
-
-// Usage
-const [isExpanded, { toggle, setTrue: expand, setFalse: collapse }] = useToggle()
-```
-
-## Testing Extracted Hooks
-
-After extraction, test hooks in isolation:
-
-```typescript
-// use-model-config.spec.ts
-import { renderHook, act } from '@testing-library/react'
-import { useModelConfig } from './use-model-config'
-
-describe('useModelConfig', () => {
-  it('should initialize with default values', () => {
-    const { result } = renderHook(() => useModelConfig({
-      hasFetchedDetail: false,
-    }))
-
-    expect(result.current.modelConfig.provider).toBe('langgenius/openai/openai')
-    expect(result.current.modelModeType).toBe(ModelModeType.unset)
-  })
-
-  it('should update model config', () => {
-    const { result } = renderHook(() => useModelConfig({
-      hasFetchedDetail: true,
-    }))
-
-    act(() => {
-      result.current.setModelConfig({
-        ...result.current.modelConfig,
-        model_id: 'gpt-4',
-      })
-    })
-
-    expect(result.current.modelConfig.model_id).toBe('gpt-4')
-  })
-})
-```

.agents/skills/frontend-code-review/SKILL.md

@@ -25,6 +25,7 @@ Before reviewing, read the relevant local contracts:
 - `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md` when code uses or changes `@langgenius/dify-ui/*`.
 - `web/docs/overlay.md` when reviewing dialogs, drawers, popovers, tooltips, menus, selects, comboboxes, or other floating UI.
 - `web/docs/test.md` and the `frontend-testing` skill when reviewing tests or testability.
+- `karpathy-guidelines` for scope control and focused, verifiable changes.
 - `how-to-write-component` when reviewing React component structure, ownership, effects, query/mutation contracts, or memoization.
 
 For any UI, UX, or accessibility review, fetch the latest Web Interface Guidelines before finalizing findings. Treat them as a required baseline, not the complete source of accessibility truth:

.agents/skills/frontend-code-review/references/code-quality.md

@@ -29,10 +29,11 @@ Prefer:
 Flag:
 
 - New CSS modules or ad hoc CSS when Tailwind utilities and Dify tokens cover the need.
+- Component-level plain `.css` files or component CSS imported through `globals.css`; use scoped `*.module.css` only when Tailwind and component variants cannot express the style.
 - Generic color utilities where Dify semantic tokens exist.
 - Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or documented radius mappings exist.
 - `!` important modifiers or important CSS overrides without a narrow, documented reason.
-- Manual string concatenation for conditional classes.
+- Manual string concatenation, template strings, array `.join(' ')`, or custom ternaries for conditional or multi-line classes.
 - JS conditional class branches for primitive visual states already exposed by Dify UI/Base UI `data-*` selectors.
 - Incoming `className` placed before default classes in `cn(...)`, preventing call-site overrides.
 - Arbitrary z-index or one-off layering fixes on overlays.
@@ -59,8 +60,9 @@ Flag:
 Flag:
 
 - User-facing hardcoded strings in `web/`.
+- Added or renamed i18n keys that are not present in every supported locale file for the touched namespace.
 - Translation namespace drift, especially using unrelated module namespaces for local feature copy.
 - Generic button labels like `Continue` where the action is specific.
 - Error messages that state only the failure and not the next step.
 
-Use feature-local translation keys by default. Alias only when crossing namespaces.
+Use feature-local translation keys by default. Alias only when crossing namespaces. `pnpm i18n:check --file <name>` should pass for any touched translation namespace.

.agents/skills/frontend-code-review/references/component-architecture.md

@@ -18,6 +18,7 @@ Accept repeated TanStack Query calls in siblings when each component independent
 
 Flag:
 
+- React component files over 300 lines when the file mixes multiple responsibilities that can be split into focused colocated components, hooks, or utilities.
 - Shallow wrappers that only rename props or hide the real primitive.
 - Extra DOM wrappers that do not provide layout, semantics, accessibility, state ownership, or library integration.
 - Dialog/dropdown/popover hidden surfaces that obscure the parent flow when they should be extracted into a small local component.
@@ -29,6 +30,7 @@ Prefer colocated components split by actual data and state needs.
 
 Flag:
 
+- Refactors of existing navigation, sidebar, dropdown, webapp list, or app-switching UI that do not preserve behavior-sensitive interactions such as expand/collapse arrows, hover persistence, pin/delete controls, routing, keyboard/focus handling, or open-state ownership.
 - Components that mix data fetching, mutation side effects, popup state, form validation, layout, and row rendering without a clear owner.
 - Generic components with many boolean props that encode one feature's workflow.
 - A shared component that imports feature-specific copy, routes, or API contracts.
@@ -38,6 +40,8 @@ Flag:
 - A component that exposes controlled props but still keeps a competing private state for the same value.
 - A component that cannot render empty, loading, or missing optional API fields without caller-side preprocessing.
 
+When existing components already own interaction logic, prefer reusing or extending them. If a refactor is necessary, preserve the old interaction contract and add or update focused tests for changed behavior.
+
 ## Props And Types
 
 Flag:

.agents/skills/frontend-code-review/references/dify-ui.md

@@ -91,6 +91,7 @@ Use:
 
 Flag:
 
+- Manually recreating UI behavior or chrome already owned by `@langgenius/dify-ui/*` or `web/app/components/base/*`, such as buttons, inputs, toggle groups, popovers, dropdown menus, alert dialogs, switches, avatars, scroll areas, toasts, borders, focus states, disabled states, segmented controls, or existing feature components.
 - Styling a raw Base UI primitive directly in `web/` when a Dify UI primitive exists.
 - Wrapping a Dify UI primitive in a feature component that hides its label, error, disabled, or focus contract.
 - Replacing a semantic primitive with a generic `div` plus classes to match a screenshot.
@@ -121,3 +122,13 @@ Use `!` only for a tightly scoped compatibility override after confirming the pr
 ## Focus Details
 
 Flag focus rings attached to the wrong element. For example, Base UI `Slider.Thumb` focuses an internal `input[type=range]`, so the visible thumb wrapper needs `has-[:focus-visible]` rather than direct wrapper `focus-visible`.
+
+## Custom SVG Icons
+
+Flag:
+
+- New generated React icon components or JSON files under `web/app/components/base/icons/src/...` for custom SVG icons.
+- Custom SVG icons consumed outside the Tailwind `i-custom-*` icon class pipeline.
+- Generated `packages/iconify-collections/custom-*/icons.json` diffs where unrelated existing icons lost or changed intrinsic `width` or `height`.
+
+New custom SVG icons belong in `packages/iconify-collections/assets/...`. Regenerate with `pnpm --filter @dify/iconify-collections generate`, validate with `pnpm --filter @dify/iconify-collections check:dimensions`, and consume the generated icon with Tailwind `i-custom-*` classes.

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

@@ -102,11 +102,11 @@ describe('ComponentName', () => {
     })
   })
 
-  // Props tests (REQUIRED)
+  // Props tests (REQUIRED when props change observable behavior)
   describe('Props', () => {
-    it('should apply custom className', () => {
-      render(<Component className="custom" />)
-      expect(screen.getByRole('button')).toHaveClass('custom')
+    it('should disable the action when disabled', () => {
+      render(<Component disabled />)
+      expect(screen.getByRole('button')).toBeDisabled()
     })
   })
 
@@ -220,6 +220,7 @@ Every test should clearly separate:
 ### 2. Black-Box Testing
 
 - Test observable behavior, not implementation details
+- Test product contracts, not cosmetic implementation. Do not add or expand unit tests only to lock pure style classes, spacing, colors, backgrounds, or layout micro-adjustments. Cover visual-only fixes with browser/manual verification, screenshots, or E2E/visual checks when risk justifies it. Add unit tests only when the change affects user-observable behavior, accessibility semantics, state, data flow, routing, or a stable component API contract.
 - Use semantic queries (`getByRole` with accessible `name`, `getByLabelText`, `getByPlaceholderText`, `getByText`, and scoped `within(...)`)
 - Treat `getByTestId` as a last resort. If a control cannot be found by role/name, label, landmark, or dialog scope, fix the component accessibility first instead of adding or relying on `data-testid`.
 - Remove production `data-testid` attributes when semantic selectors can cover the behavior. Keep them only for non-visual mocked boundaries, editor/browser shims such as Monaco, canvas/chart output, or third-party widgets with no accessible DOM in the test environment.
@@ -273,7 +274,7 @@ it('should disable input when isReadOnly is true')
 ### Always Required (All Components)
 
 1. **Rendering**: Component renders without crashing
-1. **Props**: Required props, optional props, default values
+1. **Props**: Required props, optional props, default values that change observable behavior. Do not test pass-through styling props such as `className` unless they are an explicit, stable component API whose absence would break a real integration contract.
 1. **Edge Cases**: null, undefined, empty values, boundary conditions
 
 ### Conditional (When Present)

.agents/skills/how-to-write-component/SKILL.md

@@ -1,71 +1,125 @@
 ---
 name: how-to-write-component
-description: React/TypeScript component style guide. Use when writing, refactoring, or reviewing React components, especially around props typing, state boundaries, shared local state with Jotai atoms, API types, query/mutation contracts, navigation, memoization, wrappers, and empty-state handling.
+description: Use when writing, refactoring, or reviewing React/TypeScript components in Dify web, especially decisions about component ownership, props/types, URL/query state, Jotai state, async state, generated API contracts, queries/mutations, overlays, effects, navigation, performance, and empty states.
 ---
 
 # How To Write A Component
 
-Use this as the decision guide for React/TypeScript component structure. Existing code is reference material, not automatic precedent; when it conflicts with these rules, adapt the approach instead of reproducing the violation.
+Use this as the component decision guide for Dify web. Existing code is reference material, not automatic precedent; if touched code violates these rules, adapt it and fix equivalent patterns in the same feature branch.
+
+## First Decisions
+
+| Question | Default | Promote or extract only when |
+| --- | --- | --- |
+| Where should code live? | Keep it local to the feature workflow, route, or owner. | Multiple verticals need the same stable primitive. |
+| How should route/tab folders be named? | Match the current route segment, tab name, or user-visible surface. | Keep a historical or broader parent only when it still owns multiple surfaces. |
+| Who owns state, data, and handlers? | The lowest component that uses them. | A parent coordinates shared loading, errors, empty UI, selection, submission, navigation, or one consistent snapshot. |
+| Should this become Jotai state? | Keep synchronous UI/form state in component or DOM state. | Siblings need one source of truth, the value drives atoms, or scoped workflow state must survive hidden/unmounted steps. |
+| Should URL state enter Jotai? | Let Next.js route params and `nuqs` own URL state and updates. | Query atoms or shared derived atoms need a read-only bridge hydrated at the route/surface boundary. |
+| Should this query/mutation become an atom? | Use TanStack Query hooks at the lowest owner. | It reads atom state, feeds derived atoms, or participates in shared Jotai workflow orchestration. |
+| Should this be a helper/wrapper? | Prefer direct readable code at the use site. | The name captures a stable domain rule or the wrapper owns real behavior, validation, state, error handling, or semantics. |
+| Is an Effect needed? | No. Derive during render or handle the user action in the event handler. | It synchronizes with an external system such as browser APIs, subscriptions, timers, analytics, or imperative DOM/non-React widgets. |
 
 ## Core Defaults
 
-- Search before adding UI, hooks, helpers, or styling patterns. Reuse existing base components, feature components, hooks, utilities, and design styles when they fit.
-- Group code by feature workflow, route, or ownership area: components, hooks, local types, query helpers, atoms, constants, and small utilities should live near the code that changes with them.
-- Promote code to shared only when multiple verticals need the same stable primitive. Otherwise keep it local and compose shared primitives inside the owning feature.
-- Follow Dify's CSS-first Tailwind v4 contract from `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md`. Prefer design-system tokens, utilities, and radius mappings over generic Tailwind guidance.
+- Search before adding UI, hooks, helpers, query utilities, or styling patterns. Reuse existing base components, feature components, hooks, utilities, and design styles when they fit.
+- Follow Dify's CSS-first Tailwind v4 contract from `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md`. Prefer design-system tokens, utilities, and radius mappings over generic Tailwind choices.
+- Group feature code by workflow, route, or ownership area with route-aligned names: components, hooks, local types, query helpers, atoms, constants, tests, and small utilities should live near the code that changes with them.
+- Keep source/default selection, validation, dirty checks, and payload shaping close to the workflow that owns submit behavior. Do not hide flow-specific priority order, fallback behavior, or submit semantics in generic utilities.
+- Prefer direct conditionals for small branch-specific decisions, especially form source selection and request payload assembly.
+- Loading states for page sections, cards, lists, tables, forms, and drawers should be skeletons scoped to the content being loaded. Use spinners only for small inline busy indicators.
 
-## Ownership
+## Layout And Ownership
 
-- Put local state, queries, mutations, handlers, and derived UI data in the lowest component that uses them. Extract a purpose-built owner component only when the logic has no natural home.
-- Repeated TanStack query calls in sibling components are acceptable when each component independently consumes the data. Do not hoist a query only because it is duplicated; TanStack Query handles deduplication and cache sharing.
-- Hoist state, queries, or callbacks to a parent only when the parent consumes the data, coordinates shared loading/error/empty UI, needs one consistent snapshot, or owns a workflow spanning children.
-- Avoid prop drilling. One pass-through layer is acceptable; repeated forwarding means ownership should move down or into feature-scoped Jotai UI state. Keep server/cache state in query and API data flow.
-- Keep callbacks in a parent only for workflow coordination such as form submission, shared selection, batch behavior, or navigation. Otherwise let the child or row own its action.
-- Prefer uncontrolled DOM state and CSS variables before adding controlled props.
+- State-heavy wizards, drawers, modals, and secondary workflows can be a small feature surface: an entry file, one feature-local state file when Jotai is actually needed, and shallow `ui/` owners that match real visual regions.
+- The entry file handles route integration, provider wiring, close behavior, and surface mounting. The composition owner handles high-level workflow branching. The closest visual owner handles section branching.
+- When a page or tab maps to a route segment, name its feature folder after that route/tab surface instead of a stale parent grouping. Remove misleading intermediate folders when only one surface remains.
+- When a tab folder grows into several independent sections or action areas, split the first level by product/visual owners. Keep the root for the entry component and cross-owner state, colocate tests with the owner folder, and put truly shared local UI under a specifically named `components/` file.
+- Repeated TanStack query calls in sibling components are acceptable when each component independently consumes the data; TanStack Query deduplicates and shares cache.
+- Pass stable domain identity across boundaries. Do not forward derived presentation state when the receiver can derive it from its own data source.
+- A component that owns a visual surface should also own data access, loading, empty, and error states for content rendered inside it unless a parent truly coordinates that state.
+- Avoid prop drilling. One pass-through layer is acceptable; repeated forwarding means ownership should move down or into feature-scoped Jotai UI state. Keep server/cache state in Query and API flow.
+- Do not replace prop drilling with one large view-model hook threaded through section props. Move each hook, query, derived value, and handler to the concrete section that consumes it.
+- Keep callbacks in a parent only for workflow coordination such as form submission, shared selection, batch behavior, or navigation. Otherwise let the child, menu, or row own the action.
+
+## Feature-Scoped Jotai
+
+- A Jotai-backed feature has one feature-local state file for shared primitive atoms, query atoms, derived atoms, write-only actions, mutation atoms, submission orchestration, provider exports, and optional scope configuration.
+- Keep component-owned synchronous UI state local even inside Jotai features: dialog open flags, menus/popovers, confirmations, field drafts, and selected local options usually belong in component state.
+- Use uncontrolled `@langgenius/dify-ui/form` and `@langgenius/dify-ui/field` controls for edit/create forms whose fields are read only at submit time. Initialize query-backed defaults with `defaultValue` and keyed remounts.
+- Promote form state to atoms only when another component must react to in-progress values, a draft must survive unmount/remount in the scoped workflow, or multiple steps share the same editable draft before submit.
+- Treat `useParams`, route args, and `nuqs` query state as framework-owned state. When atom logic needs those values, hydrate primitive atoms at the route or surface boundary, such as with `useHydrateAtoms(..., { dangerouslyForceHydrate: true })`; keep URL updates in the route/query-state APIs instead of write atoms.
+- Within a route-owned feature, choose one source for route identity. If route params are bridged into feature atoms, use that bridge consistently for route-derived queries and actions instead of also threading the same route id through page, tab, and section props.
+- For async work tied to atom state, use `atomWithQuery` or `atomWithMutation`; write atoms should update only the inputs that drive those atoms. This applies to pure frontend async work as well as network requests, so do not hand-roll loading/error/in-flight state with `useState` or `useRef` for atom-orchestrated async behavior. For component-owned remote work, use `useQuery` or `useMutation` directly.
+- Row-local async state belongs to the row owner unless it participates in a shared Jotai workflow or needs atom-scoped reset semantics.
+- Leave query and mutation atoms unscoped so they keep shared QueryClient cache and invalidation behavior. Scope resettable primitives and explicit hydration tuples; scope a derived atom only when every dependency should be private to that surface.
+- For scoped primitives that are always hydrated by `ScopeProvider`, prefer `atomWithLazy<T>(() => { throw new Error(...) })` when consumers should see a non-null type.
+- Order state files by dependency graph: types/constants, primitives, query atoms, query-data derived atoms, business/readiness derived atoms, write actions, mutation atoms, submission orchestration, provider exports.
+- Name derived atoms as business facts and write atoms as user or workflow commands. Components should read or write the exact atom they need with `useAtomValue` or `useSetAtom`.
+- Menu/dialog `open` state usually stays local, but a scoped atom is acceptable when a composed menu plus secondary surface would otherwise pass confusing `open`/`onClose` props through unrelated layers. Scope that primitive with the surface instance so reset behavior stays local.
+- Keep independent dialog lifecycles separate. Avoid one discriminated "current action dialog" atom when dialogs have separate open state, loading guards, or reset behavior.
 
 ## Components, Props, And Types
 
 - Type component signatures directly; do not use `FC` or `React.FC`.
 - Prefer `function` for top-level components and module helpers. Use arrow functions for local callbacks, handlers, and lambda-style APIs.
 - Prefer named exports. Use default exports only where the framework requires them, such as Next.js route files.
+- Avoid barrel files that only re-export secondary owners. `index.tsx` is acceptable for a route/tab entry component; import header controls, switches, sections, and row owners from their concrete owner files.
 - Type simple one-off props inline. Use a named `Props` type only when reused, exported, complex, or clearer.
-- Use API-generated or API-returned types at component boundaries. Keep small UI conversion helpers beside the component that needs them.
-- Name values by their domain role and backend API contract, and keep that name stable across the call chain, especially IDs like `appInstanceId`. Normalize framework or route params at the boundary.
-- Keep fallback and invariant checks at the lowest component that already handles that state; callers should pass raw values through instead of duplicating checks.
+- Use API-generated or API-returned types at component boundaries. Keep small UI conversion helpers and one-off UI extensions beside the component that needs them.
+- Avoid `common.tsx` buckets for shared UI. Use a feature-local `components/` folder with concrete filenames that describe the shared role.
+- Do not create type aliases that only rename another type. Use aliases only for real UI concepts, refinements, or reusable local contracts.
+- Name values by their domain role and backend API contract, especially persistent IDs and route params. Normalize framework or route params at the boundary.
+- Put fallback and invariant checks in the lowest component that already handles that state. Do not extract helpers whose only behavior is hiding missing display data.
+
+## Generated API And Nullable Data
+
+- Treat generated contracts as authoritative at API, query, mutation, cache, and service boundaries. For enterprise APIs, use `packages/contracts/generated/enterprise/*`.
+- Do not hand-write DTO mirrors, widen generated fields/enums, or add parallel frontend enum/status layers unless they model product state not represented by the API.
+- Use generated enum objects and union types directly in props, comparisons, status logic, and i18n keys. Presentation-only tone maps should be keyed by generated enums.
+- Normalize or coerce only at real boundaries: user-entered forms, search, URL/query params, file names, DOM IDs, or legacy adapters.
+- Do not coerce nullable or optional API strings to `''` in query, derived model, or payload-building code. Keep `null` or `undefined` until the final boundary requiring a string.
+- Do not use `value || undefined` for mutation fields where `''` means "clear this value". Trim or normalize at the form boundary, then preserve intentional empty strings.
+- Prefer nullable-tolerant render props for API-returned rows. Narrow only where a real value is required, such as mutation params, route hrefs, select values, query input, or required React keys.
+- Build required values in the same branch that proves them, using `flatMap`, a local loop, or an early return. Avoid truthiness guards, `filter(Boolean)`, `filter(item => item.id)`, and `!` after filters.
+- Use conditional spreads or explicit pushes for conditional array items instead of `undefined` placeholders followed by narrowing filters.
+- Empty collection fallbacks are for not-yet-loaded query data or genuinely nullable collections at the owning render boundary, not for hiding required API fields.
 
 ## Queries And Mutations
 
-- Keep `web/contract/*` as the single source of truth for API shape; follow existing domain/router patterns and the `{ params, query?, body? }` input shape.
-- Consume queries directly with `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))`.
-- Avoid pass-through hooks and thin `web/service/use-*` wrappers that only rename `queryOptions()` or `mutationOptions()`. Extract a small `queryOptions` helper only when repeated call-site options justify it.
-- Keep feature hooks for real orchestration, workflow state, or shared domain behavior.
-- For missing required query input, use `input: skipToken`; use `enabled` only for extra business gating after the input is valid.
-- Consume mutations directly with `useMutation(consoleQuery.xxx.mutationOptions(...))` or `useMutation(marketplaceQuery.xxx.mutationOptions(...))`; use oRPC clients as `mutationFn` only for custom flows.
-- Put shared cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`; components may add UI feedback callbacks, but should not own shared invalidation rules.
+- Keep `web/contract/*` as the API shape source of truth and follow the `{ params, query?, body? }` input shape.
+- Consume generated queries with `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))`.
+- If a generated query input comes from an atom, including a route-identity bridge atom, keep the query in `atomWithQuery`; do not unwrap the atom in a component just to call `useQuery`.
+- Consume owner-local mutations with `useMutation(consoleQuery.xxx.mutationOptions(...))` or `useMutation(marketplaceQuery.xxx.mutationOptions(...))` when pending/error state is not consumed by feature atoms.
+- In `atomWithQuery`, `atomWithInfiniteQuery`, and `atomWithMutation`, return generated `queryOptions()`, `infiniteOptions()`, or `mutationOptions()` directly. Pass `enabled`, `retry`, `placeholderData`, `select`, and pagination options into the generated call instead of spreading options into a hand-built object.
+- For generated oRPC options with missing required input, branch the whole input with `input: condition ? validInput : skipToken` and `enabled: Boolean(condition)`. Never place `skipToken` inside a nested placeholder payload or coerce required IDs to `''`.
+- When prefetch and render use the same request, extract local query options or a query-options atom so `prefetchQuery` and `useQuery`/`atomWithQuery` share the exact options.
+- For custom query or mutation functions, wrap options with TanStack `queryOptions(...)` or `mutationOptions(...)`.
+- Do not extract generated `queryOptions(...)` into a helper solely to share input construction; extract only when prefetch/render must share exact options or the helper owns real domain behavior.
+- Avoid pass-through hooks and thin `web/service/use-*` wrappers that only rename generated options. Keep feature hooks for real orchestration, workflow state, or shared domain behavior.
+- Put shared cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`. Component or atom callbacks may handle local toasts, closing dialogs, and navigation, but should not replace shared invalidation or patch shared server state locally.
+- For overlays that may open heavier secondary content, prefetch from the trigger/menu open event with `queryClient.prefetchQuery(queryOptions)` when `onOpenChange` is available. Do not mount hidden subscribers just to warm cache.
 - Do not use deprecated `useInvalid` or `useReset`.
 - Prefer `mutate(...)`; use `mutateAsync(...)` only when Promise semantics are required, and wrap awaited calls in `try/catch`.
 
-## Component Boundaries
+## Boundaries And Overlays
 
-- Use the first level below a page or tab to organize independent page sections when it adds real structure. This layer is layout/semantic first, not automatically the data owner.
-- Split deeper components by the data and state each layer actually needs. Each component should access only necessary data, and ownership should stay at the lowest consumer.
+- Use the first level below a page or tab to organize independent page sections when it adds structure or the root folder becomes noisy. This layer is layout/semantic first, not automatically the data owner.
+- Treat component names, semantic roles, and user- or design-marked visual regions as boundary constraints. Keep adjacent UI as a sibling owner or introduce a correctly named broader owner.
 - Keep cohesive forms, menu bodies, and one-off helpers local unless they need their own state, reuse, or semantic boundary.
-- Separate hidden secondary surfaces from the trigger's main flow. For dialogs, dropdowns, popovers, and similar branches, extract a small local component that owns the trigger, open state, and hidden content when it would obscure the parent flow.
-- Preserve composability by separating behavior ownership from layout ownership. A dropdown action may own its trigger, open state, and menu content; the caller owns placement such as slots, offsets, and alignment.
-- Avoid unnecessary DOM hierarchy. Do not add wrapper elements unless they provide layout, semantics, accessibility, state ownership, or integration with a library API; prefer fragments or styling an existing element when possible.
-- Avoid shallow wrappers and prop renaming unless the wrapper adds validation, orchestration, error handling, state ownership, or a real semantic boundary.
+- Separate hidden secondary surfaces from the trigger's main flow. For dialogs, dropdowns, popovers, and similar branches, extract a small local component when hidden content would obscure the parent.
+- Preserve composability by separating behavior ownership from placement ownership: an action can own trigger/open/menu content while the caller owns slots, offsets, and alignment.
+- When a dialog, dropdown, or popover accepts controlled `open`, mount it unconditionally unless unmounting is required for performance or reset semantics. Use keyed scope or local state reset instead of `{open && <Surface />}` wrappers.
+- When opening a dialog from a menu item, keep the menu and dialog as sibling surfaces. Let the menu command open the dialog, and mount the dialog outside menu popup content.
+- For dialogs and alert dialogs, keep the root responsible for `open` wiring and put query/mutation hooks inside the content component when work should mount only after the overlay opens.
+- Prefer uncontrolled overlay roots when the library can own open state. Use `onOpenChange` for side effects and CSS/data selectors for open-state styling.
+- Avoid wrapper DOM unless it provides layout, semantics, accessibility, state ownership, or library integration. Avoid shallow wrappers, hook-to-props adapters, layout-only render props, children pass-through wrappers, and prop renaming unless they add real behavior or a real boundary.
 
-## You Might Not Need An Effect
-
-- Use Effects only to synchronize with external systems such as browser APIs, non-React widgets, subscriptions, timers, analytics that must run because the component was shown, or imperative DOM integration.
-- Do not use Effects to transform props or state for rendering. Calculate derived values during render, and use `useMemo` only when the calculation is actually expensive.
-- Do not use Effects to handle user actions. Put action-specific logic in the event handler where the cause is known.
-- Do not use Effects to copy one state value into another state value representing the same concept. Pick one source of truth and derive the rest during render.
-- Do not reset or adjust state from props with an Effect. Prefer a `key` reset, storing a stable ID and deriving the selected object, or guarded same-component render-time adjustment when truly necessary.
-- Prefer framework data APIs or TanStack Query for data fetching instead of writing request Effects in components.
-- If an Effect still seems necessary, first name the external system it synchronizes with. If there is no external system, remove the Effect and restructure the state or event flow.
-
-## Navigation And Performance
+## Effects, Navigation, And Performance
 
+- Use Effects only to synchronize with external systems. Do not use Effects to transform props/state for rendering, handle user actions, copy state, reset state from props, or fetch data.
+- For forms initialized from query data, prefer keyed remounts or surface-entry atom hydration over Effects that copy query data into form state.
+- Prefer framework data APIs or TanStack Query for data fetching.
 - Prefer `Link` for normal navigation. Use router APIs only for command-flow side effects such as mutation success, guarded redirects, or form submission.
+- Before using `memo`, move changing state down to the smallest component that uses it. If state must wrap stable content, lift the stable content up and pass it as `children`.
 - Avoid `memo`, `useMemo`, and `useCallback` unless there is a clear performance reason.

.claude/skills/karpathy-guidelines

@@ -0,0 +1 @@
+../../.agents/skills/karpathy-guidelines

.github/CODEOWNERS

@@ -23,8 +23,8 @@
 /docs/ @crazywoola
 
 # CLI
-/cli/ @langgenius/maintainers
-/.github/workflows/cli-tests.yml @langgenius/maintainers
+/cli/ @GareArc
+/.github/workflows/cli-tests.yml @GareArc
 
 # Backend (default owner, more specific rules below will override)
 /api/ @QuantumGhost

.github/workflows/api-tests.yml

@@ -29,13 +29,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -91,13 +91,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -142,13 +142,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: "3.12"
@@ -195,7 +195,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           files: ./coverage.xml
           disable_search: true

.github/workflows/autofix.yml

@@ -20,7 +20,7 @@ jobs:
         run: echo "autofix.ci updates pull request branches, not merge group refs."
 
       - if: github.event_name != 'merge_group'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Check Docker Compose inputs
         if: github.event_name != 'merge_group'
@@ -66,7 +66,7 @@ jobs:
           python-version: "3.11"
 
       - if: github.event_name != 'merge_group'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Generate Docker Compose
         if: github.event_name != 'merge_group' && steps.docker-compose-changes.outputs.any_changed == 'true'

.github/workflows/build-push.yml

@@ -8,7 +8,6 @@ on:
       - "build/**"
       - "release/e-*"
       - "hotfix/**"
-      - "feat/hitl-backend"
     tags:
       - "*"
 
@@ -21,6 +20,8 @@ env:
   DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
   DIFY_WEB_IMAGE_NAME: ${{ vars.DIFY_WEB_IMAGE_NAME || 'langgenius/dify-web' }}
   DIFY_API_IMAGE_NAME: ${{ vars.DIFY_API_IMAGE_NAME || 'langgenius/dify-api' }}
+  DIFY_AGENT_IMAGE_NAME: ${{ vars.DIFY_AGENT_IMAGE_NAME || 'langgenius/dify-agent-backend' }}
+  DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME: ${{ vars.DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME || 'langgenius/dify-agent-local-sandbox' }}
 
 jobs:
   build:
@@ -60,6 +61,34 @@ jobs:
             file: "web/Dockerfile"
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
+          - service_name: "build-agent-amd64"
+            image_name_env: "DIFY_AGENT_IMAGE_NAME"
+            artifact_context: "agent"
+            build_context: "{{defaultContext}}"
+            file: "dify-agent/Dockerfile"
+            platform: linux/amd64
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: "build-agent-arm64"
+            image_name_env: "DIFY_AGENT_IMAGE_NAME"
+            artifact_context: "agent"
+            build_context: "{{defaultContext}}"
+            file: "dify-agent/Dockerfile"
+            platform: linux/arm64
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: "build-agent-local-sandbox-amd64"
+            image_name_env: "DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME"
+            artifact_context: "local-sandbox"
+            build_context: "{{defaultContext}}:dify-agent"
+            file: "docker/local-sandbox/Dockerfile"
+            platform: linux/amd64
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: "build-agent-local-sandbox-arm64"
+            image_name_env: "DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME"
+            artifact_context: "local-sandbox"
+            build_context: "{{defaultContext}}:dify-agent"
+            file: "docker/local-sandbox/Dockerfile"
+            platform: linux/arm64
+            runs_on: depot-ubuntu-24.04-4
 
     steps:
       - name: Prepare
@@ -68,7 +97,7 @@ jobs:
           echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
 
       - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
         with:
           username: ${{ env.DOCKERHUB_USER }}
           password: ${{ env.DOCKERHUB_TOKEN }}
@@ -78,13 +107,13 @@ jobs:
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
         with:
           images: ${{ env[matrix.image_name_env] }}
 
       - name: Build Docker image
         id: build
-        uses: depot/build-push-action@5f3b3c2e5a00f0093de47f657aeaefcedff27d18 # v1.17.0
+        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
         with:
           project: ${{ vars.DEPOT_PROJECT_ID }}
           context: ${{ matrix.build_context }}
@@ -122,12 +151,18 @@ jobs:
           - service_name: "validate-web-amd64"
             build_context: "{{defaultContext}}"
             file: "web/Dockerfile"
+          - service_name: "validate-agent-amd64"
+            build_context: "{{defaultContext}}"
+            file: "dify-agent/Dockerfile"
+          - service_name: "validate-agent-local-sandbox-amd64"
+            build_context: "{{defaultContext}}:dify-agent"
+            file: "docker/local-sandbox/Dockerfile"
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
 
       - name: Validate Docker image
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           push: false
           context: ${{ matrix.build_context }}
@@ -147,6 +182,12 @@ jobs:
           - service_name: "merge-web-images"
             image_name_env: "DIFY_WEB_IMAGE_NAME"
             context: "web"
+          - service_name: "merge-agent-images"
+            image_name_env: "DIFY_AGENT_IMAGE_NAME"
+            context: "agent"
+          - service_name: "merge-agent-local-sandbox-images"
+            image_name_env: "DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME"
+            context: "local-sandbox"
     steps:
       - name: Download digests
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -156,14 +197,14 @@ jobs:
           merge-multiple: true
 
       - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
         with:
           username: ${{ env.DOCKERHUB_USER }}
           password: ${{ env.DOCKERHUB_TOKEN }}
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
         with:
           images: ${{ env[matrix.image_name_env] }}
           tags: |

.github/workflows/cli-e2e.yml

@@ -0,0 +1,415 @@
+name: CLI E2E Tests
+
+on:
+  workflow_dispatch:
+    inputs:
+      cli_ref:
+        description: "Git ref (default: current branch)"
+        type: string
+        required: false
+
+      edition:
+        description: "Dify edition"
+        type: choice
+        required: false
+        default: ee
+        options: [ee, ce]
+
+      test_scope:
+        description: "smoke = [P0] only  /  full = all cases"
+        type: choice
+        required: false
+        default: full
+        options: [smoke, full]
+
+      # ── Suite on/off ────────────────────────────────────────────────────────
+      suite_framework_output_error:
+        description: "framework + output + error-handling suites"
+        type: boolean
+        default: true
+      suite_discovery:
+        description: "discovery suite (get app / describe app)"
+        type: boolean
+        default: true
+      suite_run:
+        description: "run suite (basic / streaming / conversation / file / hitl)"
+        type: boolean
+        default: true
+      suite_auth:
+        description: "auth suite (login / status / whoami / use / devices / logout)"
+        type: boolean
+        default: true
+      suite_agent:
+        description: "agent suite"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+# ── Shared env injected into every E2E job ───────────────────────────────────
+# Each job reads DIFY_E2E_TOKEN + app IDs from the provision job outputs,
+# so global-setup skips minting and finds existing apps in < 10 s.
+env:
+  DIFY_E2E_NO_KEYRING: "1"   # Linux CI has no keychain; skip probe
+  VITEST_RETRY:        "2"    # Retry flaky staging responses
+
+jobs:
+
+# ════════════════════════════════════════════════════════════════════════════
+# 0. PROVISION — mint token + import DSL fixtures (runs once, outputs IDs)
+# ════════════════════════════════════════════════════════════════════════════
+  provision:
+    name: "Provision: mint token + DSL apps"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      token:                      ${{ steps.out.outputs.DIFY_E2E_TOKEN }}
+      workspace_id:               ${{ steps.out.outputs.DIFY_E2E_WORKSPACE_ID }}
+      workspace_name:             ${{ steps.out.outputs.DIFY_E2E_WORKSPACE_NAME }}
+      ws2_id:                     ${{ steps.out.outputs.DIFY_E2E_WS2_ID }}
+      chat_app_id:                ${{ steps.out.outputs.DIFY_E2E_CHAT_APP_ID }}
+      workflow_app_id:            ${{ steps.out.outputs.DIFY_E2E_WORKFLOW_APP_ID }}
+      file_app_id:                ${{ steps.out.outputs.DIFY_E2E_FILE_APP_ID }}
+      file_chat_app_id:           ${{ steps.out.outputs.DIFY_E2E_FILE_CHAT_APP_ID }}
+      hitl_app_id:                ${{ steps.out.outputs.DIFY_E2E_HITL_APP_ID }}
+      hitl_external_app_id:       ${{ steps.out.outputs.DIFY_E2E_HITL_EXTERNAL_APP_ID }}
+      hitl_single_action_app_id:  ${{ steps.out.outputs.DIFY_E2E_HITL_SINGLE_ACTION_APP_ID }}
+      hitl_multi_node_app_id:     ${{ steps.out.outputs.DIFY_E2E_HITL_MULTI_NODE_APP_ID }}
+      ws2_app_id:                 ${{ steps.out.outputs.DIFY_E2E_WS2_APP_ID }}
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with:
+          package_json_field: packageManager
+          run_install: false
+
+      - name: Install CLI dependencies
+        working-directory: cli
+        run: pnpm install --frozen-lockfile
+
+      - name: Mint token & provision apps
+        id: out
+        working-directory: cli
+        env:
+          DIFY_E2E_HOST:     ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:    ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD: ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_TOKEN:    ${{ secrets.DIFY_E2E_TOKEN }}
+          DIFY_E2E_EDITION:  ${{ inputs.edition || 'ee' }}
+        run: bun scripts/e2e-provision.ts
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1-B. framework + output + error-handling (parallel with run/discovery)
+# ════════════════════════════════════════════════════════════════════════════
+  suite-framework-output-error:
+    name: "Suite: framework + output + error-handling"
+    if: ${{ inputs.suite_framework_output_error != 'false' }}
+    needs: provision
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: Run framework + output + error-handling
+        env:
+          DIFY_E2E_HOST:           ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:          ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:       ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:        ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_TOKEN:          ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:   ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME: ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_CHAT_APP_ID:    ${{ needs.provision.outputs.chat_app_id }}
+          DIFY_E2E_WORKFLOW_APP_ID: ${{ needs.provision.outputs.workflow_app_id }}
+          DIFY_E2E_INCLUDE: "test/e2e/suites/framework/**/*.e2e.ts,test/e2e/suites/output/**/*.e2e.ts,test/e2e/suites/error-handling/**/*.e2e.ts"
+        run: |
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            pnpm test:e2e -- -t "\[P0\]"
+          else
+            pnpm test:e2e
+          fi
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1-C. Discovery (parallel)
+# ════════════════════════════════════════════════════════════════════════════
+  suite-discovery:
+    name: "Suite: discovery"
+    if: ${{ inputs.suite_discovery != 'false' }}
+    needs: provision
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: Run discovery suite
+        env:
+          DIFY_E2E_HOST:           ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:          ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:       ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:        ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_TOKEN:          ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:   ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME: ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_WS2_ID:         ${{ needs.provision.outputs.ws2_id }}
+          DIFY_E2E_CHAT_APP_ID:    ${{ needs.provision.outputs.chat_app_id }}
+          DIFY_E2E_WORKFLOW_APP_ID: ${{ needs.provision.outputs.workflow_app_id }}
+          DIFY_E2E_INCLUDE: "test/e2e/suites/discovery/**/*.e2e.ts"
+        run: |
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            pnpm test:e2e -- -t "\[P0\]"
+          else
+            pnpm test:e2e
+          fi
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1-D. Run suite — 5 files in matrix (parallel)
+# ════════════════════════════════════════════════════════════════════════════
+  suite-run:
+    name: "Suite: run / ${{ matrix.name }}"
+    if: ${{ inputs.suite_run != 'false' }}
+    needs: provision
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: basic
+            file: run-app-basic.e2e.ts
+          - name: streaming
+            file: run-app-streaming.e2e.ts
+          - name: conversation
+            file: run-app-conversation.e2e.ts
+          - name: file
+            file: run-app-file.e2e.ts
+          - name: hitl
+            file: run-app-hitl.e2e.ts
+
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: "Run run/${{ matrix.name }}"
+        env:
+          DIFY_E2E_HOST:                      ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:                     ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:                  ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:                   ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_SSO_TOKEN:                 ${{ secrets.DIFY_E2E_SSO_TOKEN }}
+          DIFY_E2E_TOKEN:                     ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:              ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME:            ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_CHAT_APP_ID:               ${{ needs.provision.outputs.chat_app_id }}
+          DIFY_E2E_WORKFLOW_APP_ID:           ${{ needs.provision.outputs.workflow_app_id }}
+          DIFY_E2E_FILE_APP_ID:               ${{ needs.provision.outputs.file_app_id }}
+          DIFY_E2E_FILE_CHAT_APP_ID:          ${{ needs.provision.outputs.file_chat_app_id }}
+          DIFY_E2E_HITL_APP_ID:               ${{ needs.provision.outputs.hitl_app_id }}
+          DIFY_E2E_HITL_EXTERNAL_APP_ID:      ${{ needs.provision.outputs.hitl_external_app_id }}
+          DIFY_E2E_HITL_SINGLE_ACTION_APP_ID: ${{ needs.provision.outputs.hitl_single_action_app_id }}
+          DIFY_E2E_HITL_MULTI_NODE_APP_ID:    ${{ needs.provision.outputs.hitl_multi_node_app_id }}
+          DIFY_E2E_INCLUDE: "test/e2e/suites/run/${{ matrix.file }}"
+        run: |
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            pnpm test:e2e -- -t "\[P0\]"
+          else
+            pnpm test:e2e
+          fi
+
+      - name: Upload results on failure
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: e2e-run-${{ matrix.name }}-${{ github.run_id }}
+          path: cli/test-results/
+          retention-days: 3
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1-E. auth/login + status + whoami (parallel, read-only, safe)
+# ════════════════════════════════════════════════════════════════════════════
+  suite-auth-safe:
+    name: "Suite: auth (login / status / whoami)"
+    if: ${{ inputs.suite_auth != 'false' }}
+    needs: provision
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: Run auth/login + status + whoami
+        env:
+          DIFY_E2E_HOST:           ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:          ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:       ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:        ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_TOKEN:          ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:   ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME: ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_WS2_ID:         ${{ needs.provision.outputs.ws2_id }}
+          DIFY_E2E_INCLUDE: "test/e2e/suites/auth/login.e2e.ts,test/e2e/suites/auth/status.e2e.ts,test/e2e/suites/auth/whoami.e2e.ts"
+        run: |
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            pnpm test:e2e -- -t "\[P0\]"
+          else
+            pnpm test:e2e
+          fi
+
+# ════════════════════════════════════════════════════════════════════════════
+# 2. DESTRUCTIVE — auth/use + devices + logout + agent (serial, runs LAST)
+#    Must wait for ALL parallel suites to finish to avoid token revocation
+#    invalidating other in-flight requests.
+# ════════════════════════════════════════════════════════════════════════════
+  suite-last:
+    name: "Suite: auth-use + devices + logout + agent (last, serial)"
+    # Runs when auth is selected; also runs after all parallel jobs finish
+    if: ${{ inputs.suite_auth != 'false' || inputs.suite_agent != 'false' }}
+    needs:
+      - provision
+      - suite-framework-output-error
+      - suite-discovery
+      - suite-run
+      - suite-auth-safe
+    # `needs` on a skipped job is treated as success — safe to proceed even if
+    # some suites were disabled via toggle.
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: Run use / devices / logout / agent (serial)
+        env:
+          DIFY_E2E_HOST:                      ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:                     ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:                  ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:                   ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_TOKEN:                     ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:              ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME:            ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_WS2_ID:                    ${{ needs.provision.outputs.ws2_id }}
+          DIFY_E2E_CHAT_APP_ID:               ${{ needs.provision.outputs.chat_app_id }}
+          DIFY_E2E_WORKFLOW_APP_ID:           ${{ needs.provision.outputs.workflow_app_id }}
+          DIFY_E2E_HITL_APP_ID:               ${{ needs.provision.outputs.hitl_app_id }}
+          DIFY_E2E_HITL_EXTERNAL_APP_ID:      ${{ needs.provision.outputs.hitl_external_app_id }}
+          DIFY_E2E_HITL_SINGLE_ACTION_APP_ID: ${{ needs.provision.outputs.hitl_single_action_app_id }}
+          DIFY_E2E_HITL_MULTI_NODE_APP_ID:    ${{ needs.provision.outputs.hitl_multi_node_app_id }}
+        run: |
+          # Collect files in safe order: use → devices → logout (revokes last) → agent
+          FILES=()
+          if [ "${{ inputs.suite_auth }}" = "true" ]; then
+            FILES+=(
+              test/e2e/suites/auth/use.e2e.ts
+              test/e2e/suites/auth/devices.e2e.ts
+              test/e2e/suites/auth/logout.e2e.ts
+            )
+          fi
+          if [ "${{ inputs.suite_agent }}" = "true" ]; then
+            while IFS= read -r f; do FILES+=("$f"); done \
+              < <(find test/e2e/suites/agent -name '*.e2e.ts' | sort)
+          fi
+
+          [ ${#FILES[@]} -eq 0 ] && { echo "Nothing to run."; exit 0; }
+
+          # Pass files via DIFY_E2E_INCLUDE (comma-separated) so vitest
+          # config's include list is overridden instead of ANDed.
+          INCLUDE=$(IFS=,; echo "${FILES[*]}")
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            DIFY_E2E_INCLUDE="$INCLUDE" pnpm test:e2e -- -t "\[P0\]"
+          else
+            DIFY_E2E_INCLUDE="$INCLUDE" pnpm test:e2e
+          fi
+
+      - name: Upload results on failure
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: e2e-last-${{ github.run_id }}
+          path: cli/test-results/
+          retention-days: 3

.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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        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/cli-release.yml

@@ -35,7 +35,7 @@ jobs:
       dify_tag: ${{ steps.resolve.outputs.dify_tag }}
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -98,7 +98,7 @@ jobs:
       DIFY_TAG: ${{ needs.validate.outputs.dify_tag }}
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
           fetch-depth: 1

.github/workflows/cli-smoke.yml

@@ -24,7 +24,7 @@ jobs:
         shell: bash
     steps:
       - name: Checkout cli ref
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false

.github/workflows/cli-tests.yml

@@ -30,23 +30,28 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
       - name: Setup web environment
         uses: ./.github/actions/setup-web
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
       - name: Validate release manifest
         if: matrix.os == 'depot-ubuntu-24.04'
         run: scripts/release-validate-manifest.sh
 
       - name: CI pipeline (typecheck, lint, coverage, build)
-        run: pnpm ci
+        run: pnpm run ci
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' && matrix.os == 'depot-ubuntu-24.04' }}
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           directory: cli/coverage
           flags: cli

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

@@ -13,13 +13,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: "3.12"
@@ -40,7 +40,7 @@ jobs:
           cp envs/middleware.env.example middleware.env
 
       - name: Set up Middlewares
-        uses: hoverkraft-tech/compose-action@d2bee4f07e8ca410d6b196d00f90c12e7d48c33a # v2.6.0
+        uses: hoverkraft-tech/compose-action@11beaa1c2dae4e8ed7b1665aa074723b6cecb0e4 # v3.0.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml
@@ -63,13 +63,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: "3.12"
@@ -94,7 +94,7 @@ jobs:
           sed -i 's/DB_USERNAME=postgres/DB_USERNAME=mysql/' middleware.env
 
       - name: Set up Middlewares
-        uses: hoverkraft-tech/compose-action@d2bee4f07e8ca410d6b196d00f90c12e7d48c33a # v2.6.0
+        uses: hoverkraft-tech/compose-action@11beaa1c2dae4e8ed7b1665aa074723b6cecb0e4 # v3.0.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml

.github/workflows/deploy-agent.yml

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

.github/workflows/docker-build.yml

@@ -53,7 +53,7 @@ jobs:
         uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
 
       - name: Build Docker Image
-        uses: depot/build-push-action@5f3b3c2e5a00f0093de47f657aeaefcedff27d18 # v1.17.0
+        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
         with:
           project: ${{ vars.DEPOT_PROJECT_ID }}
           push: false
@@ -77,10 +77,10 @@ jobs:
             file: "web/Dockerfile"
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
 
       - name: Build Docker Image
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           push: false
           context: ${{ matrix.context }}

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

@@ -24,7 +24,7 @@ jobs:
     name: Require cherry-pick provenance
     runs-on: depot-ubuntu-24.04
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 

.github/workflows/main-ci.yml

@@ -48,7 +48,7 @@ jobs:
       vdb-changed: ${{ steps.changes.outputs.vdb }}
       migration-changed: ${{ steps.changes.outputs.migration }}
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
         id: changes
         with:

.github/workflows/pyrefly-diff.yml

@@ -17,12 +17,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout PR branch
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
 

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

@@ -21,10 +21,10 @@ jobs:
     if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.pull_requests[0].head.repo.full_name != github.repository }}
     steps:
       - name: Checkout default branch (trusted code)
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
 

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

@@ -17,12 +17,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout PR branch
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
 

.github/workflows/stale.yml

@@ -18,7 +18,7 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
+      - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 # v10.3.0
         with:
           days-before-issue-stale: 15
           days-before-issue-close: 3

.github/workflows/style.yml

@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -33,7 +33,7 @@ jobs:
 
       - name: Setup UV and Python
         if: steps.changed-files.outputs.any_changed == 'true'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: false
           python-version: "3.12"
@@ -53,6 +53,8 @@ jobs:
 
       - name: Run Type Checks
         if: steps.changed-files.outputs.any_changed == 'true'
+        env:
+          PYREFLY_OUTPUT_FORMAT: github
         run: make type-check-core
 
       - name: Dotenv check
@@ -71,7 +73,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -105,6 +107,14 @@ jobs:
         if: steps.changed-files.outputs.any_changed == 'true'
         run: vp run knip
 
+      - name: Web dead code check production
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: vp run knip:production
+
+      - name: Web production unused declarations check
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: vp run knip:production-unused-check
+
   ts-common-style:
     name: TS Common
     runs-on: depot-ubuntu-24.04
@@ -114,7 +124,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -171,7 +181,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false

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

@@ -24,7 +24,7 @@ jobs:
         working-directory: sdks/nodejs-client
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

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

@@ -40,7 +40,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -158,7 +158,7 @@ jobs:
 
       - name: Run Claude Code for Translation Sync
         if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@1dc994ee7a008f0ecc866d9ac23ef036b7229f84 # v1.0.127
+        uses: anthropics/claude-code-action@806af32823ef69c8ef357086c573a902af641307 # v1.0.151
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}

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

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 

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

@@ -24,7 +24,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -36,7 +36,7 @@ jobs:
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/vdb-tests.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -33,7 +33,7 @@ jobs:
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/web-e2e.yml

@@ -20,7 +20,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -28,7 +28,7 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: "3.12"

.github/workflows/web-tests.yml

@@ -31,7 +31,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -64,7 +64,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -83,7 +83,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           directory: web/coverage
           flags: web
@@ -102,7 +102,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -113,13 +113,36 @@ 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 != '' }}
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           directory: packages/dify-ui/coverage
           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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        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

README.md

@@ -116,7 +116,7 @@ All of Dify's offerings come with corresponding APIs, so you could effortlessly
 ## Using Dify
 
 - **Cloud <br/>**
-  We host a [Dify Cloud](https://dify.ai) service for anyone to try with zero setup. It provides all the capabilities of the self-deployed version, and includes 200 free GPT-4 calls in the sandbox plan.
+  We host a [Dify Cloud](https://dify.ai) service for anyone to try with zero setup. It provides all the capabilities of the self-deployed version, and includes 200 free GPT-4 calls in the sandbox plan. If you run into issues with Dify Cloud, [contact our Cloud support team](mailto:cloud@dify.ai?subject=%5BGitHub%5DDify%20Cloud%20Support).
 
 - **Self-hosting Dify Community Edition<br/>**
   Quickly get Dify running in your environment with this [starter guide](#quick-start).

api/.env.example

@@ -36,6 +36,9 @@ FILES_ACCESS_TIMEOUT=300
 # Collaboration mode toggle
 ENABLE_COLLABORATION_MODE=true
 
+# Learn app feature toggle
+ENABLE_LEARN_APP=true
+
 # Access token expiration time in minutes
 ACCESS_TOKEN_EXPIRE_MINUTES=60
 
@@ -768,9 +771,16 @@ EVENT_BUS_REDIS_CHANNEL_TYPE=pubsub
 # Whether to use Redis cluster mode while use redis as event bus.
 #  It's highly recommended to enable this for large deployments.
 EVENT_BUS_REDIS_USE_CLUSTERS=false
-EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS=2000
 
 # Whether to Enable human input timeout check task
 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/app.py

@@ -55,7 +55,7 @@ else:
 
 if __name__ == "__main__":
     from gevent import pywsgi
-    from geventwebsocket.handler import WebSocketHandler  # type: ignore[reportMissingTypeStubs]
+    from geventwebsocket.handler import WebSocketHandler
 
     log_startup_banner(HOST, PORT)
     server = pywsgi.WSGIServer((HOST, PORT), socketio_app, handler_class=WebSocketHandler)

api/app_factory.py

@@ -1,7 +1,7 @@
 import logging
 import time
 
-import socketio  # type: ignore[reportMissingTypeStubs]
+import socketio
 from flask import request
 from opentelemetry.trace import get_current_span
 from opentelemetry.trace.span import INVALID_SPAN_ID, INVALID_TRACE_ID

api/celery_entrypoint.py

@@ -1,5 +1,5 @@
-import psycogreen.gevent as pscycogreen_gevent  # type: ignore
-from grpc.experimental import gevent as grpc_gevent  # type: ignore
+import psycogreen.gevent as pscycogreen_gevent
+from grpc.experimental import gevent as grpc_gevent
 
 # grpc gevent
 grpc_gevent.init_gevent()

api/clients/agent_backend/__init__.py

@@ -5,6 +5,8 @@ API adapters: request building from Dify product concepts, a thin client wrapper
 event adaptation for future workflow integration, and deterministic fakes.
 """
 
+from dify_agent.protocol import RuntimeLayerSpec, extract_runtime_layer_specs
+
 from clients.agent_backend.client import AgentBackendRunClient, DifyAgentBackendRunClient
 from clients.agent_backend.errors import (
     AgentBackendError,
@@ -16,12 +18,12 @@ from clients.agent_backend.errors import (
     AgentBackendValidationError,
 )
 from clients.agent_backend.event_adapter import (
+    AgentBackendDeferredToolCallInternalEvent,
     AgentBackendInternalEvent,
     AgentBackendInternalEventType,
     AgentBackendRunCancelledInternalEvent,
     AgentBackendRunEventAdapter,
     AgentBackendRunFailedInternalEvent,
-    AgentBackendRunPausedInternalEvent,
     AgentBackendRunStartedInternalEvent,
     AgentBackendRunSucceededInternalEvent,
     AgentBackendStreamInternalEvent,
@@ -31,6 +33,7 @@ from clients.agent_backend.fake_client import FakeAgentBackendRunClient, FakeAge
 from clients.agent_backend.request_builder import (
     AGENT_SOUL_PROMPT_LAYER_ID,
     DIFY_EXECUTION_CONTEXT_LAYER_ID,
+    DIFY_KNOWLEDGE_BASE_LAYER_ID,
     DIFY_PLUGIN_TOOLS_LAYER_ID,
     WORKFLOW_NODE_JOB_PROMPT_LAYER_ID,
     WORKFLOW_USER_PROMPT_LAYER_ID,
@@ -39,18 +42,18 @@ from clients.agent_backend.request_builder import (
     AgentBackendOutputConfig,
     AgentBackendRunRequestBuilder,
     AgentBackendWorkflowNodeRunInput,
-    CleanupLayerSpec,
-    extract_cleanup_layer_specs,
     redact_for_agent_backend_log,
 )
 
 __all__ = [
     "AGENT_SOUL_PROMPT_LAYER_ID",
     "DIFY_EXECUTION_CONTEXT_LAYER_ID",
+    "DIFY_KNOWLEDGE_BASE_LAYER_ID",
     "DIFY_PLUGIN_TOOLS_LAYER_ID",
     "WORKFLOW_NODE_JOB_PROMPT_LAYER_ID",
     "WORKFLOW_USER_PROMPT_LAYER_ID",
     "AgentBackendAgentAppRunInput",
+    "AgentBackendDeferredToolCallInternalEvent",
     "AgentBackendError",
     "AgentBackendHTTPError",
     "AgentBackendInternalEvent",
@@ -63,7 +66,6 @@ __all__ = [
     "AgentBackendRunEventAdapter",
     "AgentBackendRunFailedError",
     "AgentBackendRunFailedInternalEvent",
-    "AgentBackendRunPausedInternalEvent",
     "AgentBackendRunRequestBuilder",
     "AgentBackendRunStartedInternalEvent",
     "AgentBackendRunSucceededInternalEvent",
@@ -72,11 +74,11 @@ __all__ = [
     "AgentBackendTransportError",
     "AgentBackendValidationError",
     "AgentBackendWorkflowNodeRunInput",
-    "CleanupLayerSpec",
     "DifyAgentBackendRunClient",
     "FakeAgentBackendRunClient",
     "FakeAgentBackendScenario",
+    "RuntimeLayerSpec",
     "create_agent_backend_run_client",
-    "extract_cleanup_layer_specs",
+    "extract_runtime_layer_specs",
     "redact_for_agent_backend_log",
 ]

api/clients/agent_backend/event_adapter.py

@@ -2,7 +2,9 @@
 
 The adapter does not define a new cross-service event contract. It consumes
 ``dify_agent.protocol.RunEvent`` and produces small API-internal models that the
-future workflow Agent Node can map to Graphon/AppQueue events in phase 3.
+workflow Agent Node maps to Graphon/AppQueue events. Deferred external tool calls
+remain Dify Agent ``run_succeeded`` payloads on the wire; API code turns them
+into an internal event so workflow pause/session handling stays local to API.
 """
 
 from __future__ import annotations
@@ -12,11 +14,11 @@ from typing import Annotated, Literal, cast
 
 from agenton.compositor import CompositorSessionSnapshot
 from dify_agent.protocol import (
+    DeferredToolCallPayload,
     PydanticAIStreamRunEvent,
     RunCancelledEvent,
     RunEvent,
     RunFailedEvent,
-    RunPausedEvent,
     RunStartedEvent,
     RunSucceededEvent,
 )
@@ -30,7 +32,7 @@ class AgentBackendInternalEventType(StrEnum):
 
     RUN_STARTED = "run_started"
     STREAM_EVENT = "stream_event"
-    RUN_PAUSED = "run_paused"
+    DEFERRED_TOOL_CALL = "deferred_tool_call"
     RUN_SUCCEEDED = "run_succeeded"
     RUN_FAILED = "run_failed"
     RUN_CANCELLED = "run_cancelled"
@@ -67,13 +69,13 @@ class AgentBackendRunSucceededInternalEvent(AgentBackendInternalEventBase):
     session_snapshot: CompositorSessionSnapshot
 
 
-class AgentBackendRunPausedInternalEvent(AgentBackendInternalEventBase):
-    """API-internal resumable pause event for human handoff and Babysit flows."""
+class AgentBackendDeferredToolCallInternalEvent(AgentBackendInternalEventBase):
+    """API-internal representation of a Dify Agent deferred external tool call."""
 
-    type: Literal[AgentBackendInternalEventType.RUN_PAUSED] = AgentBackendInternalEventType.RUN_PAUSED
-    reason: str
+    type: Literal[AgentBackendInternalEventType.DEFERRED_TOOL_CALL] = AgentBackendInternalEventType.DEFERRED_TOOL_CALL
+    deferred_tool_call: DeferredToolCallPayload
     message: str | None = None
-    session_snapshot: CompositorSessionSnapshot | None = None
+    session_snapshot: CompositorSessionSnapshot
 
 
 class AgentBackendRunFailedInternalEvent(AgentBackendInternalEventBase):
@@ -95,7 +97,7 @@ class AgentBackendRunCancelledInternalEvent(AgentBackendInternalEventBase):
 type AgentBackendInternalEvent = Annotated[
     AgentBackendRunStartedInternalEvent
     | AgentBackendStreamInternalEvent
-    | AgentBackendRunPausedInternalEvent
+    | AgentBackendDeferredToolCallInternalEvent
     | AgentBackendRunSucceededInternalEvent
     | AgentBackendRunFailedInternalEvent
     | AgentBackendRunCancelledInternalEvent,
@@ -128,6 +130,18 @@ class AgentBackendRunEventAdapter:
                     )
                 ]
             case RunSucceededEvent():
+                if "deferred_tool_call" in event.data.model_fields_set:
+                    if event.data.deferred_tool_call is None:
+                        raise TypeError("run_succeeded deferred_tool_call branch is missing payload")
+                    return [
+                        AgentBackendDeferredToolCallInternalEvent(
+                            run_id=event.run_id,
+                            source_event_id=event.id,
+                            deferred_tool_call=event.data.deferred_tool_call,
+                            message=_deferred_tool_call_message(event.data.deferred_tool_call),
+                            session_snapshot=event.data.session_snapshot,
+                        )
+                    ]
                 return [
                     AgentBackendRunSucceededInternalEvent(
                         run_id=event.run_id,
@@ -136,16 +150,6 @@ class AgentBackendRunEventAdapter:
                         session_snapshot=event.data.session_snapshot,
                     )
                 ]
-            case RunPausedEvent():
-                return [
-                    AgentBackendRunPausedInternalEvent(
-                        run_id=event.run_id,
-                        source_event_id=event.id,
-                        reason=event.data.reason,
-                        message=event.data.message,
-                        session_snapshot=event.data.session_snapshot,
-                    )
-                ]
             case RunFailedEvent():
                 return [
                     AgentBackendRunFailedInternalEvent(
@@ -165,3 +169,18 @@ class AgentBackendRunEventAdapter:
                     )
                 ]
         raise TypeError(f"unsupported agent backend run event: {type(event).__name__}")
+
+
+def _deferred_tool_call_message(payload: DeferredToolCallPayload) -> str:
+    """Return a concise workflow pause message from deferred-tool arguments."""
+    args = payload.args
+    if isinstance(args, dict):
+        question = args.get("question")
+        if isinstance(question, str) and question.strip():
+            return question
+
+        title = args.get("title")
+        if isinstance(title, str) and title.strip():
+            return title
+
+    return f"Agent backend requested external input via deferred tool '{payload.tool_name}'."

api/clients/agent_backend/fake_client.py

@@ -17,11 +17,10 @@ from dify_agent.protocol import (
     CancelRunResponse,
     CreateRunRequest,
     CreateRunResponse,
+    DeferredToolCallPayload,
     RunEvent,
     RunFailedEvent,
     RunFailedEventData,
-    RunPausedEvent,
-    RunPausedEventData,
     RunStartedEvent,
     RunStatusResponse,
     RunSucceededEvent,
@@ -32,7 +31,11 @@ _FIXED_TIME = datetime(2026, 1, 1, tzinfo=UTC)
 
 
 class FakeAgentBackendScenario(StrEnum):
-    """Deterministic fake scenarios for API-side integration tests."""
+    """Deterministic fake scenarios for API-side integration tests.
+
+    ``PAUSED`` represents the API workflow effect. On the Dify Agent wire
+    protocol it is a succeeded run carrying a deferred external tool call.
+    """
 
     SUCCESS = "success"
     FAILED = "failed"
@@ -95,7 +98,7 @@ class FakeAgentBackendRunClient:
             case FakeAgentBackendScenario.PAUSED:
                 return RunStatusResponse(
                     run_id=run_id,
-                    status="paused",
+                    status="succeeded",
                     created_at=_FIXED_TIME,
                     updated_at=_FIXED_TIME,
                 )
@@ -128,13 +131,17 @@ class FakeAgentBackendRunClient:
             case FakeAgentBackendScenario.PAUSED:
                 return (
                     RunStartedEvent(id="1-0", run_id=run_id, created_at=_FIXED_TIME),
-                    RunPausedEvent(
+                    RunSucceededEvent(
                         id="2-0",
                         run_id=run_id,
                         created_at=_FIXED_TIME,
-                        data=RunPausedEventData(
-                            reason="human_input_required",
-                            message="Agent requested human input.",
+                        data=RunSucceededEventData(
+                            deferred_tool_call=DeferredToolCallPayload(
+                                tool_call_id="fake-ask-human-1",
+                                tool_name="ask_human",
+                                args={"question": "Agent requested human input."},
+                                metadata={"layer_type": "dify.ask_human", "schema_version": 1},
+                            ),
                             session_snapshot=CompositorSessionSnapshot(layers=[]),
                         ),
                     ),

api/clients/agent_backend/request_builder.py

@@ -11,13 +11,15 @@ composition-driven.
 
 from __future__ import annotations
 
-from typing import ClassVar, cast
+from collections.abc import Mapping
+from typing import ClassVar
 
 from agenton.compositor import CompositorSessionSnapshot
 from agenton.compositor.schemas import LayerSessionSnapshot
 from agenton.layers import ExitIntent
 from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
 from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
+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,
@@ -25,10 +27,12 @@ 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,
 )
+from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig
 from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
 from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
 from dify_agent.protocol import (
@@ -36,10 +40,12 @@ from dify_agent.protocol import (
     DIFY_AGENT_MODEL_LAYER_ID,
     DIFY_AGENT_OUTPUT_LAYER_ID,
     CreateRunRequest,
+    DeferredToolResultsPayload,
     LayerExitSignals,
     RunComposition,
     RunLayerSpec,
     RunPurpose,
+    RuntimeLayerSpec,
 )
 from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator
 
@@ -48,74 +54,16 @@ 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_KNOWLEDGE_BASE_LAYER_ID = "knowledge"
+DIFY_ASK_HUMAN_LAYER_ID = "ask_human"
 DIFY_SHELL_LAYER_ID = "shell"
 
-# Layer types that hold credentials in their per-run config. These are excluded
-# from the cleanup-replay composition (and from the snapshot that is sent with
-# the cleanup request) because we deliberately do not persist plaintext
-# credentials between runs.
-_CLEANUP_EXCLUDED_LAYER_TYPES: tuple[str, ...] = (
-    DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
-    DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
-)
-
-
-class CleanupLayerSpec(BaseModel):
-    """One layer node replayed by an Agent backend cleanup-only run.
-
-    Cleanup composition cannot include credential-bearing plugin layers, so we
-    persist only the non-plugin layer specs together with the original config.
-    Storing the config (rather than just ``name``/``type``) means cleanup does
-    not depend on the original build-time inputs being re-derivable.
-    """
-
-    name: str
-    type: str
-    deps: dict[str, str] = Field(default_factory=dict)
-    metadata: dict[str, JsonValue] = Field(default_factory=dict)
-    config: JsonValue = None
-
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
-
-def extract_cleanup_layer_specs(composition: RunComposition) -> list[CleanupLayerSpec]:
-    """Project the in-flight composition into the persistable cleanup spec list.
-
-    Plugin layers are intentionally dropped (their configs hold credentials and
-    the lifecycle contract says "do not include an LLM layer" during cleanup).
-    The filtered names must later drive snapshot filtering so the agenton
-    compositor's name-order check still passes for the cleanup run.
-    """
-    excluded = set(_CLEANUP_EXCLUDED_LAYER_TYPES)
-    specs: list[CleanupLayerSpec] = []
-    for layer in composition.layers:
-        if layer.type in excluded:
-            continue
-        config_value: JsonValue = None
-        if isinstance(layer.config, BaseModel):
-            config_value = layer.config.model_dump(mode="json", warnings=False)
-        else:
-            # ``RunLayerSpec.config`` is typed as ``LayerConfigInput`` which
-            # includes ``Mapping[str, object] | bytes``. In the cleanup-replay
-            # pipeline our builder only emits BaseModel-derived configs or
-            # ``None``, so the wider input alias narrows safely here.
-            config_value = cast(JsonValue, layer.config)
-        specs.append(
-            CleanupLayerSpec(
-                name=layer.name,
-                type=layer.type,
-                deps=dict(layer.deps),
-                metadata=dict(layer.metadata),
-                config=config_value,
-            )
-        )
-    return specs
-
 
 def _filter_snapshot_to_specs(
     snapshot: CompositorSessionSnapshot,
-    specs: list[CleanupLayerSpec],
+    specs: list[RuntimeLayerSpec],
 ) -> CompositorSessionSnapshot:
     """Keep only snapshot layers whose names appear in the cleanup spec list.
 
@@ -130,6 +78,13 @@ def _filter_snapshot_to_specs(
     return CompositorSessionSnapshot(schema_version=snapshot.schema_version, layers=filtered_layers)
 
 
+def _shell_layer_deps(*, include_drive: bool) -> dict[str, str]:
+    deps = {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
+    if include_drive:
+        deps["drive"] = DIFY_DRIVE_LAYER_ID
+    return deps
+
+
 class AgentBackendModelConfig(BaseModel):
     """API-side model/plugin selection before it is converted to Dify Agent layers."""
 
@@ -142,6 +97,30 @@ class AgentBackendModelConfig(BaseModel):
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
 
 
+# ``DifyPluginLLMLayerConfig.model_settings`` is pydantic_ai's ``ModelSettings``
+# TypedDict (closed: unknown keys are rejected, explicit ``None`` values fail the
+# per-field type checks). Agent Soul model settings carry a wider, nullable shape
+# (``stop`` / ``response_format`` plus null-padded fields), so the layer config
+# only receives the keys the runtime contract accepts.
+_AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS = (
+    "temperature",
+    "top_p",
+    "presence_penalty",
+    "frequency_penalty",
+    "max_tokens",
+)
+
+
+def _agent_model_settings(settings: Mapping[str, JsonValue]) -> dict[str, JsonValue] | None:
+    sanitized: dict[str, JsonValue] = {
+        key: settings[key] for key in _AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS if settings.get(key) is not None
+    }
+    stop = settings.get("stop")
+    if isinstance(stop, list) and stop:
+        sanitized["stop_sequences"] = stop
+    return sanitized or None
+
+
 class AgentBackendOutputConfig(BaseModel):
     """API-side structured output declaration for the conventional output layer.
 
@@ -169,11 +148,22 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
     idempotency_key: str | None = None
     output: AgentBackendOutputConfig | None = None
     tools: DifyPluginToolsLayerConfig | None = None
+    knowledge: DifyKnowledgeBaseLayerConfig | 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)
@@ -205,11 +195,21 @@ class AgentBackendAgentAppRunInput(BaseModel):
     idempotency_key: str | None = None
     output: AgentBackendOutputConfig | None = None
     tools: DifyPluginToolsLayerConfig | None = None
+    knowledge: DifyKnowledgeBaseLayerConfig | 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)
@@ -232,7 +232,7 @@ class AgentBackendRunRequestBuilder:
 
         Layer graph: optional Agent Soul system prompt → user prompt →
         execution context → optional history (multi-turn) → LLM → optional
-        plugin tools → optional structured output. Mirrors the workflow-node
+        plugin tools / knowledge search → optional structured output. Mirrors the workflow-node
         layer ordering minus the workflow-job / previous-node prompt.
         """
         layers: list[RunLayerSpec] = []
@@ -263,6 +263,19 @@ 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,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
+                    metadata=run_input.metadata,
+                    config=run_input.drive_config,
+                )
+            )
+
         if run_input.include_history:
             layers.append(
                 RunLayerSpec(
@@ -283,7 +296,7 @@ class AgentBackendRunRequestBuilder:
                     model_provider=run_input.model.model_provider,
                     model=run_input.model.model,
                     credentials=run_input.model.credentials,
-                    model_settings=run_input.model.model_settings or None,
+                    model_settings=_agent_model_settings(run_input.model.model_settings),
                 ),
             )
         )
@@ -299,13 +312,40 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.knowledge is not None and run_input.knowledge.dataset_ids:
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_KNOWLEDGE_BASE_LAYER_ID,
+                    type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
+                    metadata=run_input.metadata,
+                    config=run_input.knowledge,
+                )
+            )
+
+        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). The layer declares NoLayerDeps,
-            # so the spec carries no deps; shellctl connection is server-injected.
+            # Sandboxed bash workspace (dify.shell). Depends on execution_context
+            # so the agent server can mint per-command Agent Stub env, and on
+            # drive when present so that env points at /mnt/drive/<drive_ref>.
+            # shellctl connection itself is server-injected.
             layers.append(
                 RunLayerSpec(
                     name=DIFY_SHELL_LAYER_ID,
                     type=DIFY_SHELL_LAYER_TYPE_ID,
+                    deps=_shell_layer_deps(include_drive=run_input.drive_config is not None),
                     metadata=run_input.metadata,
                     config=run_input.shell_config or DifyShellLayerConfig(),
                 )
@@ -331,6 +371,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,
             ),
@@ -340,7 +381,7 @@ class AgentBackendRunRequestBuilder:
         self,
         *,
         session_snapshot: CompositorSessionSnapshot,
-        composition_layer_specs: list[CleanupLayerSpec],
+        runtime_layer_specs: list[RuntimeLayerSpec],
         idempotency_key: str | None = None,
         metadata: dict[str, JsonValue] | None = None,
     ) -> CreateRunRequest:
@@ -353,9 +394,9 @@ class AgentBackendRunRequestBuilder:
         composition and the snapshot before submission because their configs
         require credentials that are not persisted between runs.
         """
-        if not composition_layer_specs:
+        if not runtime_layer_specs:
             raise ValueError(
-                "build_cleanup_request requires composition_layer_specs; an empty "
+                "build_cleanup_request requires runtime_layer_specs; an empty "
                 "composition would fail the agent backend's snapshot validation."
             )
         request_metadata = dict(metadata or {})
@@ -368,9 +409,9 @@ class AgentBackendRunRequestBuilder:
                 metadata=dict(spec.metadata),
                 config=spec.config,
             )
-            for spec in composition_layer_specs
+            for spec in runtime_layer_specs
         ]
-        filtered_snapshot = _filter_snapshot_to_specs(session_snapshot, composition_layer_specs)
+        filtered_snapshot = _filter_snapshot_to_specs(session_snapshot, runtime_layer_specs)
         return CreateRunRequest(
             composition=RunComposition(layers=layers),
             purpose="workflow_node",
@@ -381,7 +422,12 @@ class AgentBackendRunRequestBuilder:
         )
 
     def build_for_workflow_node(self, run_input: AgentBackendWorkflowNodeRunInput) -> CreateRunRequest:
-        """Build a workflow Agent Node run request without defining another wire schema."""
+        """Build a workflow Agent Node run request without defining another wire schema.
+
+        Layer graph mirrors the workflow surface: prompts → execution context →
+        optional drive/history → LLM → optional plugin tools / knowledge search
+        → optional auxiliary layers such as ask_human, shell, and structured output.
+        """
         layers: list[RunLayerSpec] = []
         if run_input.agent_soul_prompt:
             layers.append(
@@ -416,6 +462,19 @@ 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,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
+                    metadata=run_input.metadata,
+                    config=run_input.drive_config,
+                )
+            )
+
         if run_input.include_history:
             layers.append(
                 RunLayerSpec(
@@ -437,7 +496,7 @@ class AgentBackendRunRequestBuilder:
                         model_provider=run_input.model.model_provider,
                         model=run_input.model.model,
                         credentials=run_input.model.credentials,
-                        model_settings=run_input.model.model_settings or None,
+                        model_settings=_agent_model_settings(run_input.model.model_settings),
                     ),
                 ),
             ]
@@ -454,13 +513,40 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.knowledge is not None and run_input.knowledge.dataset_ids:
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_KNOWLEDGE_BASE_LAYER_ID,
+                    type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
+                    metadata=run_input.metadata,
+                    config=run_input.knowledge,
+                )
+            )
+
+        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). The layer declares NoLayerDeps,
-            # so the spec carries no deps; shellctl connection is server-injected.
+            # Sandboxed bash workspace (dify.shell). Depends on execution_context
+            # so the agent server can mint per-command Agent Stub env, and on
+            # drive when present so that env points at /mnt/drive/<drive_ref>.
+            # shellctl connection itself is server-injected.
             layers.append(
                 RunLayerSpec(
                     name=DIFY_SHELL_LAYER_ID,
                     type=DIFY_SHELL_LAYER_TYPE_ID,
+                    deps=_shell_layer_deps(include_drive=run_input.drive_config is not None),
                     metadata=run_input.metadata,
                     config=run_input.shell_config or DifyShellLayerConfig(),
                 )
@@ -486,6 +572,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/clients/agent_backend/workspace_files_client.py

@@ -1,135 +0,0 @@
-"""API-side client for the agent backend's read-only workspace file endpoints.
-
-The agent backend exposes ``/workspaces/{session_id}/files{,/preview,/download}``
-to inspect a shell-layer sandbox workspace. This thin synchronous client proxies
-those reads for the console FS inspector and normalizes transport/HTTP failures
-into the API backend's ``AgentBackendError`` boundary, preserving the backend's
-status code and ``{code, message}`` detail so the controller can relay them.
-"""
-
-from __future__ import annotations
-
-import base64
-import binascii
-from dataclasses import dataclass
-from typing import Literal
-
-import httpx
-from pydantic import BaseModel
-
-from clients.agent_backend.errors import AgentBackendHTTPError, AgentBackendTransportError
-
-_DEFAULT_TIMEOUT_SECONDS = 30.0
-
-
-class WorkspaceFileEntry(BaseModel):
-    """One entry in a workspace directory listing."""
-
-    name: str
-    type: Literal["file", "dir", "symlink"]
-    size: int
-    mtime: int
-
-
-class WorkspaceListResult(BaseModel):
-    """Directory listing of a workspace path."""
-
-    path: str
-    entries: list[WorkspaceFileEntry]
-    truncated: bool
-
-
-class WorkspacePreviewResult(BaseModel):
-    """Inline preview of a workspace file."""
-
-    path: str
-    size: int
-    truncated: bool
-    binary: bool
-    text: str | None = None
-
-
-@dataclass(frozen=True, slots=True)
-class WorkspaceDownloadResult:
-    """Decoded bytes of a workspace file for download."""
-
-    path: str
-    size: int
-    truncated: bool
-    content: bytes
-
-
-class WorkspaceFilesBackendClient:
-    """Synchronous proxy to the agent backend workspace file endpoints."""
-
-    def __init__(
-        self,
-        base_url: str,
-        *,
-        timeout: float = _DEFAULT_TIMEOUT_SECONDS,
-        transport: httpx.BaseTransport | None = None,
-    ) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._timeout = timeout
-        self._transport = transport
-
-    def list_files(self, session_id: str, path: str) -> WorkspaceListResult:
-        data = self._get(f"/workspaces/{session_id}/files", params={"path": path})
-        return WorkspaceListResult.model_validate(data)
-
-    def preview(self, session_id: str, path: str) -> WorkspacePreviewResult:
-        data = self._get(f"/workspaces/{session_id}/files/preview", params={"path": path})
-        return WorkspacePreviewResult.model_validate(data)
-
-    def download(self, session_id: str, path: str) -> WorkspaceDownloadResult:
-        data = self._get(f"/workspaces/{session_id}/files/download", params={"path": path})
-        encoded = data.get("content_base64")
-        if not isinstance(encoded, str):
-            raise AgentBackendHTTPError("agent backend download response missing content", status_code=502, detail=data)
-        try:
-            content = base64.b64decode(encoded, validate=True)
-        except (binascii.Error, ValueError) as exc:
-            raise AgentBackendHTTPError(
-                "agent backend returned undecodable download content", status_code=502, detail=str(exc)
-            ) from exc
-        size = data.get("size")
-        return WorkspaceDownloadResult(
-            path=str(data.get("path", path)),
-            size=int(size) if isinstance(size, (int, float)) else len(content),
-            truncated=bool(data.get("truncated")),
-            content=content,
-        )
-
-    def _get(self, route: str, *, params: dict[str, str]) -> dict[str, object]:
-        url = f"{self._base_url}{route}"
-        try:
-            with httpx.Client(timeout=self._timeout, transport=self._transport, trust_env=False) as client:
-                response = client.get(url, params=params)
-        except httpx.HTTPError as exc:
-            raise AgentBackendTransportError(f"failed to reach agent backend workspace endpoint: {exc}") from exc
-        if response.status_code >= 400:
-            detail: object
-            try:
-                detail = response.json().get("detail", response.text)
-            except ValueError:
-                detail = response.text
-            raise AgentBackendHTTPError(
-                f"agent backend workspace request failed ({response.status_code})",
-                status_code=response.status_code,
-                detail=detail,
-            )
-        body = response.json()
-        if not isinstance(body, dict):
-            raise AgentBackendHTTPError(
-                "agent backend workspace response was not an object", status_code=502, detail=body
-            )
-        return body
-
-
-__all__ = [
-    "WorkspaceDownloadResult",
-    "WorkspaceFileEntry",
-    "WorkspaceFilesBackendClient",
-    "WorkspaceListResult",
-    "WorkspacePreviewResult",
-]

api/commands/__init__.py

@@ -22,8 +22,10 @@ from .plugin import (
     setup_system_trigger_oauth_client,
     transform_datasource_credentials,
 )
+from .rbac import migrate_member_roles_to_rbac
 from .retention import (
     archive_workflow_runs,
+    archive_workflow_runs_plan,
     clean_expired_messages,
     clean_workflow_runs,
     cleanup_orphaned_draft_variables,
@@ -50,6 +52,7 @@ from .vector import (
 __all__ = [
     "add_qdrant_index",
     "archive_workflow_runs",
+    "archive_workflow_runs_plan",
     "backfill_plugin_auto_upgrade",
     "clean_expired_messages",
     "clean_workflow_runs",
@@ -74,6 +77,7 @@ __all__ = [
     "migrate_annotation_vector_database",
     "migrate_data_for_plugin",
     "migrate_knowledge_vector_database",
+    "migrate_member_roles_to_rbac",
     "migrate_oss",
     "migration_data_wizard",
     "old_metadata_migration",

api/commands/account.py

@@ -25,7 +25,7 @@ def reset_password(email, new_password, password_confirm):
         return
     normalized_email = email.strip().lower()
 
-    account = AccountService.get_account_by_email_with_case_fallback(email.strip())
+    account = AccountService.get_account_by_email_with_case_fallback(db.session, email.strip())
 
     if not account:
         click.echo(click.style(f"Account not found for email: {email}", fg="red"))
@@ -67,7 +67,7 @@ def reset_email(email, new_email, email_confirm):
         return
     normalized_new_email = new_email.strip().lower()
 
-    account = AccountService.get_account_by_email_with_case_fallback(email.strip())
+    account = AccountService.get_account_by_email_with_case_fallback(db.session, email.strip())
 
     if not account:
         click.echo(click.style(f"Account not found for email: {email}", fg="red"))
@@ -133,8 +133,9 @@ def create_tenant(email: str, language: str | None = None, name: str | None = No
         password=new_password,
         language=language,
         create_workspace_required=False,
+        session=db.session,
     )
-    TenantService.create_owner_tenant_if_not_exist(account, name)
+    TenantService.create_owner_tenant_if_not_exist(account, name, session=db.session)
 
     click.echo(
         click.style(

api/commands/data_migrate.py

@@ -145,7 +145,7 @@ def legacy_model_types(
         option_name="--model-types",
     )
     selected_model_types = (
-        tuple(ModelType.value_of(model_type) for model_type in normalized_model_types)
+        tuple(ModelType(model_type) for model_type in normalized_model_types)
         if normalized_model_types
         else (
             ModelType.LLM,

api/commands/rbac.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import click
+from sqlalchemy import select
+
+from core.db.session_factory import session_factory
+from models import TenantAccountJoin, TenantAccountRole
+from services.enterprise.rbac_service import ListOption, RBACService
+
+
+def _resolve_builtin_role_id(tenant_id: str, operator_account_id: str, legacy_role: str) -> str:
+    """Resolve a legacy workspace role to the current tenant's builtin RBAC role id.
+
+    The migration replays the old `TenantAccountJoin.role` values onto the
+    RBAC member-role binding API. Builtin RBAC roles are tenant-scoped and
+    identified by runtime ids, so the command must look them up per tenant.
+    """
+    expected_builtin_tag = {
+        TenantAccountRole.OWNER.value: "owner",
+        TenantAccountRole.ADMIN.value: "admin",
+        TenantAccountRole.EDITOR.value: "editor",
+        TenantAccountRole.NORMAL.value: "normal",
+        TenantAccountRole.DATASET_OPERATOR.value: "dataset_operator",
+    }.get(legacy_role)
+    if not expected_builtin_tag:
+        raise ValueError(f"Unsupported legacy workspace role: {legacy_role}")
+
+    roles = RBACService.Roles.list(
+        tenant_id=tenant_id,
+        account_id=operator_account_id,
+        options=ListOption(page_number=1, results_per_page=100),
+    ).data
+    for role in roles:
+        if role.is_builtin and role.category == "global_system_default" and role.role_tag == expected_builtin_tag:
+            return str(role.id)
+
+    raise ValueError(f"Builtin RBAC role not found for tenant={tenant_id}, legacy_role={legacy_role}")
+
+
+@click.command(
+    "rbac-migrate-member-roles", help="Migrate legacy workspace member roles into RBAC member-role bindings."
+)
+@click.option("--tenant-id", help="Only migrate a single workspace.")
+@click.option("--dry-run", is_flag=True, default=False, help="Preview the migration without writing RBAC bindings.")
+def migrate_member_roles_to_rbac(tenant_id: str | None, dry_run: bool) -> None:
+    """Backfill RBAC member-role bindings from legacy `TenantAccountJoin.role` data.
+
+    This is an offline migration command for workspaces that already have
+    members in the legacy role model but need matching records in the RBAC
+    member-role binding store.
+    """
+    click.echo(click.style("Starting RBAC member-role migration.", fg="green"))
+
+    with session_factory.create_session() as session:
+        stmt = select(TenantAccountJoin).order_by(TenantAccountJoin.tenant_id.asc(), TenantAccountJoin.id.asc())
+        if tenant_id:
+            stmt = stmt.where(TenantAccountJoin.tenant_id == tenant_id)
+
+        joins = list(session.scalars(stmt).all())
+
+    if not joins:
+        click.echo(click.style("No workspace members found for migration.", fg="yellow"))
+        return
+
+    owner_account_by_tenant: dict[str, str] = {}
+    resolved_role_ids: dict[tuple[str, str], str] = {}
+    migrated_count = 0
+
+    for join in joins:
+        workspace_id = str(join.tenant_id)
+        member_account_id = str(join.account_id)
+        legacy_role = str(join.role)
+
+        if workspace_id not in owner_account_by_tenant:
+            owner_join = next(
+                (
+                    item
+                    for item in joins
+                    if str(item.tenant_id) == workspace_id and str(item.role) == TenantAccountRole.OWNER.value
+                ),
+                None,
+            )
+            if not owner_join:
+                raise ValueError(f"Workspace owner not found for tenant={workspace_id}")
+            owner_account_by_tenant[workspace_id] = str(owner_join.account_id)
+
+        operator_account_id = owner_account_by_tenant[workspace_id]
+        cache_key = (workspace_id, legacy_role)
+        if cache_key not in resolved_role_ids:
+            resolved_role_ids[cache_key] = _resolve_builtin_role_id(workspace_id, operator_account_id, legacy_role)
+
+        resolved_role_id = resolved_role_ids[cache_key]
+        click.echo(
+            f"tenant={workspace_id} member={member_account_id} "
+            f"legacy_role={legacy_role} -> rbac_role_id={resolved_role_id}"
+        )
+
+        if dry_run:
+            continue
+
+        RBACService.MemberRoles.replace(
+            tenant_id=workspace_id,
+            account_id=operator_account_id,
+            member_account_id=member_account_id,
+            role_ids=[resolved_role_id],
+        )
+        migrated_count += 1
+
+    if dry_run:
+        click.echo(click.style("Dry run completed. No RBAC bindings were written.", fg="yellow"))
+    else:
+        click.echo(click.style(f"RBAC member-role migration completed. Migrated {migrated_count} members.", fg="green"))

api/commands/retention.py

@@ -12,10 +12,160 @@ from services.clear_free_plan_tenant_expired_logs import ClearFreePlanTenantExpi
 from services.retention.conversation.messages_clean_policy import create_message_clean_policy
 from services.retention.conversation.messages_clean_service import MessagesCleanService
 from services.retention.workflow_run.clear_free_plan_expired_workflow_run_logs import WorkflowRunCleanup
+from services.retention.workflow_run.tenant_prefix import tenant_prefix_condition
 from tasks.remove_app_and_related_data_task import delete_draft_variables_batch
 
 logger = logging.getLogger(__name__)
 
+_HEX_PREFIXES = tuple("0123456789abcdef")
+
+
+class WorkflowRunArchivePlanRow(TypedDict):
+    tenant_prefix: str
+    total_tenants: int
+    workflow_runs: int
+    workflow_node_executions: int
+    paid_tenants: int
+    unpaid_tenants: int
+
+
+class WorkflowRunArchiveTenantPlan(TypedDict):
+    archive_tenant_ids: list[str] | None
+    paid_tenant_ids: list[str]
+    unpaid_tenant_ids: list[str]
+
+
+def _parse_tenant_prefixes(prefixes: str | None) -> list[str]:
+    if not prefixes:
+        return []
+
+    parsed = []
+    for raw_prefix in prefixes.split(","):
+        prefix = raw_prefix.strip().lower()
+        if not prefix:
+            continue
+        if len(prefix) != 1 or prefix not in _HEX_PREFIXES:
+            raise click.UsageError("--tenant-prefixes must be a comma-separated list of hex digits, e.g. 0,1,a,f.")
+        parsed.append(prefix)
+    return sorted(set(parsed))
+
+
+def _get_archive_candidate_tenant_ids_by_prefix(
+    prefix: str,
+    *,
+    start_from: datetime.datetime | None,
+    end_before: datetime.datetime,
+) -> list[str]:
+    from graphon.enums import WorkflowExecutionStatus
+    from models.workflow import WorkflowRun
+    from services.retention.workflow_run.archive_paid_plan_workflow_run import WorkflowRunArchiver
+
+    conditions = [
+        WorkflowRun.created_at < end_before,
+        WorkflowRun.status.in_(WorkflowExecutionStatus.ended_values()),
+        WorkflowRun.type.in_(WorkflowRunArchiver.ARCHIVED_TYPE),
+        tenant_prefix_condition(WorkflowRun.tenant_id, prefix),
+    ]
+    if start_from is not None:
+        conditions.append(WorkflowRun.created_at >= start_from)
+
+    tenant_ids = db.session.scalars(
+        sa.select(WorkflowRun.tenant_id).where(*conditions).distinct().order_by(WorkflowRun.tenant_id)
+    ).all()
+    return list(tenant_ids)
+
+
+def _filter_paid_workflow_archive_tenant_ids(tenant_ids: list[str]) -> tuple[list[str], list[str]]:
+    from configs import dify_config
+    from enums.cloud_plan import CloudPlan
+    from services.billing_service import BillingService
+
+    tenant_ids = sorted(set(tenant_ids))
+    if not tenant_ids:
+        return [], []
+    if not dify_config.BILLING_ENABLED:
+        return tenant_ids, []
+
+    plans = BillingService.get_plan_bulk_with_cache(tenant_ids)
+    paid_tenant_ids = [
+        tenant_id
+        for tenant_id in tenant_ids
+        if plans.get(tenant_id) and plans[tenant_id].get("plan") in (CloudPlan.PROFESSIONAL, CloudPlan.TEAM)
+    ]
+    unpaid_tenant_ids = sorted(set(tenant_ids) - set(paid_tenant_ids))
+    return paid_tenant_ids, unpaid_tenant_ids
+
+
+def _resolve_archive_tenant_ids_from_plan(
+    *,
+    tenant_ids: str | None,
+    tenant_prefixes: list[str],
+    start_from: datetime.datetime | None,
+    end_before: datetime.datetime,
+) -> WorkflowRunArchiveTenantPlan:
+    """
+    Resolve the archive tenant scope once before scanning workflow_runs.
+
+    Prefix rollout should use the tenant list collected by the same planning path, then archive by
+    tenant_id IN (...). Scanning workflow_runs with a tenant prefix range in every archive run is too expensive on
+    the large production table this command is meant to shrink.
+    """
+    if tenant_ids:
+        requested_tenant_ids = [tid.strip() for tid in tenant_ids.split(",") if tid.strip()]
+    elif tenant_prefixes:
+        requested_tenant_ids = []
+        for prefix in tenant_prefixes:
+            requested_tenant_ids.extend(
+                _get_archive_candidate_tenant_ids_by_prefix(
+                    prefix,
+                    start_from=start_from,
+                    end_before=end_before,
+                )
+            )
+    else:
+        return WorkflowRunArchiveTenantPlan(
+            archive_tenant_ids=None,
+            paid_tenant_ids=[],
+            unpaid_tenant_ids=[],
+        )
+
+    paid_tenant_ids, unpaid_tenant_ids = _filter_paid_workflow_archive_tenant_ids(requested_tenant_ids)
+    return WorkflowRunArchiveTenantPlan(
+        archive_tenant_ids=paid_tenant_ids,
+        paid_tenant_ids=paid_tenant_ids,
+        unpaid_tenant_ids=unpaid_tenant_ids,
+    )
+
+
+def _resolve_archive_time_range(
+    *,
+    before_days: int,
+    from_days_ago: int | None,
+    to_days_ago: int | None,
+    start_from: datetime.datetime | None,
+    end_before: datetime.datetime | None,
+) -> tuple[int, datetime.datetime | None, datetime.datetime | None]:
+    if (start_from is None) ^ (end_before is None):
+        raise click.UsageError("--start-from and --end-before must be provided together.")
+
+    if (from_days_ago is None) ^ (to_days_ago is None):
+        raise click.UsageError("--from-days-ago and --to-days-ago must be provided together.")
+
+    if from_days_ago is not None and to_days_ago is not None:
+        if start_from or end_before:
+            raise click.UsageError("Choose either day offsets or explicit dates, not both.")
+        if from_days_ago <= to_days_ago:
+            raise click.UsageError("--from-days-ago must be greater than --to-days-ago.")
+        now = datetime.datetime.now()
+        start_from = now - datetime.timedelta(days=from_days_ago)
+        end_before = now - datetime.timedelta(days=to_days_ago)
+        before_days = 0
+
+    if start_from and end_before and start_from >= end_before:
+        raise click.UsageError("--start-from must be earlier than --end-before.")
+
+    return before_days, start_from, end_before
+
 
 @click.command("clear-free-plan-tenant-expired-logs", help="Clear free plan tenant expired logs.")
 @click.option("--days", prompt=True, help="The days to clear free plan tenant expired logs.", default=30)
@@ -139,11 +289,143 @@ def clean_workflow_runs(
     )
 
 
+@click.command(
+    "archive-workflow-runs-plan",
+    help="Plan workflow run archive rollout by tenant ID first hex digit.",
+)
+@click.option("--before-days", default=90, show_default=True, help="Plan runs older than N days.")
+@click.option(
+    "--from-days-ago",
+    default=None,
+    type=click.IntRange(min=0),
+    help="Lower bound in days ago (older). Must be paired with --to-days-ago.",
+)
+@click.option(
+    "--to-days-ago",
+    default=None,
+    type=click.IntRange(min=0),
+    help="Upper bound in days ago (newer). Must be paired with --from-days-ago.",
+)
+@click.option(
+    "--start-from",
+    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    default=None,
+    help="Plan runs created at or after this timestamp (UTC if no timezone).",
+)
+@click.option(
+    "--end-before",
+    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    default=None,
+    help="Plan runs created before this timestamp (UTC if no timezone).",
+)
+@click.option(
+    "--include-archived",
+    is_flag=True,
+    help="Compatibility no-op for V2 bundle archive; plan counts source rows in the requested window.",
+)
+def archive_workflow_runs_plan(
+    before_days: int,
+    from_days_ago: int | None,
+    to_days_ago: int | None,
+    start_from: datetime.datetime | None,
+    end_before: datetime.datetime | None,
+    include_archived: bool,
+):
+    """
+    Print the 16 tenant-prefix rollout rows used to choose archive execution order.
+
+    Counts use the same workflow run eligibility as archive-workflow-runs: ended runs,
+    supported workflow types, and the requested created_at window. V2 bundle archive
+    does not maintain per-run archive logs, so this plan reports source-table volume.
+    """
+    from graphon.enums import WorkflowExecutionStatus
+    from models.workflow import WorkflowNodeExecutionModel, WorkflowRun
+    from services.retention.workflow_run.archive_paid_plan_workflow_run import WorkflowRunArchiver
+
+    before_days, start_from, end_before = _resolve_archive_time_range(
+        before_days=before_days,
+        from_days_ago=from_days_ago,
+        to_days_ago=to_days_ago,
+        start_from=start_from,
+        end_before=end_before,
+    )
+    plan_end_before = end_before or datetime.datetime.now(datetime.UTC) - datetime.timedelta(days=before_days)
+    if include_archived:
+        click.echo(click.style("--include-archived is a no-op for V2 bundle archive plans.", fg="yellow"))
+
+    rows: list[WorkflowRunArchivePlanRow] = []
+    for prefix in _HEX_PREFIXES:
+        tenant_ids = _get_archive_candidate_tenant_ids_by_prefix(
+            prefix,
+            start_from=start_from,
+            end_before=plan_end_before,
+        )
+        total_tenants = len(tenant_ids)
+        paid_tenant_ids, unpaid_tenant_ids = _filter_paid_workflow_archive_tenant_ids(tenant_ids)
+
+        run_conditions = [
+            WorkflowRun.created_at < plan_end_before,
+            WorkflowRun.status.in_(WorkflowExecutionStatus.ended_values()),
+            WorkflowRun.type.in_(WorkflowRunArchiver.ARCHIVED_TYPE),
+            tenant_prefix_condition(WorkflowRun.tenant_id, prefix),
+        ]
+        if start_from is not None:
+            run_conditions.append(WorkflowRun.created_at >= start_from)
+        workflow_runs = (
+            db.session.scalar(sa.select(sa.func.count()).select_from(WorkflowRun).where(*run_conditions)) or 0
+        )
+        candidate_runs = sa.select(WorkflowRun.id).where(*run_conditions).subquery()
+        workflow_node_executions = (
+            db.session.scalar(
+                sa.select(sa.func.count())
+                .select_from(WorkflowNodeExecutionModel)
+                .join(candidate_runs, WorkflowNodeExecutionModel.workflow_run_id == candidate_runs.c.id)
+            )
+            or 0
+        )
+
+        rows.append(
+            WorkflowRunArchivePlanRow(
+                tenant_prefix=prefix,
+                total_tenants=total_tenants,
+                workflow_runs=workflow_runs,
+                workflow_node_executions=workflow_node_executions,
+                paid_tenants=len(paid_tenant_ids),
+                unpaid_tenants=len(unpaid_tenant_ids),
+            )
+        )
+
+    click.echo(
+        click.style(
+            f"Workflow archive plan for runs before {plan_end_before.isoformat()}"
+            f"{f' and at/after {start_from.isoformat()}' if start_from else ''}.",
+            fg="white",
+        )
+    )
+    click.echo("tenant_prefix,total_tenants,workflow_runs,workflow_node_executions,paid_tenants,unpaid_tenants")
+    for row in rows:
+        click.echo(
+            f"{row['tenant_prefix']},{row['total_tenants']},{row['workflow_runs']},"
+            f"{row['workflow_node_executions']},{row['paid_tenants']},{row['unpaid_tenants']}"
+        )
+
+    ordered_rows = sorted(
+        rows,
+        key=lambda row: (row["workflow_runs"] + row["workflow_node_executions"], row["tenant_prefix"]),
+    )
+    click.echo("suggested_execution_order=" + ",".join(row["tenant_prefix"] for row in ordered_rows))
+
+
 @click.command(
     "archive-workflow-runs",
     help="Archive workflow runs for paid plan tenants to S3-compatible storage.",
 )
 @click.option("--tenant-ids", default=None, help="Optional comma-separated tenant IDs for grayscale rollout.")
+@click.option(
+    "--tenant-prefixes",
+    default=None,
+    help="Optional comma-separated tenant ID first hex digits for rollout waves, e.g. 0,1,a,f.",
+)
 @click.option("--before-days", default=90, show_default=True, help="Archive runs older than N days.")
 @click.option(
     "--from-days-ago",
@@ -169,13 +451,36 @@ def clean_workflow_runs(
     default=None,
     help="Archive runs created before this timestamp (UTC if no timezone).",
 )
-@click.option("--batch-size", default=100, show_default=True, help="Batch size for processing.")
-@click.option("--workers", default=1, show_default=True, type=int, help="Concurrent workflow runs to archive.")
+@click.option("--batch-size", default=100, show_default=True, help="Maximum workflow runs per archive bundle.")
+@click.option(
+    "--workers",
+    default=1,
+    show_default=True,
+    type=int,
+    help="Reserved; bundle archive currently runs serially.",
+)
+@click.option(
+    "--run-shard-index",
+    default=None,
+    type=click.IntRange(min=0),
+    help="Zero-based workflow run shard index for parallel cron jobs. Must be paired with --run-shard-total.",
+)
+@click.option(
+    "--run-shard-total",
+    default=None,
+    type=click.IntRange(min=1, max=16),
+    help="Total workflow run shard count for parallel cron jobs. Must be paired with --run-shard-index.",
+)
 @click.option("--limit", default=None, type=int, help="Maximum number of runs to archive.")
 @click.option("--dry-run", is_flag=True, help="Preview without archiving.")
-@click.option("--delete-after-archive", is_flag=True, help="Delete runs and related data after archiving.")
+@click.option(
+    "--delete-after-archive",
+    is_flag=True,
+    help="Not supported by bundle archive; use a separate bundle delete workflow after validation.",
+)
 def archive_workflow_runs(
     tenant_ids: str | None,
+    tenant_prefixes: str | None,
     before_days: int,
     from_days_ago: int | None,
     to_days_ago: int | None,
@@ -183,6 +488,8 @@ def archive_workflow_runs(
     end_before: datetime.datetime | None,
     batch_size: int,
     workers: int,
+    run_shard_index: int | None,
+    run_shard_total: int | None,
     limit: int | None,
     dry_run: bool,
     delete_after_archive: bool,
@@ -190,14 +497,19 @@ def archive_workflow_runs(
     """
     Archive workflow runs for paid plan tenants older than the specified days.
 
-    This command archives the following tables to storage:
+    This command writes V2 tenant/month/shard archive bundles. Each bundle contains Parquet snapshots from:
+    - workflow_runs
+    - workflow_app_logs
     - workflow_node_executions
     - workflow_node_execution_offload
     - workflow_pauses
     - workflow_pause_reasons
     - workflow_trigger_logs
 
-    The workflow_runs and workflow_app_logs tables are preserved for UI listing.
+    Source database rows are always preserved by archive. Deletion must be handled by
+    a separate bundle-level delete workflow after manifest, checksum, row-count, and
+    restore-sampling validation. In --dry-run mode, no storage or database writes
+    happen; the command estimates per-table Parquet bytes and object size instead.
     """
     from services.retention.workflow_run.archive_paid_plan_workflow_run import WorkflowRunArchiver
 
@@ -209,32 +521,58 @@ def archive_workflow_runs(
         )
     )
 
-    if (start_from is None) ^ (end_before is None):
-        click.echo(click.style("start-from and end-before must be provided together.", fg="red"))
-        return
-
-    if (from_days_ago is None) ^ (to_days_ago is None):
-        click.echo(click.style("from-days-ago and to-days-ago must be provided together.", fg="red"))
-        return
-
-    if from_days_ago is not None and to_days_ago is not None:
-        if start_from or end_before:
-            click.echo(click.style("Choose either day offsets or explicit dates, not both.", fg="red"))
-            return
-        if from_days_ago <= to_days_ago:
-            click.echo(click.style("from-days-ago must be greater than to-days-ago.", fg="red"))
-            return
-        now = datetime.datetime.now()
-        start_from = now - datetime.timedelta(days=from_days_ago)
-        end_before = now - datetime.timedelta(days=to_days_ago)
-        before_days = 0
-
-    if start_from and end_before and start_from >= end_before:
-        click.echo(click.style("start-from must be earlier than end-before.", fg="red"))
+    try:
+        before_days, start_from, end_before = _resolve_archive_time_range(
+            before_days=before_days,
+            from_days_ago=from_days_ago,
+            to_days_ago=to_days_ago,
+            start_from=start_from,
+            end_before=end_before,
+        )
+        parsed_tenant_prefixes = _parse_tenant_prefixes(tenant_prefixes)
+    except click.UsageError as e:
+        click.echo(click.style(e.message, fg="red"))
         return
+    plan_end_before = end_before or datetime.datetime.now(datetime.UTC) - datetime.timedelta(days=before_days)
     if workers < 1:
         click.echo(click.style("workers must be at least 1.", fg="red"))
         return
+    if (run_shard_index is None) ^ (run_shard_total is None):
+        click.echo(click.style("run-shard-index and run-shard-total must be provided together.", fg="red"))
+        return
+    if run_shard_index is not None and run_shard_total is not None and run_shard_index >= run_shard_total:
+        click.echo(click.style("run-shard-index must be less than run-shard-total.", fg="red"))
+        return
+    if delete_after_archive:
+        click.echo(click.style("delete-after-archive is not supported by bundle archive.", fg="red"))
+        return
+
+    try:
+        tenant_plan = _resolve_archive_tenant_ids_from_plan(
+            tenant_ids=tenant_ids,
+            tenant_prefixes=parsed_tenant_prefixes,
+            start_from=start_from,
+            end_before=plan_end_before,
+        )
+    except Exception:
+        logger.exception("Failed to resolve workflow archive tenant plan")
+        click.echo(click.style("Failed to resolve workflow archive tenant plan.", fg="red"))
+        return
+
+    planned_tenant_ids = tenant_plan["archive_tenant_ids"]
+    planned_paid_tenant_ids = tenant_plan["paid_tenant_ids"] if planned_tenant_ids is not None else None
+    paid_tenants = len(tenant_plan["paid_tenant_ids"])
+    unpaid_tenants = len(tenant_plan["unpaid_tenant_ids"])
+    if planned_tenant_ids is not None:
+        click.echo(
+            click.style(
+                f"Resolved archive tenant plan: paid_tenants={paid_tenants}, unpaid_tenants={unpaid_tenants}.",
+                fg="white",
+            )
+        )
+        if not planned_tenant_ids:
+            click.echo(click.style("No paid tenants matched the archive plan; nothing to archive.", fg="yellow"))
+            return
 
     archiver = WorkflowRunArchiver(
         days=before_days,
@@ -242,7 +580,11 @@ def archive_workflow_runs(
         start_from=start_from,
         end_before=end_before,
         workers=workers,
-        tenant_ids=[tid.strip() for tid in tenant_ids.split(",")] if tenant_ids else None,
+        tenant_ids=planned_tenant_ids,
+        tenant_prefixes=parsed_tenant_prefixes,
+        paid_tenant_ids=planned_paid_tenant_ids,
+        run_shard_index=run_shard_index,
+        run_shard_total=run_shard_total,
         limit=limit,
         dry_run=dry_run,
         delete_after_archive=delete_after_archive,
@@ -252,7 +594,9 @@ def archive_workflow_runs(
         click.style(
             f"Summary: processed={summary.total_runs_processed}, archived={summary.runs_archived}, "
             f"skipped={summary.runs_skipped}, failed={summary.runs_failed}, "
-            f"time={summary.total_elapsed_time:.2f}s",
+            f"bundles_archived={summary.bundles_archived}, bundles_skipped={summary.bundles_skipped}, "
+            f"bundles_failed={summary.bundles_failed}, "
+            f"object_size_bytes={summary.total_object_size_bytes}, time={summary.total_elapsed_time:.2f}s",
             fg="cyan",
         )
     )
@@ -268,6 +612,52 @@ def archive_workflow_runs(
     )
 
 
+def _echo_bundle_archive_operation_summary(summary) -> None:
+    status = "completed successfully" if summary.bundles_failed == 0 else "completed with failures"
+    fg = "green" if summary.bundles_failed == 0 else "red"
+    click.echo(
+        click.style(
+            f"{summary.operation} {status}. "
+            f"bundles_success={summary.bundles_succeeded} bundles_failed={summary.bundles_failed} "
+            f"runs={summary.runs_processed} rows={summary.rows_processed} "
+            f"archive_bytes={summary.archive_bytes} duration={summary.elapsed_time:.2f}s "
+            f"validation_time={summary.validation_time:.2f}s "
+            f"runs_per_second={summary.runs_per_second:.2f} rows_per_second={summary.rows_per_second:.2f} "
+            f"bytes_per_second={summary.bytes_per_second:.2f}",
+            fg=fg,
+        )
+    )
+    click.echo(click.style("table,row_count", fg="white"))
+    for table_name in [
+        "workflow_runs",
+        "workflow_app_logs",
+        "workflow_node_executions",
+        "workflow_node_execution_offload",
+        "workflow_pauses",
+        "workflow_pause_reasons",
+        "workflow_trigger_logs",
+    ]:
+        click.echo(f"{table_name},{summary.table_counts.get(table_name, 0)}")
+    for result in summary.results:
+        if result.success:
+            click.echo(
+                click.style(
+                    f"  bundle={result.bundle_id} tenant={result.tenant_id} runs={result.run_count} "
+                    f"rows={result.row_count} archive_bytes={result.archive_bytes} "
+                    f"time={result.elapsed_time:.2f}s validation={result.validation_time:.2f}s",
+                    fg="white",
+                )
+            )
+        else:
+            click.echo(
+                click.style(
+                    f"  failed bundle={result.bundle_id} tenant={result.tenant_id} "
+                    f"object_prefix={result.object_prefix} error={result.error}",
+                    fg="red",
+                )
+            )
+
+
 @click.command(
     "restore-workflow-runs",
     help="Restore archived workflow runs from S3-compatible storage.",
@@ -290,8 +680,8 @@ def archive_workflow_runs(
     default=None,
     help="Optional upper bound (exclusive) for created_at; must be paired with --start-from.",
 )
-@click.option("--workers", default=1, show_default=True, type=int, help="Concurrent workflow runs to restore.")
-@click.option("--limit", type=int, default=100, show_default=True, help="Maximum number of runs to restore.")
+@click.option("--workers", default=1, show_default=True, type=int, help="V1 --run-id compatibility only.")
+@click.option("--limit", type=int, default=100, show_default=True, help="Maximum number of V2 bundles to restore.")
 @click.option("--dry-run", is_flag=True, help="Preview without restoring.")
 def restore_workflow_runs(
     tenant_ids: str | None,
@@ -303,15 +693,18 @@ def restore_workflow_runs(
     dry_run: bool,
 ):
     """
-    Restore an archived workflow run from storage to the database.
+    Restore archived workflow runs from storage to the database.
 
-    This restores the following tables:
+    Batch restore uses V2 bundle metadata and validates archive objects before writing source rows. This restores:
+    - workflow_runs
+    - workflow_app_logs
     - workflow_node_executions
     - workflow_node_execution_offload
     - workflow_pauses
     - workflow_pause_reasons
     - workflow_trigger_logs
     """
+    from services.retention.workflow_run.bundle_archive_maintenance import WorkflowRunBundleArchiveMaintenance
     from services.retention.workflow_run.restore_archived_workflow_run import WorkflowRunRestore
 
     parsed_tenant_ids = None
@@ -335,39 +728,46 @@ def restore_workflow_runs(
         )
     )
 
-    restorer = WorkflowRunRestore(dry_run=dry_run, workers=workers)
     if run_id:
+        restorer = WorkflowRunRestore(dry_run=dry_run, workers=workers)
         results = [restorer.restore_by_run_id(run_id)]
-    else:
-        assert start_from is not None
-        assert end_before is not None
-        results = restorer.restore_batch(
-            parsed_tenant_ids,
-            start_date=start_from,
-            end_date=end_before,
-            limit=limit,
-        )
+        end_time = datetime.datetime.now(datetime.UTC)
+        elapsed = end_time - start_time
 
-    end_time = datetime.datetime.now(datetime.UTC)
-    elapsed = end_time - start_time
+        successes = sum(1 for result in results if result.success)
+        failures = len(results) - successes
 
-    successes = sum(1 for result in results if result.success)
-    failures = len(results) - successes
-
-    if failures == 0:
-        click.echo(
-            click.style(
-                f"Restore completed successfully. success={successes} duration={elapsed}",
-                fg="green",
+        if failures == 0:
+            click.echo(
+                click.style(
+                    f"Restore completed successfully. success={successes} duration={elapsed}",
+                    fg="green",
+                )
             )
-        )
-    else:
-        click.echo(
-            click.style(
-                f"Restore completed with failures. success={successes} failed={failures} duration={elapsed}",
-                fg="red",
+        else:
+            click.echo(
+                click.style(
+                    f"Restore completed with failures. success={successes} failed={failures} duration={elapsed}",
+                    fg="red",
+                )
             )
+        return
+
+    if workers != 1:
+        click.echo(
+            click.style("--workers is ignored for V2 bundle restore; bundles are processed serially.", fg="yellow")
         )
+    assert start_from is not None
+    assert end_before is not None
+    bundle_restorer = WorkflowRunBundleArchiveMaintenance(dry_run=dry_run, strict_content_validation=True)
+    summary = bundle_restorer.restore_batch(
+        tenant_ids=parsed_tenant_ids,
+        start_date=start_from,
+        end_date=end_before,
+        limit=limit,
+    )
+    _echo_bundle_archive_operation_summary(summary)
+    return
 
 
 @click.command(
@@ -392,8 +792,20 @@ def restore_workflow_runs(
     default=None,
     help="Optional upper bound (exclusive) for created_at; must be paired with --start-from.",
 )
-@click.option("--limit", type=int, default=100, show_default=True, help="Maximum number of runs to delete.")
+@click.option("--limit", type=int, default=100, show_default=True, help="Maximum number of V2 bundles to delete.")
 @click.option("--dry-run", is_flag=True, help="Preview without deleting.")
+@click.option(
+    "--skip-bad-archives",
+    is_flag=True,
+    help="Continue batch deletion when one archive object fails validation.",
+)
+@click.option(
+    "--restore-sample-interval",
+    type=int,
+    default=0,
+    show_default=True,
+    help="Run restore dry-run after every N successful deletes; 0 disables restore sampling.",
+)
 def delete_archived_workflow_runs(
     tenant_ids: str | None,
     run_id: str | None,
@@ -401,10 +813,16 @@ def delete_archived_workflow_runs(
     end_before: datetime.datetime | None,
     limit: int,
     dry_run: bool,
+    skip_bad_archives: bool,
+    restore_sample_interval: int,
 ):
     """
     Delete archived workflow runs from the database.
+
+    Batch delete uses V2 bundle metadata and validates object existence, manifest schema, object size, checksum, row
+    counts, and source/archive content checksums before deleting source rows. `--run-id` keeps the V1 per-run path.
     """
+    from services.retention.workflow_run.bundle_archive_maintenance import WorkflowRunBundleArchiveMaintenance
     from services.retention.workflow_run.delete_archived_workflow_run import ArchivedWorkflowRunDeletion
 
     parsed_tenant_ids = None
@@ -417,6 +835,8 @@ def delete_archived_workflow_runs(
         raise click.UsageError("--start-from and --end-before must be provided together.")
     if run_id is None and (start_from is None or end_before is None):
         raise click.UsageError("--start-from and --end-before are required for batch delete.")
+    if restore_sample_interval < 0:
+        raise click.BadParameter("restore-sample-interval must be >= 0")
 
     start_time = datetime.datetime.now(datetime.UTC)
     target_desc = f"workflow run {run_id}" if run_id else "workflow runs"
@@ -427,56 +847,85 @@ def delete_archived_workflow_runs(
         )
     )
 
-    deleter = ArchivedWorkflowRunDeletion(dry_run=dry_run)
     if run_id:
-        results = [deleter.delete_by_run_id(run_id)]
-    else:
-        assert start_from is not None
-        assert end_before is not None
-        results = deleter.delete_batch(
-            parsed_tenant_ids,
-            start_date=start_from,
-            end_date=end_before,
-            limit=limit,
+        deleter = ArchivedWorkflowRunDeletion(
+            dry_run=dry_run,
+            skip_bad_archives=skip_bad_archives,
+            restore_sample_interval=restore_sample_interval,
         )
+        results = [deleter.delete_by_run_id(run_id)]
+        for result in results:
+            if result.success:
+                click.echo(
+                    click.style(
+                        f"{'[DRY RUN] Would delete' if dry_run else 'Deleted'} "
+                        f"workflow run {result.run_id} (tenant={result.tenant_id}, "
+                        f"archive_key={result.archive_key}, counts={result.validated_counts})",
+                        fg="green",
+                    )
+                )
+                if result.restore_sampled:
+                    sample_status = "passed" if result.restore_sample_success else "failed"
+                    click.echo(
+                        click.style(
+                            f"  restore dry-run sample {sample_status} for workflow run {result.run_id}",
+                            fg="green" if result.restore_sample_success else "red",
+                        )
+                    )
+            else:
+                click.echo(
+                    click.style(
+                        f"Failed to delete workflow run {result.run_id}: {result.error}",
+                        fg="red",
+                    )
+                )
+                click.echo(
+                    click.style(
+                        "  runbook: pause this delete window, verify archive storage object and manifest/checksum, "
+                        "retry the same run after fixing storage or DB drift, or rerun with --skip-bad-archives "
+                        "to quarantine this run and continue the batch.",
+                        fg="yellow",
+                    )
+                )
 
-    for result in results:
-        if result.success:
+        end_time = datetime.datetime.now(datetime.UTC)
+        elapsed = end_time - start_time
+
+        successes = sum(1 for result in results if result.success)
+        failures = len(results) - successes
+
+        if failures == 0:
             click.echo(
                 click.style(
-                    f"{'[DRY RUN] Would delete' if dry_run else 'Deleted'} "
-                    f"workflow run {result.run_id} (tenant={result.tenant_id})",
+                    f"Delete completed successfully. success={successes} duration={elapsed}",
                     fg="green",
                 )
             )
         else:
             click.echo(
                 click.style(
-                    f"Failed to delete workflow run {result.run_id}: {result.error}",
+                    f"Delete completed with failures. success={successes} failed={failures} duration={elapsed}",
                     fg="red",
                 )
             )
+        return
 
-    end_time = datetime.datetime.now(datetime.UTC)
-    elapsed = end_time - start_time
-
-    successes = sum(1 for result in results if result.success)
-    failures = len(results) - successes
-
-    if failures == 0:
-        click.echo(
-            click.style(
-                f"Delete completed successfully. success={successes} duration={elapsed}",
-                fg="green",
-            )
-        )
-    else:
-        click.echo(
-            click.style(
-                f"Delete completed with failures. success={successes} failed={failures} duration={elapsed}",
-                fg="red",
-            )
-        )
+    if restore_sample_interval:
+        click.echo(click.style("--restore-sample-interval is ignored for V2 bundle delete.", fg="yellow"))
+    assert start_from is not None
+    assert end_before is not None
+    bundle_deleter = WorkflowRunBundleArchiveMaintenance(
+        dry_run=dry_run,
+        strict_content_validation=True,
+        stop_on_error=not skip_bad_archives,
+    )
+    summary = bundle_deleter.delete_batch(
+        tenant_ids=parsed_tenant_ids,
+        start_date=start_from,
+        end_date=end_before,
+        limit=limit,
+    )
+    _echo_bundle_archive_operation_summary(summary)
 
 
 def _find_orphaned_draft_variables(batch_size: int = 1000) -> list[str]:

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(
@@ -29,6 +29,11 @@ class EnterpriseFeatureConfig(BaseSettings):
         "This helps gain runtime performance by trading off consistency.",
     )
 
+    RBAC_ENABLED: bool = Field(
+        description="Enable enterprise RBAC APIs. When disabled, compatibility responses fall back to legacy roles.",
+        default=False,
+    )
+
 
 class EnterpriseTelemetryConfig(BaseSettings):
     """

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/feature/__init__.py

@@ -943,9 +943,10 @@ class AuthConfig(BaseSettings):
         default=True,
     )
 
-    OPENAPI_RATE_LIMIT_PER_TOKEN: PositiveInt = Field(
+    OPENAPI_RATE_LIMIT_PER_TOKEN: NonNegativeInt = Field(
         description="Per-token rate limit on /openapi/v1/* (requests per minute). "
-        "Bucket keyed on sha256(token), shared across api replicas via Redis.",
+        "Bucket keyed on sha256(token), shared across api replicas via Redis. "
+        "Set to 0 to disable the per-token limit entirely.",
         default=60,
     )
 
@@ -1072,6 +1073,12 @@ class MailConfig(BaseSettings):
         default=None,
     )
 
+
+class HomepageConfig(BaseSettings):
+    """
+    Configuration for homepage feature toggles exposed through system features.
+    """
+
     ENABLE_TRIAL_APP: bool = Field(
         description="Enable trial app",
         default=False,
@@ -1082,6 +1089,11 @@ class MailConfig(BaseSettings):
         default=False,
     )
 
+    ENABLE_LEARN_APP: bool = Field(
+        description="Enable Learn App",
+        default=True,
+    )
+
 
 class RagEtlConfig(BaseSettings):
     """
@@ -1488,6 +1500,7 @@ class FeatureConfig(
     EndpointConfig,
     FileAccessConfig,
     FileUploadConfig,
+    HomepageConfig,
     HttpConfig,
     InnerAPIConfig,
     IndexingConfig,

api/configs/middleware/cache/redis_pubsub_config.py

@@ -2,7 +2,6 @@ from typing import Literal, Protocol, cast
 from urllib.parse import quote_plus, urlunparse
 
 from pydantic import AliasChoices, Field
-from pydantic.types import NonNegativeInt
 from pydantic_settings import BaseSettings
 
 
@@ -71,24 +70,6 @@ class RedisPubSubConfig(BaseSettings):
         default=600,
     )
 
-    PUBSUB_LISTENER_JOIN_TIMEOUT_MS: NonNegativeInt = Field(
-        validation_alias=AliasChoices("EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS", "PUBSUB_LISTENER_JOIN_TIMEOUT_MS"),
-        description=(
-            "Maximum time (milliseconds) that ``Subscription.close()`` waits for its listener thread to "
-            "finish before returning. Bounds the tail latency between a terminal event being delivered to "
-            "an SSE client and the response stream actually closing.\n\n"
-            "The listener thread blocks on a polling read (XREAD BLOCK for streams, get_message timeout "
-            "for pubsub/sharded) with a fixed 1s window, so close() naturally has to wait up to ~1s for "
-            "the thread to notice the subscription was closed. Setting this lower (e.g. 100) lets close() "
-            "return promptly while the daemon listener thread cleans itself up on the next poll "
-            "boundary - safe because the listener holds no critical state and exits within one poll "
-            "window. Setting it higher (e.g. 5000) gives the listener more grace before close() gives up "
-            "and logs a warning. Default 2000ms preserves the pre-change behaviour.\n\n"
-            "Also accepts ENV: EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS."
-        ),
-        default=2000,
-    )
-
     def _build_default_pubsub_url(self) -> str:
         defaults = _redis_defaults(self)
         if not defaults.REDIS_HOST or not defaults.REDIS_PORT:

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/context/execution_context.py

@@ -7,7 +7,6 @@ consumes injected context managers when it needs to preserve thread-local state.
 
 import contextvars
 import threading
-from abc import ABC, abstractmethod
 from collections.abc import Callable, Generator
 from contextlib import AbstractContextManager, contextmanager
 from typing import Any, Protocol, final, override, runtime_checkable
@@ -15,28 +14,25 @@ from typing import Any, Protocol, final, override, runtime_checkable
 from pydantic import BaseModel
 
 
-class AppContext(ABC):
+class AppContext(Protocol):
     """
-    Abstract application context interface.
+    Application context interface.
 
     Application adapters can implement this to restore framework-specific state
     such as Flask app context around worker execution.
     """
 
-    @abstractmethod
     def get_config(self, key: str, default: Any = None) -> Any:
         """Get configuration value by key."""
-        raise NotImplementedError
+        ...
 
-    @abstractmethod
     def get_extension(self, name: str) -> Any:
         """Get application extension by name."""
-        raise NotImplementedError
+        ...
 
-    @abstractmethod
     def enter(self) -> AbstractContextManager[None]:
         """Enter the application context."""
-        raise NotImplementedError
+        ...
 
 
 @runtime_checkable

api/controllers/common/app_access.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from services.enterprise import rbac_service as enterprise_rbac_service
+
+if TYPE_CHECKING:
+    from services.app_service import AppListBaseParams
+    from services.enterprise.rbac_service import MyPermissionsResponse
+
+# Permission keys (dot-notation, from MyPermissionsResponse) that grant
+# list/preview access to an app. Keep this the single source of truth for both
+# the console and OpenAPI app-list endpoints.
+APP_LIST_PERMISSION_KEYS: frozenset[str] = frozenset({"app.preview", "app.acl.preview", "app.full_access"})
+
+# Workspace permission key that lets a caller see apps they maintain even when
+# those apps are not in their preview whitelist.
+_MANAGE_OWN_APPS_PERMISSION_KEY = "app.create_and_management"
+
+
+def has_app_list_permission(permission_keys: Sequence[str]) -> bool:
+    """Return True if any of ``permission_keys`` grants app list/preview access."""
+    return any(permission_key in APP_LIST_PERMISSION_KEYS for permission_key in permission_keys)
+
+
+@dataclass(frozen=True)
+class AppAccessFilter:
+    """Resolved RBAC visibility for app list/read endpoints.
+
+    ``accessible_app_ids`` of ``None`` means the caller can see every app in the
+    workspace (unrestricted). Otherwise it is the exact set of app ids the
+    caller may preview; combined with ``can_manage_own_apps`` it also covers
+    apps the caller maintains.
+    """
+
+    accessible_app_ids: set[str] | None
+    can_manage_own_apps: bool
+
+    @classmethod
+    def unrestricted(cls) -> AppAccessFilter:
+        """Filter that imposes no restriction (RBAC disabled / not applicable)."""
+        return cls(accessible_app_ids=None, can_manage_own_apps=False)
+
+    def is_app_accessible(self, app_id: str, maintainer: str | None, account_id: str) -> bool:
+        """Whether a single app is visible to the caller under this filter.
+
+        Mirrors the service-layer query gate: an app is visible when the filter
+        is unrestricted, the app id is whitelisted, or the caller maintains it
+        and holds ``app.create_and_management``.
+        """
+        if self.accessible_app_ids is None:
+            return True
+        if app_id in self.accessible_app_ids:
+            return True
+        return self.can_manage_own_apps and maintainer is not None and maintainer == account_id
+
+    def apply_to_params(self, params: AppListBaseParams) -> None:
+        if self.accessible_app_ids is None:
+            return
+        params.accessible_app_ids = sorted(self.accessible_app_ids)
+        params.include_own_apps = self.can_manage_own_apps
+
+
+def resolve_app_access_filter(
+    tenant_id: str,
+    account_id: str,
+    *,
+    permissions: MyPermissionsResponse | None = None,
+) -> AppAccessFilter:
+    """Compute the RBAC app-access filter for ``account_id`` in ``tenant_id``.
+
+    Pass ``permissions`` when the caller has already fetched the snapshot (the
+    console controller reuses it for per-app permission keys) to avoid a second
+    inner-API round trip; otherwise it is fetched here.
+    """
+    if permissions is None:
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(tenant_id, account_id)
+    whitelist_scope = enterprise_rbac_service.RBACService.AppAccess.whitelist_resources(tenant_id, account_id)
+
+    can_manage_own_apps = _MANAGE_OWN_APPS_PERMISSION_KEY in permissions.workspace.permission_keys
+    has_default_preview = has_app_list_permission(permissions.app.default_permission_keys) or has_app_list_permission(
+        permissions.workspace.permission_keys
+    )
+
+    permission_app_ids: set[str] | None = None
+    if not has_default_preview:
+        # Collect apps the caller can preview via per-app permission overrides.
+        permission_app_ids = {
+            override.resource_id
+            for override in permissions.app.overrides
+            if has_app_list_permission(override.permission_keys)
+        }
+
+    accessible_app_ids: set[str] | None
+    if getattr(whitelist_scope, "unrestricted", False):
+        accessible_app_ids = permission_app_ids
+    else:
+        accessible_app_ids = set(whitelist_scope.resource_ids)
+        if permission_app_ids is not None:
+            accessible_app_ids |= permission_app_ids
+        elif has_default_preview:
+            # Default preview overrides the whitelist restriction.
+            accessible_app_ids = None
+
+    return AppAccessFilter(accessible_app_ids=accessible_app_ids, can_manage_own_apps=can_manage_own_apps)

api/controllers/common/controller_schemas.py

@@ -1,7 +1,8 @@
-from typing import Any, Literal
+from copy import deepcopy
+from typing import Annotated, Any, Literal, override
 from uuid import UUID
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, GetJsonSchemaHandler, WithJsonSchema, model_validator
 
 from libs.helper import UUIDStrOrEmpty
 
@@ -9,8 +10,53 @@ from libs.helper import UUIDStrOrEmpty
 
 
 class ConversationRenamePayload(BaseModel):
-    name: str | None = None
-    auto_generate: bool = False
+    name: str | None = Field(
+        default=None,
+        description="Conversation name. Required when `auto_generate` is `false`.",
+    )
+    auto_generate: bool = Field(
+        default=False,
+        description="Automatically generate the conversation name. When `true`, the `name` field is ignored.",
+    )
+
+    @classmethod
+    @override
+    def __get_pydantic_json_schema__(cls, core_schema: Any, handler: GetJsonSchemaHandler) -> dict[str, Any]:
+        schema = handler.resolve_ref_schema(handler(core_schema))
+        properties = schema.get("properties")
+        if not isinstance(properties, dict):
+            return schema
+
+        auto_generate_schema = deepcopy(properties.get("auto_generate", {"type": "boolean"}))
+        name_schema = deepcopy(properties.get("name", {"type": "string"}))
+        non_blank_name_schema: dict[str, Any] = {"pattern": r".*\S.*", "type": "string"}
+        if isinstance(name_schema, dict) and isinstance(name_schema.get("title"), str):
+            non_blank_name_schema["title"] = name_schema["title"]
+
+        auto_generate_true_schema = {**auto_generate_schema, "enum": [True]}
+        auto_generate_true_schema.pop("default", None)
+
+        return {
+            **schema,
+            "anyOf": [
+                {
+                    "properties": {
+                        "auto_generate": auto_generate_true_schema,
+                        "name": name_schema,
+                    },
+                    "required": ["auto_generate"],
+                    "type": "object",
+                },
+                {
+                    "properties": {
+                        "auto_generate": {**auto_generate_schema, "enum": [False]},
+                        "name": non_blank_name_schema,
+                    },
+                    "required": ["name"],
+                    "type": "object",
+                },
+            ],
+        }
 
     @model_validator(mode="after")
     def validate_name_requirement(self):
@@ -24,14 +70,28 @@ class ConversationRenamePayload(BaseModel):
 
 
 class MessageListQuery(BaseModel):
-    conversation_id: UUIDStrOrEmpty = Field(description="Conversation UUID")
-    first_id: UUIDStrOrEmpty | None = Field(default=None, description="First message ID for pagination")
-    limit: int = Field(default=20, ge=1, le=100, description="Number of messages to return (1-100)")
+    conversation_id: UUIDStrOrEmpty = Field(description="Conversation ID.")
+    first_id: UUIDStrOrEmpty | None = Field(
+        default=None,
+        description=(
+            "The ID of the first chat record on the current page. Omit this value to fetch the latest messages; "
+            "for subsequent pages, use the first message ID from the current list to fetch older messages."
+        ),
+    )
+    limit: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Number of chat history messages to return per request.",
+    )
 
 
 class MessageFeedbackPayload(BaseModel):
-    rating: Literal["like", "dislike"] | None = None
-    content: str | None = None
+    rating: Literal["like", "dislike"] | None = Field(
+        default=None,
+        description="Feedback rating. Set to `null` to revoke previously submitted feedback.",
+    )
+    content: str | None = Field(default=None, description="Optional text feedback providing additional detail.")
 
 
 # --- Saved message schemas ---
@@ -48,6 +108,39 @@ class SavedMessageCreatePayload(BaseModel):
 
 # --- Workflow schemas ---
 
+WORKFLOW_INPUT_FILE_ITEM_SCHEMA: dict[str, object] = {
+    "type": "object",
+    "required": ["type", "transfer_method"],
+    "properties": {
+        "type": {
+            "description": "File type.",
+            "enum": ["document", "image", "audio", "video", "custom"],
+            "type": "string",
+        },
+        "transfer_method": {
+            "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file.",
+            "enum": ["remote_url", "local_file"],
+            "type": "string",
+        },
+        "url": {
+            "description": "File URL when `transfer_method` is `remote_url`.",
+            "format": "url",
+            "type": "string",
+        },
+        "upload_file_id": {
+            "description": (
+                "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API when "
+                "`transfer_method` is `local_file`."
+            ),
+            "type": "string",
+        },
+    },
+}
+WORKFLOW_INPUT_FILE_LIST_SCHEMA: dict[str, object] = {
+    "anyOf": [{"items": WORKFLOW_INPUT_FILE_ITEM_SCHEMA, "type": "array"}, {"type": "null"}]
+}
+WorkflowInputFileList = Annotated[list[dict[str, Any]] | None, WithJsonSchema(WORKFLOW_INPUT_FILE_LIST_SCHEMA)]
+
 
 class DefaultBlockConfigQuery(BaseModel):
     q: str | None = None
@@ -61,8 +154,22 @@ class WorkflowListQuery(BaseModel):
 
 
 class WorkflowRunPayload(BaseModel):
-    inputs: dict[str, Any]
-    files: list[dict[str, Any]] | None = None
+    inputs: dict[str, Any] = Field(
+        description=(
+            "Key-value pairs for workflow input variables. Values for file-type variables should be arrays of "
+            "file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`. Refer to the "
+            "`user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) "
+            "response to discover the variable names and types expected by your app."
+        )
+    )
+    files: WorkflowInputFileList = Field(
+        default=None,
+        description=(
+            "File list for workflow system file inputs. Available when file upload is enabled for the workflow. "
+            "To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use "
+            "the returned `id` as `upload_file_id` with `transfer_method: local_file`."
+        ),
+    )
 
 
 class WorkflowUpdatePayload(BaseModel):
@@ -77,28 +184,49 @@ DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS = 100
 
 
 class ChildChunkCreatePayload(BaseModel):
-    content: str
+    content: str = Field(description="Child chunk text content.")
 
 
 class ChildChunkUpdatePayload(BaseModel):
-    content: str
+    content: str = Field(description="Child chunk text content.")
 
 
 class DocumentBatchDownloadZipPayload(BaseModel):
     """Request payload for bulk downloading documents as a zip archive."""
 
-    document_ids: list[UUID] = Field(..., min_length=1, max_length=DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS)
+    document_ids: list[UUID] = Field(
+        ...,
+        min_length=1,
+        max_length=DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS,
+        description="List of document IDs to include in the ZIP download.",
+    )
 
 
 class MetadataUpdatePayload(BaseModel):
-    name: str
+    name: str = Field(description="New metadata field name.")
 
 
 # --- Audio schemas ---
 
 
+UUIDString = Annotated[str, WithJsonSchema({"format": "uuid", "type": "string"})]
+
+
 class TextToAudioPayload(BaseModel):
-    message_id: str | None = Field(default=None, description="Message ID")
-    voice: str | None = Field(default=None, description="Voice to use for TTS")
-    text: str | None = Field(default=None, description="Text to convert to audio")
-    streaming: bool | None = Field(default=None, description="Enable streaming response")
+    message_id: UUIDString | None = Field(
+        default=None,
+        description="Message ID. Takes priority over `text` when both are provided.",
+    )
+    voice: str | None = Field(
+        default=None,
+        description=(
+            "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. "
+            "Omit to use the app's configured voice when available; that value is exposed by "
+            "[Get App Parameters](/api-reference/applications/get-app-parameters) as `text_to_speech.voice`."
+        ),
+    )
+    text: str | None = Field(default=None, description="Speech content to convert.")
+    streaming: bool | None = Field(
+        default=None,
+        description="Reserved for compatibility; TTS response streaming is determined by the provider output.",
+    )

api/controllers/common/errors.py

@@ -41,3 +41,13 @@ class NoFileUploadedError(BaseHTTPException):
     error_code = "no_file_uploaded"
     description = "Please upload your file."
     code = 400
+
+
+class NotFoundError(BaseHTTPException):
+    error_code = "not_found"
+    code = 404
+
+
+class InvalidArgumentError(BaseHTTPException):
+    error_code = "invalid_param"
+    code = 400

api/controllers/common/fields.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field, computed_field
+from pydantic import BaseModel, ConfigDict, Field, RootModel, computed_field
 
 from fields.base import ResponseModel
 from graphon.file import helpers as file_helpers
@@ -24,6 +24,34 @@ class SimpleResultResponse(ResponseModel):
     result: str
 
 
+class GeneratedAppResponse(RootModel[JSONValue]):
+    root: JSONValue
+
+
+class EventStreamResponse(RootModel[str]):
+    root: str
+
+
+class TextFileResponse(RootModel[str]):
+    root: str
+
+
+class RedirectResponse(RootModel[str]):
+    root: str
+
+
+class BinaryFileResponse(RootModel[bytes]):
+    root: bytes
+
+
+class AudioBinaryResponse(RootModel[bytes]):
+    root: bytes
+
+
+class AudioTranscriptResponse(ResponseModel):
+    text: str
+
+
 class SimpleResultMessageResponse(ResponseModel):
     result: str
     message: str
@@ -125,6 +153,7 @@ class ApiBaseUrlResponse(ResponseModel):
 
 class NewAppResponse(ResponseModel):
     new_app_id: str
+    permission_keys: list[str] = Field(default_factory=list)
 
 
 class Parameters(BaseModel):

api/controllers/common/human_input.py

@@ -35,17 +35,23 @@ class HumanInputFormSubmitPayload(BaseModel):
         ),
         examples=[HUMAN_INPUT_FORM_INPUT_EXAMPLE],
     )
-    action: str
+    action: str = Field(
+        description=(
+            "ID of the action button the recipient selected. Must match one of the `id` values from the form's "
+            "`user_actions` list."
+        )
+    )
 
 
 def stringify_form_default_values(values: dict[str, object]) -> dict[str, str]:
     """Serialize default values into strings expected by human-input form clients."""
     result: dict[str, str] = {}
     for key, value in values.items():
-        if value is None:
-            result[key] = ""
-        elif isinstance(value, (dict, list)):
-            result[key] = json.dumps(value, ensure_ascii=False)
-        else:
-            result[key] = str(value)
+        match value:
+            case None:
+                result[key] = ""
+            case dict() | list():
+                result[key] = json.dumps(value, ensure_ascii=False)
+            case _:
+                result[key] = str(value)
     return result

api/controllers/common/schema.py

@@ -1,9 +1,9 @@
 """Helpers for registering Pydantic models with Flask-RESTX namespaces.
 
 Flask-RESTX treats `SchemaModel` bodies as opaque JSON schemas; it does not
-promote Pydantic's nested `$defs` into top-level Swagger `definitions`.
+promote Pydantic's nested `$defs` into top-level OpenAPI component schemas.
 These helpers keep that translation centralized so models registered through
-`register_schema_models` emit resolvable Swagger 2.0 references.
+`register_schema_models` emit resolvable OpenAPI 3 references.
 """
 
 from collections.abc import Iterable, Mapping
@@ -14,7 +14,7 @@ from flask import request
 from flask_restx import Namespace
 from pydantic import BaseModel, TypeAdapter
 
-DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
+DEFAULT_REF_TEMPLATE_OPENAPI_3_0 = "#/components/schemas/{model}"
 
 
 QueryParamDoc = TypedDict(
@@ -27,12 +27,18 @@ QueryParamDoc = TypedDict(
         "description": NotRequired[str],
         "enum": NotRequired[list[object]],
         "default": NotRequired[object],
+        "format": NotRequired[str],
         "minimum": NotRequired[int | float],
         "maximum": NotRequired[int | float],
+        "exclusiveMinimum": NotRequired[int | float],
+        "exclusiveMaximum": NotRequired[int | float],
         "minLength": NotRequired[int],
         "maxLength": NotRequired[int],
+        "pattern": NotRequired[str],
         "minItems": NotRequired[int],
         "maxItems": NotRequired[int],
+        "uniqueItems": NotRequired[bool],
+        "multipleOf": NotRequired[int | float],
     },
 )
 
@@ -48,7 +54,6 @@ class QueryArgs(Protocol):
 def _register_json_schema(namespace: Namespace, name: str, schema: dict) -> None:
     """Register a JSON schema and promote any nested Pydantic `$defs`."""
 
-    schema = _swagger_2_compatible_schema(schema)
     nested_definitions = schema.get("$defs")
     schema_to_register = dict(schema)
     if isinstance(nested_definitions, dict):
@@ -71,41 +76,12 @@ def _register_schema_model(namespace: Namespace, model: type[BaseModel], *, mode
     _register_json_schema(
         namespace,
         model.__name__,
-        model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0, mode=mode),
+        model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0, mode=mode),
     )
 
 
-def _swagger_2_compatible_schema(value: Any) -> Any:
-    if isinstance(value, list):
-        return [_swagger_2_compatible_schema(item) for item in value]
-
-    if not isinstance(value, dict):
-        return value
-
-    converted = {key: _swagger_2_compatible_schema(child) for key, child in value.items()}
-    any_of = value.get("anyOf")
-    if not isinstance(any_of, list):
-        return converted
-
-    non_null_candidates = [
-        candidate for candidate in any_of if isinstance(candidate, Mapping) and candidate.get("type") != "null"
-    ]
-    has_null_candidate = any(isinstance(candidate, Mapping) and candidate.get("type") == "null" for candidate in any_of)
-    if not has_null_candidate or len(non_null_candidates) != 1:
-        return converted
-
-    non_null_schema = _swagger_2_compatible_schema(dict(non_null_candidates[0]))
-    if not isinstance(non_null_schema, dict):
-        return converted
-
-    converted.pop("anyOf", None)
-    converted.update(non_null_schema)
-    converted["x-nullable"] = True
-    return converted
-
-
 def register_schema_model(namespace: Namespace, model: type[BaseModel]) -> None:
-    """Register a BaseModel and its nested schema definitions for Swagger documentation."""
+    """Register a BaseModel and its nested component schemas for OpenAPI documentation."""
 
     _register_schema_model(namespace, model, mode="validation")
 
@@ -146,7 +122,7 @@ def register_enum_models(namespace: Namespace, *models: type[StrEnum]) -> None:
         _register_json_schema(
             namespace,
             model.__name__,
-            TypeAdapter(model).json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
+            TypeAdapter(model).json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0),
         )
 
 
@@ -155,10 +131,11 @@ def query_params_from_model(model: type[BaseModel]) -> dict[str, QueryParamDoc]:
 
     `Namespace.expect()` treats Pydantic schema models as request bodies, so GET
     endpoints should keep runtime validation on the Pydantic model and feed this
-    derived mapping to `Namespace.doc(params=...)` for Swagger documentation.
+    derived mapping to `Namespace.doc(params=...)` for OpenAPI documentation.
     """
 
-    schema = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0)
+    schema = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0)
+    definitions = _schema_definitions(schema)
     properties = schema.get("properties", {})
     if not isinstance(properties, Mapping):
         return {}
@@ -171,7 +148,11 @@ def query_params_from_model(model: type[BaseModel]) -> dict[str, QueryParamDoc]:
         if not isinstance(name, str) or not isinstance(property_schema, Mapping):
             continue
 
-        params[name] = _query_param_from_property(property_schema, required=name in required_names)
+        params[name] = _query_param_from_property(
+            property_schema,
+            required=name in required_names,
+            definitions=definitions,
+        )
 
     return params
 
@@ -203,7 +184,7 @@ def query_params_from_request[ModelT: BaseModel](
 
 
 def _drop_malformed_defaulted_integer_params(model: type[BaseModel], params: dict[str, Any]) -> None:
-    properties = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0).get("properties", {})
+    properties = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0).get("properties", {})
     if not isinstance(properties, Mapping):
         return
 
@@ -228,8 +209,18 @@ def _drop_malformed_defaulted_integer_params(model: type[BaseModel], params: dic
             params.pop(name)
 
 
-def _query_param_from_property(property_schema: Mapping[str, Any], *, required: bool) -> QueryParamDoc:
-    param_schema = _nullable_property_schema(property_schema)
+def _schema_definitions(schema: Mapping[str, Any]) -> Mapping[str, Any]:
+    definitions = schema.get("$defs")
+    return definitions if isinstance(definitions, Mapping) else {}
+
+
+def _query_param_from_property(
+    property_schema: Mapping[str, Any],
+    *,
+    required: bool,
+    definitions: Mapping[str, Any],
+) -> QueryParamDoc:
+    param_schema = _resolve_schema_ref(_nullable_property_schema(property_schema), definitions)
     param_doc: QueryParamDoc = {"in": "query", "required": required}
 
     description = param_schema.get("description")
@@ -242,9 +233,16 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
         if schema_type == "array":
             items = param_schema.get("items")
             if isinstance(items, Mapping):
-                item_type = items.get("type")
+                item_schema = _resolve_schema_ref(items, definitions)
+                item_type = item_schema.get("type")
                 if isinstance(item_type, str):
                     param_doc["items"] = {"type": item_type}
+                item_enum = item_schema.get("enum")
+                if isinstance(item_enum, list):
+                    param_doc.setdefault("items", {})["enum"] = item_enum
+                item_format = item_schema.get("format")
+                if isinstance(item_format, str):
+                    param_doc.setdefault("items", {})["format"] = item_format
 
     enum = param_schema.get("enum")
     if isinstance(enum, list):
@@ -254,6 +252,10 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
     if default is not None:
         param_doc["default"] = default
 
+    schema_format = param_schema.get("format")
+    if isinstance(schema_format, str):
+        param_doc["format"] = schema_format
+
     minimum = param_schema.get("minimum")
     if isinstance(minimum, int | float):
         param_doc["minimum"] = minimum
@@ -262,6 +264,14 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
     if isinstance(maximum, int | float):
         param_doc["maximum"] = maximum
 
+    exclusive_minimum = param_schema.get("exclusiveMinimum")
+    if isinstance(exclusive_minimum, int | float):
+        param_doc["exclusiveMinimum"] = exclusive_minimum
+
+    exclusive_maximum = param_schema.get("exclusiveMaximum")
+    if isinstance(exclusive_maximum, int | float):
+        param_doc["exclusiveMaximum"] = exclusive_maximum
+
     min_length = param_schema.get("minLength")
     if isinstance(min_length, int):
         param_doc["minLength"] = min_length
@@ -270,6 +280,10 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
     if isinstance(max_length, int):
         param_doc["maxLength"] = max_length
 
+    pattern = param_schema.get("pattern")
+    if isinstance(pattern, str):
+        param_doc["pattern"] = pattern
+
     min_items = param_schema.get("minItems")
     if isinstance(min_items, int):
         param_doc["minItems"] = min_items
@@ -278,9 +292,31 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
     if isinstance(max_items, int):
         param_doc["maxItems"] = max_items
 
+    unique_items = param_schema.get("uniqueItems")
+    if isinstance(unique_items, bool):
+        param_doc["uniqueItems"] = unique_items
+
+    multiple_of = param_schema.get("multipleOf")
+    if isinstance(multiple_of, int | float):
+        param_doc["multipleOf"] = multiple_of
+
     return param_doc
 
 
+def _resolve_schema_ref(property_schema: Mapping[str, Any], definitions: Mapping[str, Any]) -> Mapping[str, Any]:
+    ref = property_schema.get("$ref")
+    if not isinstance(ref, str):
+        return property_schema
+
+    ref_name = ref.rsplit("/", 1)[-1]
+    resolved = definitions.get(ref_name)
+    if not isinstance(resolved, Mapping):
+        return property_schema
+
+    property_without_ref = {key: value for key, value in property_schema.items() if key != "$ref"}
+    return {**resolved, **property_without_ref}
+
+
 def _nullable_property_schema(property_schema: Mapping[str, Any]) -> Mapping[str, Any]:
     any_of = property_schema.get("anyOf")
     if not isinstance(any_of, list):
@@ -297,7 +333,7 @@ def _nullable_property_schema(property_schema: Mapping[str, Any]) -> Mapping[str
 
 
 __all__ = [
-    "DEFAULT_REF_TEMPLATE_SWAGGER_2_0",
+    "DEFAULT_REF_TEMPLATE_OPENAPI_3_0",
     "get_or_create_model",
     "query_params_from_model",
     "query_params_from_request",

api/controllers/common/wraps.py

@@ -0,0 +1,166 @@
+from collections.abc import Callable
+from functools import wraps
+
+from sqlalchemy import select
+from werkzeug.exceptions import Forbidden, NotFound
+
+from configs import dify_config
+from core.rbac import RBACPermission, RBACResourceScope
+from extensions.ext_database import db
+from libs.login import current_account_with_tenant
+from models.dataset import Dataset
+from models.model import App
+from services.enterprise.rbac_service import RBACService
+
+__all__ = ["RBACPermission", "RBACResourceScope", "enforce_rbac_access", "rbac_permission_required"]
+
+
+def enforce_rbac_access(
+    *,
+    tenant_id: str,
+    account_id: str,
+    resource_type: RBACResourceScope,
+    scene: RBACPermission,
+    resource_required: bool = True,
+    path_args: dict[str, object] | None = None,
+) -> None:
+    """Enforce enterprise RBAC for an explicit account/tenant pair.
+
+    This is the flask-login-independent core of the RBAC gate so it can run
+    inside request-handling layers that resolve the caller themselves (e.g. the
+    openapi auth pipeline, which has the account on ``AuthData`` before
+    flask-login is mounted).
+
+    No-op when ``RBAC_ENABLED`` is ``False``. For resource-scoped checks the
+    resource ID is taken from ``path_args`` merged with ``request.view_args``;
+    resource ownership short-circuits the check. Raises ``Forbidden`` when
+    access is denied. For workspace-level checks pass ``resource_required=False``
+    so the RBAC request omits ``resource_id``.
+
+    Args:
+        tenant_id: The tenant the access is evaluated against.
+        account_id: The account requesting access.
+        resource_type: The :class:`RBACResourceScope` member (app/dataset/workspace).
+        scene: The :class:`RBACPermission` permission point, e.g. ``RBACPermission.APP_DELETE``.
+        resource_required: Whether a concrete resource ID is required.
+        path_args: Extra path arguments to merge with ``request.view_args``.
+    """
+    if not dify_config.RBAC_ENABLED:
+        return
+
+    check_resource_type = None if resource_type == RBACResourceScope.WORKSPACE else resource_type
+    resource_id = None
+    if resource_required and check_resource_type:
+        resource_id = _extract_resource_id(resource_type, path_args)
+        if _is_resource_owned_by_current_user(tenant_id, account_id, resource_type, resource_id):
+            return
+    allowed = RBACService.CheckAccess.check(
+        tenant_id,
+        account_id,
+        scene=scene,
+        resource_type=check_resource_type,
+        resource_id=resource_id,
+    )
+    if not allowed:
+        raise Forbidden()
+
+
+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 flask-login user.
+
+    When ``RBAC_ENABLED`` is ``False`` the decorator is a no-op and the
+    request passes through unchanged. When enabled it resolves the current
+    account/tenant and delegates to :func:`enforce_rbac_access`, raising
+    ``Forbidden`` if access is denied.
+
+    Args:
+        resource_type: The :class:`RBACResourceScope` member (app/dataset/workspace).
+        scene: The :class:`RBACPermission` permission point, e.g. ``RBACPermission.APP_DELETE``.
+        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:
+            if not dify_config.RBAC_ENABLED:
+                return view(*args, **kwargs)
+
+            current_user, current_tenant_id = current_account_with_tenant()
+            enforce_rbac_access(
+                tenant_id=current_tenant_id,
+                account_id=current_user.id,
+                resource_type=resource_type,
+                scene=scene,
+                resource_required=resource_required,
+                path_args=kwargs,
+            )
+            return view(*args, **kwargs)
+
+        return decorated
+
+    return decorator
+
+
+def _is_resource_owned_by_current_user(
+    tenant_id: str, account_id: str, resource_type: RBACResourceScope, resource_id: str
+) -> bool:
+    if resource_type == RBACResourceScope.APP:
+        maintainer = db.session.scalar(
+            select(App.maintainer).where(
+                App.id == resource_id,
+                App.tenant_id == tenant_id,
+                App.status == "normal",
+            )
+        )
+        return maintainer == account_id
+
+    if resource_type == RBACResourceScope.DATASET:
+        maintainer = db.session.scalar(
+            select(Dataset.maintainer).where(
+                Dataset.id == resource_id,
+                Dataset.tenant_id == tenant_id,
+            )
+        )
+        return maintainer == account_id
+
+    return False
+
+
+def _extract_resource_id(resource_type: RBACResourceScope, path_args: dict[str, object] | None = None) -> str:
+    """Extract the resource ID from matched path arguments.
+
+    Some legacy route classes use neutral names such as ``resource_id`` for
+    app/dataset resources, and Agent App routes use ``agent_id`` as the app id.
+    Dataset endpoints behind a rag-pipeline route contain ``pipeline_id``
+    instead of ``dataset_id``. In that case we look up the associated
+    ``Dataset`` row via ``Dataset.pipeline_id``.
+    """
+    from flask import request
+
+    view_args = request.view_args or {}
+    matched_args = {**view_args, **(path_args or {})}
+
+    if resource_type == RBACResourceScope.APP:
+        app_id = matched_args.get("app_id") or matched_args.get("agent_id") or matched_args.get("resource_id")
+        if not app_id:
+            raise ValueError("Missing app_id in request path")
+        return str(app_id)
+
+    if resource_type == RBACResourceScope.DATASET:
+        dataset_id = matched_args.get("dataset_id") or matched_args.get("resource_id")
+        if dataset_id:
+            return str(dataset_id)
+
+        pipeline_id = matched_args.get("pipeline_id")
+        if pipeline_id:
+            dataset = db.session.scalar(select(Dataset).where(Dataset.pipeline_id == str(pipeline_id)))
+            if not dataset:
+                raise NotFound("Dataset not found for pipeline")
+            return str(dataset.id)
+        raise ValueError("Missing dataset_id or pipeline_id in request path")
+    raise ValueError(f"Unknown resource_type: {resource_type}")

api/controllers/console/__init__.py

@@ -53,7 +53,8 @@ from .app import (
     agent,
     agent_app_access,
     agent_app_feature,
-    agent_app_workspace,
+    agent_app_sandbox,
+    agent_drive_inspector,
     annotation,
     app,
     audio,
@@ -138,6 +139,7 @@ from .workspace import (
     model_providers,
     models,
     plugin,
+    rbac,
     snippets,
     tool_providers,
     trigger_providers,
@@ -153,8 +155,9 @@ __all__ = [
     "agent",
     "agent_app_access",
     "agent_app_feature",
-    "agent_app_workspace",
+    "agent_app_sandbox",
     "agent_composer",
+    "agent_drive_inspector",
     "agent_providers",
     "agent_roster",
     "annotation",
@@ -210,6 +213,7 @@ __all__ = [
     "rag_pipeline_draft_variable",
     "rag_pipeline_import",
     "rag_pipeline_workflow",
+    "rbac",
     "recommended_app",
     "saved_message",
     "setup",

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,11 +1,17 @@
+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 (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user_id,
@@ -22,9 +28,9 @@ from libs.login import login_required
 from models.model import App, AppMode
 from services.agent.composer_service import AgentComposerService
 from services.agent.composer_validator import ComposerConfigValidator
-from services.entities.agent_entities import ComposerSavePayload
+from services.entities.agent_entities import ComposerSavePayload, WorkflowComposerCopyFromRosterPayload
 
-register_schema_models(console_ns, ComposerSavePayload)
+register_schema_models(console_ns, ComposerSavePayload, WorkflowComposerCopyFromRosterPayload)
 register_response_schema_models(
     console_ns,
     AgentAppComposerResponse,
@@ -35,6 +41,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(
@@ -63,6 +73,7 @@ class WorkflowAgentComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     @with_current_user_id
     @with_current_tenant_id
@@ -80,6 +91,38 @@ class WorkflowAgentComposerApi(Resource):
         )
 
 
+@console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer/copy-from-roster")
+class WorkflowAgentComposerCopyFromRosterApi(Resource):
+    @console_ns.expect(console_ns.models[WorkflowComposerCopyFromRosterPayload.__name__])
+    @console_ns.response(
+        200,
+        "Workflow roster agent copied to inline agent",
+        console_ns.models[WorkflowAgentComposerResponse.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    @with_current_user_id
+    @with_current_tenant_id
+    def post(self, tenant_id: str, account_id: str, app_model: App, node_id: str):
+        payload = WorkflowComposerCopyFromRosterPayload.model_validate(console_ns.payload or {})
+        return dump_response(
+            WorkflowAgentComposerResponse,
+            AgentComposerService.copy_workflow_composer_from_roster(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                node_id=node_id,
+                account_id=account_id,
+                source_agent_id=payload.source_agent_id,
+                source_snapshot_id=payload.source_snapshot_id,
+                idempotency_key=payload.idempotency_key,
+            ),
+        )
+
+
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer/validate")
 class WorkflowAgentComposerValidateApi(Resource):
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
@@ -90,10 +133,18 @@ class WorkflowAgentComposerValidateApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
-    def post(self, app_model: App, node_id: str):
+    @with_current_tenant_id
+    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)
-        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": []})
+        ComposerConfigValidator.validate_publish_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})
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer/candidates")
@@ -105,10 +156,17 @@ class WorkflowAgentComposerCandidatesApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
-    def get(self, app_model: App, node_id: str):
+    @with_current_user_id
+    @with_current_tenant_id
+    def get(self, tenant_id: str, current_user_id: str, app_model: App, node_id: str):
         return dump_response(
             AgentComposerCandidatesResponse,
-            AgentComposerService.get_workflow_candidates(app_id=app_model.id),
+            AgentComposerService.get_workflow_candidates(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                node_id=node_id,
+                user_id=current_user_id,
+            ),
         )
 
 
@@ -144,6 +202,7 @@ class WorkflowAgentComposerSaveToRosterApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     @with_current_user_id
     @with_current_tenant_id
@@ -161,18 +220,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()
     @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__])
@@ -181,24 +240,25 @@ class AgentAppComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @get_app_model()
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @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__]
@@ -206,24 +266,36 @@ class AgentAppComposerValidateApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model()
-    def post(self, app_model: App):
+    @with_current_tenant_id
+    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)
-        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": []})
+        ComposerConfigValidator.validate_publish_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()
-    def get(self, app_model: App):
+    @with_current_user_id
+    @with_current_tenant_id
+    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(app_id=app_model.id),
+            AgentComposerService.get_agent_app_candidates(
+                tenant_id=tenant_id,
+                app_id=app_id,
+                user_id=current_user_id,
+            ),
         )

api/controllers/console/agent/roster.py

@@ -1,30 +1,72 @@
 from uuid import UUID
 
-from flask import request
+from flask import abort, request
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, BaseModel, Field, field_validator
+from sqlalchemy import func, select
 
 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.apikey import ApiKeyItem, ApiKeyList, BaseApiKeyListResource, BaseApiKeyResource
+from controllers.console.app.app import (
+    AppDetailWithSite as GenericAppDetailWithSite,
+)
+from controllers.console.app.app import (
+    AppListQuery,
+    _normalize_app_list_query_args,
+)
+from controllers.console.app.app import (
+    AppPagination as GenericAppPagination,
+)
+from controllers.console.app.app import (
+    AppPartial as GenericAppPartial,
+)
+from controllers.console.app.app import (
+    UpdateAppPayload as GenericUpdateAppPayload,
+)
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    enterprise_license_required,
+    is_admin_or_owner_required,
+    rbac_permission_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 (
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
+    AgentConfigSnapshotRestoreResponse,
     AgentInviteOptionsResponse,
+    AgentLogListResponse,
+    AgentLogMessageListResponse,
+    AgentLogSourceListResponse,
+    AgentPublishedReferenceResponse,
     AgentRosterListResponse,
-    AgentRosterResponse,
+    AgentStatisticSummaryEnvelopeResponse,
 )
+from libs.datetime_utils import parse_time_range
 from libs.helper import dump_response
 from libs.login import login_required
+from models import Account
+from models.enums import ApiTokenType
+from models.model import ApiToken, App, IconType
+from services.agent.errors import AgentNotFoundError
+from services.agent.observability_service import (
+    AgentLogQueryParams,
+    AgentObservabilityService,
+    AgentStatisticsQueryParams,
+)
 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):
@@ -35,21 +77,216 @@ 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(..., min_length=1, 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")
+
+    @field_validator("role")
+    @classmethod
+    def validate_role(cls, value: str) -> str:
+        role = value.strip()
+        if not role:
+            raise ValueError("Agent role is required.")
+        return role
+
+
+# Keep agent-app roster DTOs agent-specific instead of reusing the shared
+# /apps response/request models. The roster surface needs Agent-only fields such
+# as `role`, while the generic console/apps contracts must stay unchanged.
+class AgentAppUpdatePayload(GenericUpdateAppPayload):
+    role: str = Field(..., min_length=1, description="Agent role", max_length=255)
+
+    @field_validator("role")
+    @classmethod
+    def validate_role(cls, value: str) -> str:
+        role = value.strip()
+        if not role:
+            raise ValueError("Agent role is required.")
+        return role
+
+
+class AgentAppCopyPayload(BaseModel):
+    name: str | None = Field(default=None, description="Name for the copied agent")
+    description: str | None = Field(default=None, description="Description for the copied agent", max_length=400)
+    role: str | None = Field(default=None, description="Role for the copied agent", 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")
+
+    @field_validator("role")
+    @classmethod
+    def validate_role(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        role = value.strip()
+        if not role:
+            raise ValueError("Agent role is required when provided.")
+        return role
+
+
+class AgentApiStatusPayload(BaseModel):
+    enable_api: bool = Field(..., description="Enable or disable Agent service API")
+
+
+class AgentApiAccessResponse(BaseModel):
+    enabled: bool
+    service_api_base_url: str
+    streaming_only: bool = True
+    chat_endpoint: str
+    stop_endpoint: str
+    conversations_endpoint: str
+    messages_endpoint: str
+    files_upload_endpoint: str
+    parameters_endpoint: str
+    info_endpoint: str
+    meta_endpoint: str
+    api_rpm: int
+    api_rph: int
+    api_key_count: int
+
+
+class AgentAppPublishedReferenceResponse(BaseModel):
+    app_id: str
+    app_name: str
+    app_icon_type: str | None = None
+    app_icon: str | None = None
+    app_icon_background: str | None = None
+
+
+class AgentLogsQuery(BaseModel):
+    page: int = Field(default=1, ge=1, description="Page number")
+    limit: int = Field(default=20, ge=1, le=100, description="Page size")
+    keyword: str | None = Field(default=None, description="Search query, answer, or conversation name")
+    status: str | None = Field(default=None, description="Deprecated single status filter")
+    statuses: list[str] = Field(default_factory=list, description="Filter by one or more of success, failed, paused")
+    source: str | None = Field(
+        default=None,
+        description="Deprecated single source filter",
+    )
+    sources: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Filter by one or more source IDs, e.g. webapp:<app_id> "
+            "or workflow:<app_id>:<workflow_id>:<version>:<node_id>"
+        ),
+    )
+    sort_by: str = Field(default="updated_at", description="Sort by created_at or updated_at")
+    sort_order: str = Field(default="desc", description="Sort order: asc or desc")
+    start: str | None = Field(default=None, description="Start date (YYYY-MM-DD HH:MM)")
+    end: str | None = Field(default=None, description="End date (YYYY-MM-DD HH:MM)")
+
+    @field_validator("keyword", "status", "source", "start", "end", mode="before")
+    @classmethod
+    def empty_string_to_none(cls, value: str | None) -> str | None:
+        if value == "":
+            return None
+        return value
+
+    @field_validator("statuses", "sources", mode="before")
+    @classmethod
+    def empty_list_values_to_list(cls, value: object) -> list[str]:
+        if value in (None, ""):
+            return []
+        if isinstance(value, str):
+            return [value]
+        if isinstance(value, list):
+            return [item for item in value if item]
+        return []
+
+    @field_validator("sort_by")
+    @classmethod
+    def validate_sort_by(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized not in {"created_at", "updated_at"}:
+            raise ValueError("sort_by must be created_at or updated_at")
+        return normalized
+
+    @field_validator("sort_order")
+    @classmethod
+    def validate_sort_order(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized not in {"asc", "desc"}:
+            raise ValueError("sort_order must be asc or desc")
+        return normalized
+
+
+class AgentStatisticsQuery(BaseModel):
+    source: str | None = Field(
+        default=None,
+        description="Filter by all, console/explore, api/service-api, web-app, debugger, openapi, or trigger",
+    )
+    start: str | None = Field(default=None, description="Start date (YYYY-MM-DD HH:MM)")
+    end: str | None = Field(default=None, description="End date (YYYY-MM-DD HH:MM)")
+
+    @field_validator("source", "start", "end", mode="before")
+    @classmethod
+    def empty_string_to_none(cls, value: str | None) -> str | None:
+        if value == "":
+            return None
+        return value
+
+
+class AgentAppPartial(GenericAppPartial):
+    app_id: str | None = None
+    debug_conversation_id: str | None = None
+    role: str | None = None
+    active_config_is_published: bool = False
+    published_reference_count: int = 0
+    published_references: list[AgentAppPublishedReferenceResponse] = Field(default_factory=list)
+
+
+class AgentAppDetailWithSite(GenericAppDetailWithSite):
+    app_id: str | None = None
+    debug_conversation_id: str | None = None
+    role: str | None = None
+    active_config_is_published: bool = False
+
+
+class AgentDebugConversationRefreshResponse(BaseModel):
+    debug_conversation_id: str
+
+
+class AgentAppPagination(GenericAppPagination):
+    data: list[AgentAppPartial] = Field(  # type: ignore[assignment]  # pyrefly: ignore[bad-override-mutable-attribute]
+        validation_alias=AliasChoices("items", "data")
+    )
+
+
 register_schema_models(
     console_ns,
+    AgentAppCreatePayload,
+    AgentAppUpdatePayload,
+    AgentAppCopyPayload,
+    AgentApiStatusPayload,
     AgentInviteOptionsQuery,
+    AgentLogsQuery,
+    AgentStatisticsQuery,
     AgentIdPath,
-    RosterAgentCreatePayload,
-    RosterAgentUpdatePayload,
+    AppListQuery,
     RosterListQuery,
 )
 register_response_schema_models(
     console_ns,
+    AgentAppPagination,
+    AgentApiAccessResponse,
+    AgentAppPublishedReferenceResponse,
+    AgentAppDetailWithSite,
+    AgentAppPartial,
+    AgentDebugConversationRefreshResponse,
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
+    AgentConfigSnapshotRestoreResponse,
     AgentInviteOptionsResponse,
+    AgentLogListResponse,
+    AgentLogMessageListResponse,
+    AgentLogSourceListResponse,
+    AgentPublishedReferenceResponse,
     AgentRosterListResponse,
-    AgentRosterResponse,
+    AgentStatisticSummaryEnvelopeResponse,
 )
 
 
@@ -57,42 +294,393 @@ 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, *, current_user: Account) -> dict:
+    """Serialize an Agent App detail using roster-only DTOs.
+
+    `/agent` responses are roster-shaped rather than raw app-shaped: `id`
+    becomes the backing roster Agent id, `app_id` carries the underlying App
+    id, and `role` is injected from the backing roster Agent. Keeping that
+    remap in this serializer lets generated console/agent contracts expose the
+    roster persona fields without widening the shared /apps detail schema.
+    """
+
+    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]
+
+    roster_service = _agent_roster_service()
+    payload = AgentAppDetailWithSite.model_validate(app_model, from_attributes=True).model_dump(mode="json")
+    agent = roster_service.get_app_backing_agent(tenant_id=app_model.tenant_id, app_id=str(app_model.id))
+    if not agent:
+        raise AgentNotFoundError()
+    payload.pop("bound_agent_id", None)
+    payload["app_id"] = str(app_model.id)
+    payload["id"] = agent.id
+    payload["debug_conversation_id"] = roster_service.get_or_create_agent_app_debug_conversation_id(
+        tenant_id=app_model.tenant_id,
+        agent_id=agent.id,
+        account_id=current_user.id,
+    )
+    payload["role"] = agent.role or ""
+    payload["active_config_is_published"] = roster_service.active_config_is_published(
+        tenant_id=app_model.tenant_id,
+        agent=agent,
+    )
+    return payload
+
+
+def _serialize_agent_app_pagination(app_pagination, *, tenant_id: str, current_user: Account) -> dict:
+    """Serialize Agent App lists with roster-shaped items.
+
+    Each item starts from the shared App list shape, then drops
+    `bound_agent_id`, rewrites `id` to the backing roster Agent id, stores the
+    original App id in `app_id`, and injects roster-only `role` when a backing
+    Agent is present.
+    """
+
+    app_ids = [str(app.id) for app in app_pagination.items]
+    roster_service = _agent_roster_service()
+    agents_by_app_id = roster_service.load_app_backing_agents_by_app_id(
+        tenant_id=tenant_id,
+        app_ids=app_ids,
+    )
+    active_config_is_published_by_agent_id = roster_service.load_active_config_is_published_by_agent_id(
+        tenant_id=tenant_id,
+        agents=list(agents_by_app_id.values()),
+    )
+    published_references_by_agent_id = roster_service.load_published_references_by_agent_id(
+        tenant_id=tenant_id,
+        agent_ids=[agent.id for agent in agents_by_app_id.values()],
+    )
+    debug_conversation_ids_by_agent_id = roster_service.load_or_create_agent_app_debug_conversation_ids_by_agent_id(
+        tenant_id=tenant_id,
+        agents=list(agents_by_app_id.values()),
+        account_id=current_user.id,
+    )
+    payload = AgentAppPagination.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["debug_conversation_id"] = debug_conversation_ids_by_agent_id.get(agent.id)
+            item["role"] = agent.role or ""
+            item["active_config_is_published"] = active_config_is_published_by_agent_id.get(agent.id, False)
+            published_references = published_references_by_agent_id.get(agent.id, [])
+            item["published_reference_count"] = len(published_references)
+            item["published_references"] = [
+                {
+                    "app_id": reference["app_id"],
+                    "app_name": reference["app_name"],
+                    "app_icon_type": reference["app_icon_type"],
+                    "app_icon": reference["app_icon"],
+                    "app_icon_background": reference["app_icon_background"],
+                }
+                for reference in published_references
+            ]
+    return AgentAppPagination.model_validate(payload).model_dump(
+        mode="json",
+        exclude={"data": {"__all__": {"bound_agent_id"}}},
+    )
+
+
+def _resolve_agent_app_model(*, tenant_id: str, agent_id: UUID):
+    return resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+
+
+def _agent_api_key_count(app_id: str) -> int:
+    return (
+        db.session.scalar(
+            select(func.count(ApiToken.id)).where(
+                ApiToken.type == ApiTokenType.APP,
+                ApiToken.app_id == app_id,
+            )
+        )
+        or 0
+    )
+
+
+def _serialize_agent_api_access(app_model: App) -> dict:
+    base_url = app_model.api_base_url
+    response = AgentApiAccessResponse(
+        enabled=bool(app_model.enable_api),
+        service_api_base_url=base_url,
+        chat_endpoint=f"{base_url}/chat-messages",
+        stop_endpoint=f"{base_url}/chat-messages/{{task_id}}/stop",
+        conversations_endpoint=f"{base_url}/conversations",
+        messages_endpoint=f"{base_url}/messages",
+        files_upload_endpoint=f"{base_url}/files/upload",
+        parameters_endpoint=f"{base_url}/parameters",
+        info_endpoint=f"{base_url}/info",
+        meta_endpoint=f"{base_url}/meta",
+        api_rpm=app_model.api_rpm or 0,
+        api_rph=app_model.api_rph or 0,
+        api_key_count=_agent_api_key_count(str(app_model.id)),
+    )
+    return response.model_dump(mode="json")
+
+
+def _agent_observability_service() -> AgentObservabilityService:
+    return AgentObservabilityService(db.session)
+
+
+def _parse_observability_time_range(start: str | None, end: str | None, account: Account):
+    timezone = account.timezone or "UTC"
+    try:
+        return parse_time_range(start, end, timezone)
+    except ValueError as exc:
+        abort(400, description=str(exc))
+
+
+def _multi_query_values(name: str, legacy_name: str | None = None) -> list[str]:
+    values: list[str] = []
+    for query_name in (name, f"{name}[]"):
+        values.extend(request.args.getlist(query_name))
+    if legacy_name:
+        values.extend(request.args.getlist(legacy_name))
+    parsed: list[str] = []
+    for value in values:
+        parsed.extend(item.strip() for item in value.split(",") if item.strip())
+    return parsed
+
+
+@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[AgentAppPagination.__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, db.session)
+        if app_pagination is None:
+            empty = AgentAppPagination(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,
+            current_user=current_user,
+        )
+
+    @console_ns.expect(console_ns.models[AgentAppCreatePayload.__name__])
+    @console_ns.response(201, "Agent app created successfully", console_ns.models[AgentAppDetailWithSite.__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_user
     @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 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, current_user=current_user), 201
 
 
-@console_ns.route("/agents/invite-options")
+@console_ns.route("/agent/<uuid:agent_id>")
+class AgentAppApi(Resource):
+    @console_ns.response(200, "Agent app detail", console_ns.models[AgentAppDetailWithSite.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_current_user
+    @with_current_tenant_id
+    def get(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 _serialize_agent_app_detail(app_model, current_user=current_user)
+
+    @console_ns.expect(console_ns.models[AgentAppUpdatePayload.__name__])
+    @console_ns.response(200, "Agent app updated successfully", console_ns.models[AgentAppDetailWithSite.__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
+    @with_current_tenant_id
+    def put(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 = 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, current_user=current_user)
+
+    @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("/agent/<uuid:agent_id>/debug-conversation/refresh")
+class AgentDebugConversationRefreshApi(Resource):
+    @console_ns.response(
+        200,
+        "Agent debug conversation refreshed",
+        console_ns.models[AgentDebugConversationRefreshResponse.__name__],
+    )
+    @console_ns.response(403, "Insufficient permissions")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        debug_conversation_id = _agent_roster_service().refresh_agent_app_debug_conversation_id(
+            tenant_id=tenant_id,
+            agent_id=str(agent_id),
+            account_id=current_user.id,
+        )
+        return AgentDebugConversationRefreshResponse(debug_conversation_id=debug_conversation_id).model_dump(
+            mode="json"
+        )
+
+
+@console_ns.route("/agent/<uuid:agent_id>/copy")
+class AgentAppCopyApi(Resource):
+    @console_ns.expect(console_ns.models[AgentAppCopyPayload.__name__])
+    @console_ns.response(201, "Agent app copied successfully", console_ns.models[AgentAppDetailWithSite.__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
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        args = AgentAppCopyPayload.model_validate(console_ns.payload or {})
+        copied_app = _agent_roster_service().duplicate_agent_app(
+            tenant_id=tenant_id,
+            agent_id=str(agent_id),
+            account=current_user,
+            name=args.name,
+            description=args.description,
+            role=args.role,
+            icon_type=args.icon_type,
+            icon=args.icon,
+            icon_background=args.icon_background,
+        )
+        return _serialize_agent_app_detail(copied_app, current_user=current_user), 201
+
+
+@console_ns.route("/agent/<uuid:agent_id>/api-access")
+class AgentApiAccessApi(Resource):
+    @console_ns.response(200, "Agent service API access", console_ns.models[AgentApiAccessResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_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_api_access(app_model)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/api-enable")
+class AgentApiStatusApi(Resource):
+    @console_ns.expect(console_ns.models[AgentApiStatusPayload.__name__])
+    @console_ns.response(200, "Agent service API status updated", console_ns.models[AgentApiAccessResponse.__name__])
+    @console_ns.response(403, "Insufficient permissions")
+    @setup_required
+    @login_required
+    @is_admin_or_owner_required
+    @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    @with_current_tenant_id
+    def post(self, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        args = AgentApiStatusPayload.model_validate(console_ns.payload)
+        app_model = AppService().update_app_api_status(app_model, args.enable_api)
+        return _serialize_agent_api_access(app_model)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/api-keys")
+class AgentApiKeyListApi(BaseApiKeyListResource):
+    resource_type = ApiTokenType.APP
+    resource_model = App
+    resource_id_field = "app_id"
+    token_prefix = "app-"
+
+    @console_ns.response(200, "Agent service API keys", console_ns.models[ApiKeyList.__name__])
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID) -> dict[str, object]:
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return dump_response(ApiKeyList, self._get_api_key_list(str(app_model.id), tenant_id))
+
+    @console_ns.response(201, "Agent service API key created", console_ns.models[ApiKeyItem.__name__])
+    @console_ns.response(400, "Maximum keys exceeded")
+    @with_current_tenant_id
+    @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    def post(self, tenant_id: str, agent_id: UUID) -> tuple[dict[str, object], int]:
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return dump_response(ApiKeyItem, self._create_api_key(str(app_model.id), tenant_id)), 201
+
+
+@console_ns.route("/agent/<uuid:agent_id>/api-keys/<uuid:api_key_id>")
+class AgentApiKeyApi(BaseApiKeyResource):
+    resource_type = ApiTokenType.APP
+    resource_model = App
+    resource_id_field = "app_id"
+
+    @console_ns.response(204, "Agent service API key deleted")
+    @with_current_user
+    @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    def delete(self, tenant_id: str, current_user: Account, agent_id: UUID, api_key_id: UUID) -> tuple[str, int]:
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        self._delete_api_key(str(app_model.id), str(api_key_id), tenant_id, current_user)
+        return "", 204
+
+
+@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__])
@@ -114,49 +702,125 @@ class AgentInviteOptionsApi(Resource):
         )
 
 
-@console_ns.route("/agents/<uuid:agent_id>")
-class AgentRosterDetailApi(Resource):
-    @console_ns.response(200, "Agent detail", console_ns.models[AgentRosterResponse.__name__])
+@console_ns.route("/agent/<uuid:agent_id>/logs")
+class AgentLogsApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AgentLogsQuery))
+    @console_ns.response(200, "Agent logs", console_ns.models[AgentLogListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @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)),
-        )
+    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        query_data: dict[str, object] = dict(request.args.to_dict(flat=True))
+        query_data["sources"] = _multi_query_values("sources", "source")
+        query_data["statuses"] = _multi_query_values("statuses", "status")
+        query = AgentLogsQuery.model_validate(query_data)
+        start, end = _parse_observability_time_range(query.start, query.end, current_user)
+        try:
+            payload = _agent_observability_service().list_logs(
+                app=app_model,
+                agent_id=str(agent_id),
+                params=AgentLogQueryParams(
+                    page=query.page,
+                    limit=query.limit,
+                    keyword=query.keyword,
+                    statuses=tuple(query.statuses),
+                    sources=tuple(query.sources),
+                    sort_by=query.sort_by,
+                    sort_order=query.sort_order,
+                    start=start,
+                    end=end,
+                ),
+            )
+        except ValueError as exc:
+            abort(400, description=str(exc))
+        return dump_response(AgentLogListResponse, payload)
 
-    @console_ns.expect(console_ns.models[RosterAgentUpdatePayload.__name__])
-    @console_ns.response(200, "Agent updated", console_ns.models[AgentRosterResponse.__name__])
+
+@console_ns.route("/agent/<uuid:agent_id>/logs/<uuid:conversation_id>/messages")
+class AgentLogMessagesApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AgentLogsQuery))
+    @console_ns.response(200, "Agent log messages", console_ns.models[AgentLogMessageListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    @edit_permission_required
-    @with_current_user_id
+    @with_current_user
     @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
-            ),
-        )
+    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, conversation_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        query_data: dict[str, object] = dict(request.args.to_dict(flat=True))
+        query_data["sources"] = _multi_query_values("sources", "source")
+        query_data["statuses"] = _multi_query_values("statuses", "status")
+        query = AgentLogsQuery.model_validate(query_data)
+        start, end = _parse_observability_time_range(query.start, query.end, current_user)
+        try:
+            payload = _agent_observability_service().list_log_messages(
+                app=app_model,
+                agent_id=str(agent_id),
+                conversation_id=str(conversation_id),
+                params=AgentLogQueryParams(
+                    page=query.page,
+                    limit=query.limit,
+                    keyword=query.keyword,
+                    statuses=tuple(query.statuses),
+                    sources=tuple(query.sources),
+                    sort_by=query.sort_by,
+                    sort_order=query.sort_order,
+                    start=start,
+                    end=end,
+                ),
+            )
+        except ValueError as exc:
+            abort(400, description=str(exc))
+        return dump_response(AgentLogMessageListResponse, payload)
 
-    @console_ns.response(204, "Agent archived")
+
+@console_ns.route("/agent/<uuid:agent_id>/log-sources")
+class AgentLogSourcesApi(Resource):
+    @console_ns.response(200, "Agent log sources", console_ns.models[AgentLogSourceListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    @edit_permission_required
-    @with_current_user_id
+    @with_current_user
     @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
+    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        payload = _agent_observability_service().list_log_sources(app=app_model, agent_id=str(agent_id))
+        return dump_response(AgentLogSourceListResponse, payload)
 
 
-@console_ns.route("/agents/<uuid:agent_id>/versions")
+@console_ns.route("/agent/<uuid:agent_id>/statistics/summary")
+class AgentStatisticsSummaryApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AgentStatisticsQuery))
+    @console_ns.response(
+        200,
+        "Agent monitoring summary and chart data",
+        console_ns.models[AgentStatisticSummaryEnvelopeResponse.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        query = AgentStatisticsQuery.model_validate(request.args.to_dict(flat=True))
+        timezone = current_user.timezone or "UTC"
+        start, end = _parse_observability_time_range(query.start, query.end, current_user)
+        try:
+            payload = _agent_observability_service().get_statistics_summary(
+                app=app_model,
+                agent_id=str(agent_id),
+                params=AgentStatisticsQueryParams(source=query.source, start=start, end=end, timezone=timezone),
+            )
+        except ValueError as exc:
+            abort(400, description=str(exc))
+        return dump_response(AgentStatisticSummaryEnvelopeResponse, payload)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/versions")
 class AgentRosterVersionsApi(Resource):
     @console_ns.response(200, "Agent versions", console_ns.models[AgentConfigSnapshotListResponse.__name__])
     @setup_required
@@ -170,7 +834,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
@@ -186,3 +850,24 @@ class AgentRosterVersionDetailApi(Resource):
                 version_id=str(version_id),
             ),
         )
+
+
+@console_ns.route("/agent/<uuid:agent_id>/versions/<uuid:version_id>/restore")
+class AgentRosterVersionRestoreApi(Resource):
+    @console_ns.response(200, "Agent version restored", console_ns.models[AgentConfigSnapshotRestoreResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID, version_id: UUID):
+        return dump_response(
+            AgentConfigSnapshotRestoreResponse,
+            _agent_roster_service().restore_agent_version(
+                tenant_id=tenant_id,
+                agent_id=str(agent_id),
+                version_id=str(version_id),
+                account_id=current_user.id,
+            ),
+        )

api/controllers/console/apikey.py

@@ -9,6 +9,7 @@ from sqlalchemy import delete, func, select
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import Forbidden
 
+from configs import dify_config
 from controllers.common.schema import register_response_schema_models
 from extensions.ext_database import db
 from fields.base import ResponseModel
@@ -22,8 +23,11 @@ from services.api_token_service import ApiTokenCache
 
 from . import console_ns
 from .wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user,
@@ -143,7 +147,7 @@ class BaseApiKeyResource(Resource):
         assert self.resource_id_field is not None, "resource_id_field must be set"
         _get_resource(resource_id, current_tenant_id, self.resource_model)
 
-        if not current_user.is_admin_or_owner:
+        if not dify_config.RBAC_ENABLED and not current_user.is_admin_or_owner:
             raise Forbidden()
 
         key = db.session.scalar(
@@ -186,6 +190,7 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.response(400, "Maximum keys exceeded")
     @with_current_tenant_id
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     def post(self, current_tenant_id: str, resource_id: UUID) -> tuple[dict[str, object], int]:
         """Create a new API key for an app"""
         return dump_response(ApiKeyItem, self._create_api_key(str(resource_id), current_tenant_id)), 201
@@ -204,6 +209,7 @@ class AppApiKeyResource(BaseApiKeyResource):
     @console_ns.response(204, "API key deleted successfully")
     @with_current_user
     @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     def delete(
         self, current_tenant_id: str, current_user: Account, resource_id: UUID, api_key_id: UUID
     ) -> tuple[str, int]:
@@ -234,6 +240,7 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.response(400, "Maximum keys exceeded")
     @with_current_tenant_id
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_API_KEY_MANAGE)
     def post(self, current_tenant_id: str, resource_id: UUID) -> tuple[dict[str, object], int]:
         """Create a new API key for a dataset"""
         return dump_response(ApiKeyItem, self._create_api_key(str(resource_id), current_tenant_id)), 201
@@ -252,6 +259,7 @@ class DatasetApiKeyResource(BaseApiKeyResource):
     @console_ns.response(204, "API key deleted successfully")
     @with_current_user
     @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_API_KEY_MANAGE)
     def delete(
         self, current_tenant_id: str, current_user: Account, resource_id: UUID, api_key_id: UUID
     ) -> tuple[str, int]:

api/controllers/console/app/advanced_prompt_template.py

@@ -1,9 +1,17 @@
+from typing import Any
+
 from flask import request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field
 
+from controllers.common.schema import (
+    DEFAULT_REF_TEMPLATE_OPENAPI_3_0,
+    query_params_from_model,
+    register_response_schema_models,
+)
 from controllers.console import console_ns
 from controllers.console.wraps import account_initialization_required, setup_required
+from fields.base import ResponseModel
 from libs.login import login_required
 from services.advanced_prompt_template_service import AdvancedPromptTemplateArgs, AdvancedPromptTemplateService
 
@@ -15,19 +23,27 @@ class AdvancedPromptTemplateQuery(BaseModel):
     model_name: str = Field(..., description="Model name")
 
 
+class AdvancedPromptTemplateResponse(ResponseModel):
+    chat_prompt_config: dict[str, Any] | None = Field(default=None)
+    completion_prompt_config: dict[str, Any] | None = Field(default=None)
+
+
 console_ns.schema_model(
     AdvancedPromptTemplateQuery.__name__,
-    AdvancedPromptTemplateQuery.model_json_schema(ref_template="#/definitions/{model}"),
+    AdvancedPromptTemplateQuery.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0),
 )
+register_response_schema_models(console_ns, AdvancedPromptTemplateResponse)
 
 
 @console_ns.route("/app/prompt-templates")
 class AdvancedPromptTemplateList(Resource):
     @console_ns.doc("get_advanced_prompt_templates")
     @console_ns.doc(description="Get advanced prompt templates based on app mode and model configuration")
-    @console_ns.expect(console_ns.models[AdvancedPromptTemplateQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(AdvancedPromptTemplateQuery))
     @console_ns.response(
-        200, "Prompt templates retrieved successfully", fields.List(fields.Raw(description="Prompt template data"))
+        200,
+        "Prompt templates retrieved successfully",
+        console_ns.models[AdvancedPromptTemplateResponse.__name__],
     )
     @console_ns.response(400, "Invalid request parameters")
     @setup_required

api/controllers/console/app/agent.py

@@ -1,16 +1,62 @@
-from flask import request
-from flask_restx import Resource, fields
-from pydantic import BaseModel, Field, field_validator
+from typing import Any
+from uuid import UUID
 
-from controllers.common.schema import register_schema_models
+from flask import request
+from flask_restx import Resource
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import select
+
+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
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_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.model import App, AppMode
+from models import Account
+from models.model import App, AppMode, UploadFile
+from services.agent.composer_service import AgentComposerService
+from services.agent.skill_package_service import SkillManifest, SkillPackageError
+from services.agent.skill_standardize_service import SkillStandardizeService
+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
 
+_WORKFLOW_AGENT_DRIVE_APP_MODES = [AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]
+_AGENT_SKILL_UPLOAD_PARAMS = {
+    "file": {
+        "in": "formData",
+        "type": "file",
+        "required": True,
+        "description": "Skill package (.zip or .skill).",
+    }
+}
+
 
 class AgentLogQuery(BaseModel):
     message_id: str = Field(..., description="Message UUID")
@@ -22,7 +68,254 @@ class AgentLogQuery(BaseModel):
         return uuid_value(value)
 
 
-register_schema_models(console_ns, AgentLogQuery)
+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
+    start_time: str
+    elapsed_time: float | None = None
+    total_tokens: int
+    agent_mode: str
+    iterations: int
+
+
+class AgentToolCallResponse(ResponseModel):
+    status: str
+    error: str | None = None
+    time_cost: float | int
+    tool_name: str
+    tool_label: str
+    tool_input: dict[str, Any]
+    tool_output: dict[str, Any]
+    tool_parameters: dict[str, Any]
+    tool_icon: Any = Field(default=None)
+
+
+class AgentIterationLogResponse(ResponseModel):
+    tokens: int
+    tool_calls: list[AgentToolCallResponse]
+    tool_raw: dict[str, Any]
+    thought: str | None = None
+    created_at: str
+    files: list[Any] = Field(default_factory=list)
+
+
+class AgentLogResponse(ResponseModel):
+    meta: AgentLogMetaResponse
+    iterations: list[AgentIterationLogResponse]
+    files: list[Any] = Field(default_factory=list)
+
+
+class AgentUploadedSkillResponse(ResponseModel):
+    name: str
+    description: str
+    path: str
+    skill_md_key: str
+    archive_key: str | None = None
+
+
+class AgentSkillUploadResponse(ResponseModel):
+    skill: AgentUploadedSkillResponse
+    manifest: SkillManifest
+
+
+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
+
+
+class AgentDriveDeleteResponse(ResponseModel):
+    result: str
+    removed_keys: list[str] = Field(default_factory=list)
+
+
+register_schema_models(console_ns, AgentLogQuery, AgentDriveFilePayload, AgentDriveDeleteFileByAgentQuery)
+register_response_schema_models(
+    console_ns,
+    AgentDriveDeleteResponse,
+    AgentDriveFileCommitResponse,
+    AgentDriveFileResponse,
+    AgentLogResponse,
+    AgentUploadedSkillResponse,
+    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, app_model: App):
+    """Upload one skill package and commit its normalized files into the agent drive."""
+
+    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]
+    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"),
+        },
+    }, 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
+
+    try:
+        result = AgentDriveService().commit(
+            tenant_id=app_model.tenant_id,
+            user_id=current_user.id,
+            agent_id=agent_id,
+            items=[DriveCommitItem(key=key, file_ref=None)],
+        )
+    except AgentDriveError as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+    removed_keys = [item["key"] for item in result if item.get("removed")]
+    return {"result": "success", "removed_keys": removed_keys}
+
+
+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
+
+    try:
+        result = AgentDriveService().commit(
+            tenant_id=app_model.tenant_id,
+            user_id=current_user.id,
+            agent_id=agent_id,
+            items=[
+                DriveCommitItem(key=f"{slug}/SKILL.md", file_ref=None),
+                DriveCommitItem(key=f"{slug}/.DIFY-SKILL-FULL.zip", file_ref=None),
+            ],
+        )
+    except AgentDriveError as exc:
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+    removed_keys = [item["key"] for item in result if item.get("removed")]
+    return {"result": "success", "removed_keys": removed_keys}
+
+
+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")
@@ -30,17 +323,203 @@ class AgentLogApi(Resource):
     @console_ns.doc("get_agent_logs")
     @console_ns.doc(description="Get agent execution logs for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[AgentLogQuery.__name__])
-    @console_ns.response(
-        200, "Agent logs retrieved successfully", fields.List(fields.Raw(description="Agent log entries"))
-    )
+    @console_ns.doc(params=query_params_from_model(AgentLogQuery))
+    @console_ns.response(200, "Agent logs retrieved successfully", console_ns.models[AgentLogResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.AGENT_CHAT])
     def get(self, app_model: App):
         """Get agent logs"""
         args = AgentLogQuery.model_validate(request.args.to_dict(flat=True))
 
         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 + standardize a Skill into an Agent App drive")
+    @console_ns.doc(consumes=["multipart/form-data"], params={"agent_id": "Agent ID", **_AGENT_SKILL_UPLOAD_PARAMS})
+    @console_ns.response(201, "Skill uploaded into drive", console_ns.models[AgentSkillUploadResponse.__name__])
+    @console_ns.response(400, "Invalid skill package or no bound agent")
+    @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 _upload_skill_for_app(current_user=current_user, app_model=app_model)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/upload")
+class AgentSkillUploadApi(Resource):
+    @console_ns.doc("upload_agent_skill")
+    @console_ns.doc(description="Upload + standardize a Skill into the agent drive")
+    @console_ns.doc(
+        consumes=["multipart/form-data"],
+        params={
+            "app_id": "Application ID",
+            **query_params_from_model(AgentDriveMutationQuery),
+            **_AGENT_SKILL_UPLOAD_PARAMS,
+        },
+    )
+    @console_ns.response(201, "Skill uploaded into drive", console_ns.models[AgentSkillUploadResponse.__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 commit drive-backed skill files."""
+        return _upload_skill_for_app(current_user=current_user, app_model=app_model)
+
+
+@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 via drive commit-null semantics")
+    @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 by removing its known drive keys via commit-null")
+    @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,20 +9,27 @@ 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 (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
 )
 from events.app_event import app_model_config_was_updated
+from extensions.ext_database import db
 from libs.helper import dump_response
 from libs.login import login_required
 from models import Account
@@ -32,7 +39,6 @@ from models.agent_config_entities import (
     AgentSuggestedQuestionsAfterAnswerFeatureConfig,
     AgentTextToSpeechFeatureConfig,
 )
-from models.model import App, AppMode
 from services.agent_app_feature_service import AgentAppFeatureConfigService
 
 
@@ -64,28 +70,31 @@ 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
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @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(
             app_model=app_model,
             account=current_user,
             config=args.model_dump(exclude_none=True),
+            session=db.session,
         )
 
         app_model_config_was_updated.send(app_model, app_model_config=new_app_model_config)

api/controllers/console/app/agent_app_sandbox.py

@@ -0,0 +1,307 @@
+"""Console routes for Agent App and workflow Agent sandbox file access.
+
+The API keeps product-facing locators (conversation or workflow node identity)
+on this public boundary and proxies list/read/upload to the agent backend's new
+``/sandbox`` contract.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from dify_agent.client import DifyAgentClientError, DifyAgentHTTPError, DifyAgentTimeoutError
+from flask import request
+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,
+    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
+from libs.login import login_required
+from models.model import App, AppMode
+from services.agent_app_sandbox_service import (
+    AgentAppSandboxService,
+    AgentSandboxInspectorError,
+    WorkflowAgentSandboxService,
+)
+
+_NODE_EXECUTION_ID_DESCRIPTION = (
+    "Optional workflow node execution ID. When omitted, the latest active session for the node is used."
+)
+
+
+class AgentSandboxListQuery(BaseModel):
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
+    path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
+
+
+class AgentSandboxFileQuery(BaseModel):
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
+    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+
+
+class AgentSandboxUploadPayload(BaseModel):
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
+    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+
+
+class WorkflowAgentSandboxListQuery(BaseModel):
+    path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
+
+
+class WorkflowAgentSandboxFileQuery(BaseModel):
+    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
+
+
+class WorkflowAgentSandboxUploadPayload(BaseModel):
+    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
+
+
+class SandboxFileEntryResponse(ResponseModel):
+    name: str
+    type: Literal["file", "dir", "symlink", "other"]
+    size: int | None = None
+    mtime: int | None = None
+
+
+class SandboxListResponse(ResponseModel):
+    path: str
+    entries: list[SandboxFileEntryResponse] = Field(default_factory=list)
+    truncated: bool = False
+
+
+class SandboxReadResponse(ResponseModel):
+    path: str
+    size: int | None = None
+    truncated: bool
+    binary: bool
+    text: str | None = None
+
+
+class SandboxToolFileResponse(ResponseModel):
+    transfer_method: Literal["tool_file"] = "tool_file"
+    reference: str
+
+
+class SandboxUploadResponse(ResponseModel):
+    path: str
+    file: SandboxToolFileResponse
+
+
+register_schema_models(
+    console_ns,
+    AgentSandboxUploadPayload,
+    WorkflowAgentSandboxUploadPayload,
+)
+register_response_schema_models(console_ns, SandboxListResponse, SandboxReadResponse, SandboxUploadResponse)
+
+
+def _handle(exc: Exception) -> tuple[dict[str, object], int]:
+    if isinstance(exc, AgentSandboxInspectorError):
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+    if isinstance(exc, DifyAgentHTTPError):
+        detail = exc.detail
+        if isinstance(detail, dict):
+            return {
+                "code": detail.get("code", "agent_backend_error"),
+                "message": detail.get("message", str(exc)),
+            }, exc.status_code
+        return {"code": "agent_backend_error", "message": str(detail)}, exc.status_code
+    if isinstance(exc, DifyAgentTimeoutError | DifyAgentClientError):
+        return {"code": "agent_backend_unreachable", "message": str(exc)}, 502
+    raise exc
+
+
+@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={"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
+    @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)
+        query = query_params_from_request(AgentSandboxListQuery)
+        try:
+            result = AgentAppSandboxService().list_files(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                conversation_id=query.conversation_id,
+                path=query.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@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={"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
+    @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)
+        query = query_params_from_request(AgentSandboxFileQuery)
+        try:
+            result = AgentAppSandboxService().read_file(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                conversation_id=query.conversation_id,
+                path=query.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@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")
+    @console_ns.expect(console_ns.models[AgentSandboxUploadPayload.__name__])
+    @console_ns.response(200, "Uploaded", console_ns.models[SandboxUploadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    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(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                conversation_id=payload.conversation_id,
+                path=payload.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/sandbox/files")
+class WorkflowAgentSandboxListResource(Resource):
+    @console_ns.doc("list_workflow_agent_sandbox_files")
+    @console_ns.doc(description="List a directory in a workflow Agent node sandbox")
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "workflow_run_id": "Workflow run ID",
+            "node_id": "Workflow Agent node ID",
+            **query_params_from_model(WorkflowAgentSandboxListQuery),
+        }
+    )
+    @console_ns.response(200, "Listing returned", console_ns.models[SandboxListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_tenant_id
+    def get(self, tenant_id: str, app_model: App, workflow_run_id: UUID, node_id: str):
+        query = query_params_from_request(WorkflowAgentSandboxListQuery)
+        try:
+            result = WorkflowAgentSandboxService().list_files(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                workflow_run_id=str(workflow_run_id),
+                node_id=node_id,
+                node_execution_id=query.node_execution_id,
+                path=query.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@console_ns.route(
+    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/sandbox/files/read"
+)
+class WorkflowAgentSandboxReadResource(Resource):
+    @console_ns.doc("read_workflow_agent_sandbox_file")
+    @console_ns.doc(description="Read a text/binary preview file in a workflow Agent node sandbox")
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "workflow_run_id": "Workflow run ID",
+            "node_id": "Workflow Agent node ID",
+            **query_params_from_model(WorkflowAgentSandboxFileQuery),
+        }
+    )
+    @console_ns.response(200, "Preview returned", console_ns.models[SandboxReadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_tenant_id
+    def get(self, tenant_id: str, app_model: App, workflow_run_id: UUID, node_id: str):
+        query = query_params_from_request(WorkflowAgentSandboxFileQuery)
+        try:
+            result = WorkflowAgentSandboxService().read_file(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                workflow_run_id=str(workflow_run_id),
+                node_id=node_id,
+                node_execution_id=query.node_execution_id,
+                path=query.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@console_ns.route(
+    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/sandbox/files/upload"
+)
+class WorkflowAgentSandboxUploadResource(Resource):
+    @console_ns.doc("upload_workflow_agent_sandbox_file")
+    @console_ns.doc(description="Upload one workflow Agent sandbox file as a Dify ToolFile mapping")
+    @console_ns.expect(console_ns.models[WorkflowAgentSandboxUploadPayload.__name__])
+    @console_ns.response(200, "Uploaded", console_ns.models[SandboxUploadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_tenant_id
+    def post(self, tenant_id: str, app_model: App, workflow_run_id: UUID, node_id: str):
+        payload = WorkflowAgentSandboxUploadPayload.model_validate(request.get_json(silent=True) or {})
+        try:
+            result = WorkflowAgentSandboxService().upload_file(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                workflow_run_id=str(workflow_run_id),
+                node_id=node_id,
+                node_execution_id=payload.node_execution_id,
+                path=payload.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()

api/controllers/console/app/agent_app_workspace.py

@@ -1,319 +0,0 @@
-"""Agent App sandbox file-system inspector (read-only).
-
-Exposes the PRD "rc1-like sandbox file system, downloadable not editable" view
-for an Agent App conversation: list a directory, preview a file, or download a
-file from the conversation's shell-layer workspace. The API never touches
-shellctl directly — it resolves the conversation's sandbox ``session_id`` from
-the stored session snapshot and proxies to the agent backend's read-only
-workspace endpoints.
-"""
-
-from typing import Literal
-from uuid import UUID
-
-from flask import Response
-from flask_restx import Resource, fields
-from pydantic import BaseModel, Field
-
-from clients.agent_backend.errors import AgentBackendHTTPError, AgentBackendTransportError
-from clients.agent_backend.workspace_files_client import WorkspaceDownloadResult
-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.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
-from fields.base import ResponseModel
-from libs.login import current_account_with_tenant, login_required
-from models.model import App, AppMode
-from services.agent_app_workspace_service import (
-    AgentAppWorkspaceService,
-    AgentWorkspaceInspectorError,
-    WorkflowAgentWorkspaceService,
-)
-
-
-class _WorkspaceFileDownloadField(fields.Raw):
-    __schema_type__ = "string"
-    __schema_format__ = "binary"
-
-
-class AgentWorkspaceListQuery(BaseModel):
-    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
-    path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
-
-
-class AgentWorkspaceFileQuery(BaseModel):
-    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
-    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
-
-
-class WorkflowAgentWorkspaceListQuery(BaseModel):
-    path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
-    node_execution_id: str | None = Field(
-        default=None,
-        description=(
-            "Optional workflow node execution ID. When omitted, the latest active session for the node is used."
-        ),
-    )
-
-
-class WorkflowAgentWorkspaceFileQuery(BaseModel):
-    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
-    node_execution_id: str | None = Field(
-        default=None,
-        description=(
-            "Optional workflow node execution ID. When omitted, the latest active session for the node is used."
-        ),
-    )
-
-
-class WorkspaceFileEntryResponse(ResponseModel):
-    name: str
-    type: Literal["file", "dir", "symlink"]
-    size: int
-    mtime: int
-
-
-class WorkspaceListResponse(ResponseModel):
-    path: str
-    entries: list[WorkspaceFileEntryResponse] = Field(default_factory=list)
-    truncated: bool = False
-
-
-class WorkspacePreviewResponse(ResponseModel):
-    path: str
-    size: int
-    truncated: bool
-    binary: bool
-    text: str | None = None
-
-
-register_response_schema_models(console_ns, WorkspaceListResponse)
-register_response_schema_models(console_ns, WorkspacePreviewResponse)
-
-
-def _handle(exc: Exception) -> tuple[dict[str, object], int]:
-    if isinstance(exc, AgentWorkspaceInspectorError):
-        return {"code": exc.code, "message": exc.message}, exc.status_code
-    if isinstance(exc, AgentBackendHTTPError):
-        detail = exc.detail
-        if isinstance(detail, dict):
-            return {
-                "code": detail.get("code", "agent_backend_error"),
-                "message": detail.get("message", str(exc)),
-            }, exc.status_code
-        return {"code": "agent_backend_error", "message": str(detail)}, exc.status_code
-    if isinstance(exc, AgentBackendTransportError):
-        return {"code": "agent_backend_unreachable", "message": str(exc)}, 502
-    raise exc
-
-
-def _download_response(result: WorkspaceDownloadResult) -> Response | tuple[dict[str, object], int]:
-    if result.truncated:
-        return {
-            "code": "workspace_file_too_large",
-            "message": (
-                "file exceeds the workspace download limit; use preview for partial text or download a smaller file"
-            ),
-            "size": result.size,
-        }, 413
-    filename = result.path.rsplit("/", 1)[-1] or "download"
-    return Response(
-        result.content,
-        mimetype="application/octet-stream",
-        headers={
-            "Content-Disposition": f'attachment; filename="{filename}"',
-            "Content-Length": str(len(result.content)),
-            "X-Workspace-File-Size": str(result.size),
-        },
-    )
-
-
-@console_ns.route("/apps/<uuid:app_id>/agent-workspace/files")
-class AgentAppWorkspaceListResource(Resource):
-    @console_ns.doc("list_agent_app_workspace_files")
-    @console_ns.doc(description="List a directory in an Agent App conversation's sandbox workspace (read-only)")
-    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentWorkspaceListQuery)})
-    @console_ns.response(200, "Listing returned", console_ns.models[WorkspaceListResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
-    def get(self, app_model: App):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(AgentWorkspaceListQuery)
-        try:
-            result = AgentAppWorkspaceService().list_files(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                conversation_id=query.conversation_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return result.model_dump()
-
-
-@console_ns.route("/apps/<uuid:app_id>/agent-workspace/files/preview")
-class AgentAppWorkspacePreviewResource(Resource):
-    @console_ns.doc("preview_agent_app_workspace_file")
-    @console_ns.doc(description="Preview a text/binary file in an Agent App conversation's sandbox workspace")
-    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentWorkspaceFileQuery)})
-    @console_ns.response(200, "Preview returned", console_ns.models[WorkspacePreviewResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
-    def get(self, app_model: App):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(AgentWorkspaceFileQuery)
-        try:
-            result = AgentAppWorkspaceService().preview(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                conversation_id=query.conversation_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return result.model_dump()
-
-
-@console_ns.route("/apps/<uuid:app_id>/agent-workspace/files/download")
-class AgentAppWorkspaceDownloadResource(Resource):
-    @console_ns.doc("download_agent_app_workspace_file")
-    @console_ns.doc(description="Download a file from an Agent App conversation's sandbox workspace (read-only)")
-    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentWorkspaceFileQuery)})
-    @console_ns.doc(produces=["application/octet-stream"])
-    @console_ns.response(200, "File bytes", _WorkspaceFileDownloadField)
-    @console_ns.response(413, "File exceeds the workspace download limit")
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
-    def get(self, app_model: App):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(AgentWorkspaceFileQuery)
-        try:
-            result = AgentAppWorkspaceService().download(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                conversation_id=query.conversation_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return _download_response(result)
-
-
-@console_ns.route(
-    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/workspace/files"
-)
-class WorkflowAgentWorkspaceListResource(Resource):
-    @console_ns.doc("list_workflow_agent_workspace_files")
-    @console_ns.doc(description="List a directory in a Workflow Agent node's sandbox workspace (read-only)")
-    @console_ns.doc(
-        params={
-            "app_id": "Application ID",
-            "workflow_run_id": "Workflow run ID",
-            "node_id": "Workflow Agent node ID",
-            **query_params_from_model(WorkflowAgentWorkspaceListQuery),
-        }
-    )
-    @console_ns.response(200, "Listing returned", console_ns.models[WorkspaceListResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, workflow_run_id: UUID, node_id: str):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(WorkflowAgentWorkspaceListQuery)
-        try:
-            result = WorkflowAgentWorkspaceService().list_files(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                workflow_run_id=str(workflow_run_id),
-                node_id=node_id,
-                node_execution_id=query.node_execution_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return result.model_dump()
-
-
-@console_ns.route(
-    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/workspace/files/preview"
-)
-class WorkflowAgentWorkspacePreviewResource(Resource):
-    @console_ns.doc("preview_workflow_agent_workspace_file")
-    @console_ns.doc(description="Preview a text/binary file in a Workflow Agent node's sandbox workspace")
-    @console_ns.doc(
-        params={
-            "app_id": "Application ID",
-            "workflow_run_id": "Workflow run ID",
-            "node_id": "Workflow Agent node ID",
-            **query_params_from_model(WorkflowAgentWorkspaceFileQuery),
-        }
-    )
-    @console_ns.response(200, "Preview returned", console_ns.models[WorkspacePreviewResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, workflow_run_id: UUID, node_id: str):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(WorkflowAgentWorkspaceFileQuery)
-        try:
-            result = WorkflowAgentWorkspaceService().preview(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                workflow_run_id=str(workflow_run_id),
-                node_id=node_id,
-                node_execution_id=query.node_execution_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return result.model_dump()
-
-
-@console_ns.route(
-    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/workspace/files/download"
-)
-class WorkflowAgentWorkspaceDownloadResource(Resource):
-    @console_ns.doc("download_workflow_agent_workspace_file")
-    @console_ns.doc(description="Download a file from a Workflow Agent node's sandbox workspace (read-only)")
-    @console_ns.doc(
-        params={
-            "app_id": "Application ID",
-            "workflow_run_id": "Workflow run ID",
-            "node_id": "Workflow Agent node ID",
-            **query_params_from_model(WorkflowAgentWorkspaceFileQuery),
-        }
-    )
-    @console_ns.doc(produces=["application/octet-stream"])
-    @console_ns.response(200, "File bytes", _WorkspaceFileDownloadField)
-    @console_ns.response(413, "File exceeds the workspace download limit")
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, workflow_run_id: UUID, node_id: str):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(WorkflowAgentWorkspaceFileQuery)
-        try:
-            result = WorkflowAgentWorkspaceService().download(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                workflow_run_id=str(workflow_run_id),
-                node_id=node_id,
-                node_execution_id=query.node_execution_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return _download_response(result)

api/controllers/console/app/agent_drive_inspector.py

@@ -0,0 +1,408 @@
+"""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
+
+import json
+from collections.abc import Mapping
+from typing import Any
+from uuid import UUID
+
+from flask import Response
+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 AgentDriveSkillInspectQuery(BaseModel):
+    node_id: str | None = Field(default=None, description="Workflow node ID (workflow composer variant)")
+
+
+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
+    is_skill: bool | None = None
+    skill_metadata: str | None = None
+
+
+class AgentDriveListResponse(ResponseModel):
+    items: list[AgentDriveItemResponse] = Field(default_factory=list)
+
+
+class AgentDriveSkillItemResponse(ResponseModel):
+    path: str
+    skill_md_key: str
+    archive_key: str | None = None
+    name: str
+    description: str
+    size: int | None = None
+    mime_type: str | None = None
+    hash: str | None = None
+    created_at: int | None = None
+
+
+class AgentDriveSkillListResponse(ResponseModel):
+    items: list[AgentDriveSkillItemResponse] = Field(default_factory=list)
+
+
+class AgentDriveSkillFileResponse(ResponseModel):
+    path: str
+    name: str
+    type: str
+    drive_key: str | None = None
+    available_in_drive: bool
+
+
+class AgentDriveSkillMarkdownResponse(ResponseModel):
+    key: str
+    size: int | None = None
+    truncated: bool
+    binary: bool
+    text: str | None = None
+
+
+class AgentDriveSkillInspectResponse(ResponseModel):
+    path: str
+    skill_md_key: str
+    archive_key: str | None = None
+    name: str
+    description: str
+    size: int | None = None
+    mime_type: str | None = None
+    hash: str | None = None
+    created_at: int | None = None
+    source: str
+    files: list[AgentDriveSkillFileResponse] = Field(default_factory=list)
+    file_tree: list[dict[str, Any]] = Field(default_factory=list)
+    skill_md: AgentDriveSkillMarkdownResponse
+    warnings: list[str] = 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,
+    AgentDriveDownloadResponse,
+    AgentDriveListResponse,
+    AgentDrivePreviewResponse,
+    AgentDriveSkillInspectResponse,
+    AgentDriveSkillListResponse,
+)
+
+
+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
+
+
+def _json_response(data: Mapping[str, Any]):
+    return Response(
+        response=json.dumps(data, ensure_ascii=False, separators=(",", ":")),
+        content_type="application/json; charset=utf-8",
+    )
+
+
+_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/skills")
+class AgentDriveSkillListByAgentApi(Resource):
+    @console_ns.doc("list_agent_drive_skills_by_agent")
+    @console_ns.doc(description="List drive-backed skills for an Agent App")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.response(200, "Drive skills", console_ns.models[AgentDriveSkillListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        try:
+            items = AgentDriveService().list_skills(tenant_id=tenant_id, agent_id=str(agent_id))
+        except AgentDriveError as exc:
+            return _handle(exc)
+        return {"items": items}
+
+
+@console_ns.route("/agent/<uuid:agent_id>/drive/skills/<path:skill_path>/inspect")
+class AgentDriveSkillInspectByAgentApi(Resource):
+    @console_ns.doc("inspect_agent_drive_skill_by_agent")
+    @console_ns.doc(description="Inspect one drive-backed skill for slash-menu hover/detail UI")
+    @console_ns.doc(params={"agent_id": "Agent ID", "skill_path": "Skill path/slug, e.g. tender-analyzer"})
+    @console_ns.response(200, "Drive skill inspect view", console_ns.models[AgentDriveSkillInspectResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID, skill_path: str):
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        try:
+            return _json_response(
+                AgentDriveService().inspect_skill(
+                    tenant_id=tenant_id,
+                    agent_id=str(agent_id),
+                    skill_path=skill_path,
+                )
+            )
+        except AgentDriveError as exc:
+            return _handle(exc)
+
+
+@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/skills")
+class AgentDriveSkillListApi(Resource):
+    @console_ns.doc("list_agent_drive_skills")
+    @console_ns.doc(description="List drive-backed skills for the bound agent")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveListQuery)})
+    @console_ns.response(200, "Drive skills", console_ns.models[AgentDriveSkillListResponse.__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().list_skills(tenant_id=app_model.tenant_id, agent_id=agent_id)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        return {"items": items}
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/drive/skills/<path:skill_path>/inspect")
+class AgentDriveSkillInspectApi(Resource):
+    @console_ns.doc("inspect_agent_drive_skill")
+    @console_ns.doc(description="Inspect one drive-backed skill for slash-menu hover/detail UI")
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "skill_path": "Skill path/slug, e.g. tender-analyzer",
+            **query_params_from_model(AgentDriveSkillInspectQuery),
+        }
+    )
+    @console_ns.response(200, "Drive skill inspect view", console_ns.models[AgentDriveSkillInspectResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, app_model: App, skill_path: str):
+        query = query_params_from_request(AgentDriveSkillInspectQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        try:
+            return _json_response(
+                AgentDriveService().inspect_skill(
+                    tenant_id=app_model.tenant_id,
+                    agent_id=agent_id,
+                    skill_path=skill_path,
+                )
+            )
+        except AgentDriveError as exc:
+            return _handle(exc)
+
+
+@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",
+    "AgentDriveSkillInspectApi",
+    "AgentDriveSkillInspectByAgentApi",
+    "AgentDriveSkillListApi",
+    "AgentDriveSkillListByAgentApi",
+]

api/controllers/console/app/annotation.py

@@ -6,16 +6,20 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, TypeAdapter, field_validator
 
 from controllers.common.errors import NoFileUploadedError, TooManyFilesError
-from controllers.common.schema import register_schema_models
+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 (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     annotation_import_concurrency_limit,
     annotation_import_rate_limit,
     cloud_edition_billing_resource_check,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
 )
+from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from fields.annotation_fields import (
     Annotation,
@@ -24,6 +28,7 @@ from fields.annotation_fields import (
     AnnotationHitHistoryList,
     AnnotationList,
 )
+from fields.base import ResponseModel
 from libs.helper import uuid_value
 from libs.login import login_required
 from services.annotation_service import (
@@ -56,7 +61,10 @@ class CreateAnnotationPayload(BaseModel):
     question: str | None = Field(default=None, description="Question text")
     answer: str | None = Field(default=None, description="Answer text")
     content: str | None = Field(default=None, description="Content text")
-    annotation_reply: dict[str, Any] | None = Field(default=None, description="Annotation reply data")
+    annotation_reply: dict[str, Any] | None = Field(
+        default=None,
+        description="Annotation reply data",
+    )
 
     @field_validator("message_id")
     @classmethod
@@ -70,13 +78,18 @@ class UpdateAnnotationPayload(BaseModel):
     question: str | None = None
     answer: str | None = None
     content: str | None = None
-    annotation_reply: dict[str, Any] | None = None
+    annotation_reply: dict[str, Any] | None = Field(default=None)
 
 
 class AnnotationReplyStatusQuery(BaseModel):
     action: Literal["enable", "disable"]
 
 
+class AnnotationHitHistoryListQuery(BaseModel):
+    page: int = Field(default=1, ge=1, description="Page number")
+    limit: int = Field(default=20, ge=1, description="Page size")
+
+
 class AnnotationFilePayload(BaseModel):
     message_id: str = Field(..., description="Message ID")
 
@@ -86,6 +99,25 @@ class AnnotationFilePayload(BaseModel):
         return uuid_value(value)
 
 
+class AnnotationJobStatusResponse(ResponseModel):
+    job_id: str | None = None
+    job_status: str | None = None
+    error_msg: str | None = None
+    record_count: int | None = None
+
+
+class AnnotationEmbeddingModelResponse(ResponseModel):
+    embedding_provider_name: str | None = None
+    embedding_model_name: str | None = None
+
+
+class AnnotationSettingResponse(ResponseModel):
+    id: str | None = None
+    enabled: bool
+    score_threshold: float | None = None
+    embedding_model: AnnotationEmbeddingModelResponse | None = None
+
+
 register_schema_models(
     console_ns,
     Annotation,
@@ -99,8 +131,19 @@ register_schema_models(
     CreateAnnotationPayload,
     UpdateAnnotationPayload,
     AnnotationReplyStatusQuery,
+    AnnotationHitHistoryListQuery,
     AnnotationFilePayload,
 )
+register_response_schema_models(
+    console_ns,
+    Annotation,
+    AnnotationList,
+    AnnotationExportList,
+    AnnotationHitHistory,
+    AnnotationHitHistoryList,
+    AnnotationJobStatusResponse,
+    AnnotationSettingResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotation-reply/<string:action>")
@@ -109,13 +152,14 @@ class AnnotationReplyActionApi(Resource):
     @console_ns.doc(description="Enable or disable annotation reply for an app")
     @console_ns.doc(params={"app_id": "Application ID", "action": "Action to perform (enable/disable)"})
     @console_ns.expect(console_ns.models[AnnotationReplyPayload.__name__])
-    @console_ns.response(200, "Action completed successfully")
+    @console_ns.response(200, "Action completed successfully", console_ns.models[AnnotationJobStatusResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID, action: Literal["enable", "disable"]):
         args = AnnotationReplyPayload.model_validate(console_ns.payload)
         match action:
@@ -136,12 +180,17 @@ class AppAnnotationSettingDetailApi(Resource):
     @console_ns.doc("get_annotation_setting")
     @console_ns.doc(description="Get annotation settings for an app")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Annotation settings retrieved successfully")
+    @console_ns.response(
+        200,
+        "Annotation settings retrieved successfully",
+        console_ns.models[AnnotationSettingResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID):
         result = AppAnnotationService.get_app_annotation_setting_by_app_id(str(app_id))
         return result, 200
@@ -153,12 +202,13 @@ class AppAnnotationSettingUpdateApi(Resource):
     @console_ns.doc(description="Update annotation settings for an app")
     @console_ns.doc(params={"app_id": "Application ID", "annotation_setting_id": "Annotation setting ID"})
     @console_ns.expect(console_ns.models[AnnotationSettingUpdatePayload.__name__])
-    @console_ns.response(200, "Settings updated successfully")
+    @console_ns.response(200, "Settings updated successfully", console_ns.models[AnnotationSettingResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID, annotation_setting_id: UUID):
         annotation_setting_id_str = str(annotation_setting_id)
 
@@ -176,13 +226,18 @@ class AnnotationReplyActionStatusApi(Resource):
     @console_ns.doc("get_annotation_reply_action_status")
     @console_ns.doc(description="Get status of annotation reply action job")
     @console_ns.doc(params={"app_id": "Application ID", "job_id": "Job ID", "action": "Action type"})
-    @console_ns.response(200, "Job status retrieved successfully")
+    @console_ns.response(
+        200,
+        "Job status retrieved successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID, job_id: UUID, action: str):
         job_id_str = str(job_id)
         app_annotation_job_key = f"{action}_app_annotation_job_{job_id_str}"
@@ -204,13 +259,14 @@ class AnnotationApi(Resource):
     @console_ns.doc("list_annotations")
     @console_ns.doc(description="Get annotations for an app with pagination")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[AnnotationListQuery.__name__])
-    @console_ns.response(200, "Annotations retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(AnnotationListQuery))
+    @console_ns.response(200, "Annotations retrieved successfully", console_ns.models[AnnotationList.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID):
         args = AnnotationListQuery.model_validate(request.args.to_dict(flat=True))
         page = args.page
@@ -239,6 +295,7 @@ class AnnotationApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID):
         args = CreateAnnotationPayload.model_validate(console_ns.payload)
         upsert_args: UpsertAnnotationArgs = {}
@@ -257,6 +314,8 @@ class AnnotationApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
+    @console_ns.response(204, "Annotations deleted successfully")
     def delete(self, app_id: UUID):
 
         # Use request.args.getlist to get annotation_ids array directly
@@ -294,6 +353,7 @@ class AnnotationExportApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID):
         annotation_list = AppAnnotationService.export_annotation_list_by_app_id(str(app_id))
         annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
@@ -321,6 +381,7 @@ class AnnotationUpdateDeleteApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID, annotation_id: UUID):
         args = UpdateAnnotationPayload.model_validate(console_ns.payload)
         update_args: UpdateAnnotationArgs = {}
@@ -328,15 +389,19 @@ class AnnotationUpdateDeleteApi(Resource):
             update_args["answer"] = args.answer
         if args.question is not None:
             update_args["question"] = args.question
-        annotation = AppAnnotationService.update_app_annotation_directly(update_args, str(app_id), str(annotation_id))
+        annotation = AppAnnotationService.update_app_annotation_directly(
+            update_args, str(app_id), str(annotation_id), db.session
+        )
         return Annotation.model_validate(annotation, from_attributes=True).model_dump(mode="json")
 
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @console_ns.response(204, "Annotation deleted successfully")
     def delete(self, app_id: UUID, annotation_id: UUID):
-        AppAnnotationService.delete_app_annotation(str(app_id), str(annotation_id))
+        AppAnnotationService.delete_app_annotation(str(app_id), str(annotation_id), db.session)
         return "", 204
 
 
@@ -345,7 +410,11 @@ class AnnotationBatchImportApi(Resource):
     @console_ns.doc("batch_import_annotations")
     @console_ns.doc(description="Batch import annotations from CSV file with rate limiting and security checks")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Batch import started successfully")
+    @console_ns.response(
+        200,
+        "Batch import started successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(400, "No file uploaded or too many files")
     @console_ns.response(413, "File too large")
@@ -357,6 +426,7 @@ class AnnotationBatchImportApi(Resource):
     @annotation_import_rate_limit
     @annotation_import_concurrency_limit
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID):
         from configs import dify_config
 
@@ -398,13 +468,18 @@ class AnnotationBatchImportStatusApi(Resource):
     @console_ns.doc("get_batch_import_status")
     @console_ns.doc(description="Get status of batch import job")
     @console_ns.doc(params={"app_id": "Application ID", "job_id": "Job ID"})
-    @console_ns.response(200, "Job status retrieved successfully")
+    @console_ns.response(
+        200,
+        "Job status retrieved successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID, job_id: UUID):
         indexing_cache_key = f"app_annotation_batch_import_{str(job_id)}"
         cache_result = redis_client.get(indexing_cache_key)
@@ -424,11 +499,7 @@ class AnnotationHitHistoryListApi(Resource):
     @console_ns.doc("list_annotation_hit_histories")
     @console_ns.doc(description="Get hit histories for an annotation")
     @console_ns.doc(params={"app_id": "Application ID", "annotation_id": "Annotation ID"})
-    @console_ns.expect(
-        console_ns.parser()
-        .add_argument("page", type=int, location="args", default=1, help="Page number")
-        .add_argument("limit", type=int, location="args", default=20, help="Page size")
-    )
+    @console_ns.doc(params=query_params_from_model(AnnotationHitHistoryListQuery))
     @console_ns.response(
         200,
         "Hit histories retrieved successfully",
@@ -439,6 +510,7 @@ class AnnotationHitHistoryListApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID, annotation_id: UUID):
         page = request.args.get("page", default=1, type=int)
         limit = request.args.get("limit", default=20, type=int)

api/controllers/console/app/app.py

@@ -3,7 +3,7 @@ import re
 import uuid
 from collections.abc import Sequence
 from datetime import datetime
-from typing import Any, Literal, cast
+from typing import Any, Literal
 
 from flask import request
 from flask_restx import Resource
@@ -11,8 +11,10 @@ from pydantic import AliasChoices, BaseModel, Field, computed_field, field_valid
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 from werkzeug.datastructures import MultiDict
-from werkzeug.exceptions import BadRequest
+from werkzeug.exceptions import BadRequest, NotFound
 
+from configs import dify_config
+from controllers.common.app_access import resolve_app_access_filter
 from controllers.common.fields import RedirectUrlResponse, SimpleResultResponse
 from controllers.common.helpers import FileInfo
 from controllers.common.schema import (
@@ -25,11 +27,14 @@ from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model, with_session
 from controllers.console.workspace.models import LoadBalancingPayload
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     cloud_edition_billing_resource_check,
     edit_permission_required,
     enterprise_license_required,
     is_admin_or_owner_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user,
@@ -48,6 +53,7 @@ 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, AppListSortBy, AppService, CreateAppParams, StarredAppListParams
+from services.enterprise import rbac_service as enterprise_rbac_service
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import ImportMode, ImportStatus
 from services.entities.knowledge_entities.knowledge_entities import (
@@ -64,7 +70,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)
 
@@ -72,12 +78,13 @@ _logger = logging.getLogger(__name__)
 _TAG_IDS_BRACKET_PATTERN = re.compile(r"^tag_ids\[(\d+)\]$")
 _CREATOR_IDS_BRACKET_PATTERN = re.compile(r"^creator_ids\[(\d+)\]$")
 AppListMode = Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"]
+DEFAULT_APP_LIST_MODE: AppListMode = "all"
 
 
 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")
+    mode: AppListMode = Field(default=DEFAULT_APP_LIST_MODE, description="App mode filter")
     sort_by: AppListSortBy = Field(
         default="last_modified",
         description="Sort apps by last modified, recently created, or earliest created",
@@ -163,9 +170,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")
@@ -224,6 +229,11 @@ class AppTracePayload(BaseModel):
         return value
 
 
+class AppTraceResponse(ResponseModel):
+    enabled: bool
+    tracing_provider: str | None = None
+
+
 type JSONValue = Any
 
 
@@ -395,7 +405,13 @@ class AppPartial(ResponseModel):
     create_user_name: str | None = None
     author_name: str | None = None
     has_draft_trigger: bool | None = None
+    permission_keys: list[str] = Field(default_factory=list)
+    # 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
     is_starred: bool = False
+    maintainer: str | None = None
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -431,6 +447,8 @@ class AppDetail(ResponseModel):
     updated_at: int | None = None
     access_mode: str | None = None
     tags: list[Tag] = Field(default_factory=list)
+    permission_keys: list[str] = Field(default_factory=list)
+    maintainer: str | None = None
 
     @field_validator("created_at", "updated_at", mode="before")
     @classmethod
@@ -446,6 +464,8 @@ 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
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -507,7 +527,7 @@ def _enrich_app_list_items(session: Session, *, apps: Sequence[App], tenant_id:
 
 
 register_enum_models(console_ns, RetrievalMethod, WorkflowExecutionStatus, DatasetPermissionEnum)
-register_response_schema_models(console_ns, RedirectUrlResponse, SimpleResultResponse)
+register_response_schema_models(console_ns, AppTraceResponse, RedirectUrlResponse, SimpleResultResponse)
 
 register_schema_models(
     console_ns,
@@ -528,10 +548,7 @@ register_schema_models(
     ModelConfig,
     Site,
     DeletedTool,
-    AppPartial,
     AppDetail,
-    AppDetailWithSite,
-    AppPagination,
     AppExportResponse,
     Segmentation,
     PreProcessingRule,
@@ -551,6 +568,13 @@ register_schema_models(
     LoadBalancingPayload,
 )
 
+register_response_schema_models(
+    console_ns,
+    AppPartial,
+    AppDetailWithSite,
+    AppPagination,
+)
+
 
 @console_ns.route("/apps")
 class AppListApi(Resource):
@@ -579,27 +603,51 @@ class AppListApi(Resource):
             is_created_by_me=args.is_created_by_me,
         )
 
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+            str(current_tenant_id),
+            current_user_id,
+        )
+        if dify_config.RBAC_ENABLED:
+            access_filter = resolve_app_access_filter(
+                str(current_tenant_id),
+                current_user_id,
+                permissions=permissions,
+            )
+            access_filter.apply_to_params(params)
+
         # get app list
         app_service = AppService()
-        app_pagination = app_service.get_paginate_apps(current_user_id, current_tenant_id, params)
+        app_pagination = app_service.get_paginate_apps(current_user_id, current_tenant_id, params, db.session)
         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
 
+        app_ids = [str(app.id) for app in app_pagination.items]
+        permission_keys_map = permissions.app.permission_keys_by_resource_ids(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)
+        if app_pagination.items:
+            pagination_model = pagination_model.model_copy(
+                update={
+                    "data": [
+                        item.model_copy(update={"permission_keys": permission_keys_map.get(str(item.id), [])})
+                        for item in pagination_model.data
+                    ]
+                }
+            )
         return pagination_model.model_dump(mode="json"), 200
 
     @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
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT, resource_required=False)
     @cloud_edition_billing_resource_check("apps")
     @edit_permission_required
     @with_current_user
@@ -618,7 +666,14 @@ 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)
+        permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(
+            str(current_tenant_id),
+            current_user.id,
+            [str(app.id)],
+        )
+        app_detail = AppDetailWithSite.model_validate(app, from_attributes=True).model_copy(
+            update={"permission_keys": permission_keys_map.get(str(app.id), [])}
+        )
         return app_detail.model_dump(mode="json"), 201
 
 
@@ -648,7 +703,7 @@ class StarredAppListApi(Resource):
             is_created_by_me=args.is_created_by_me,
         )
 
-        app_pagination = AppService().get_paginate_starred_apps(current_user_id, current_tenant_id, params)
+        app_pagination = AppService().get_paginate_starred_apps(current_user_id, current_tenant_id, params, db.session)
         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
@@ -704,8 +759,11 @@ class AppApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
+    @with_current_user
+    @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=None)
-    def get(self, app_model: App):
+    def get(self, current_tenant_id: str, current_user: Account, app_model: App):
         """Get app detail"""
         app_service = AppService()
 
@@ -713,9 +771,18 @@ 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)
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+            str(current_tenant_id),
+            current_user.id,
+            app_id=str(app_model.id),
+        )
+        permission_keys_map = permissions.app.permission_keys_by_resource_ids([str(app_model.id)])
+
+        response_model = AppDetailWithSite.model_validate(app_model, from_attributes=True).model_copy(
+            update={"permission_keys": permission_keys_map.get(str(app_model.id), [])}
+        )
         return response_model.model_dump(mode="json")
 
     @console_ns.doc("update_app")
@@ -728,8 +795,9 @@ class AppApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model(mode=None)
     def put(self, app_model: App):
         """Update app"""
         args = UpdateAppPayload.model_validate(console_ns.payload)
@@ -754,11 +822,12 @@ class AppApi(Resource):
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.response(204, "App deleted successfully")
     @console_ns.response(403, "Insufficient permissions")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_DELETE)
+    @get_app_model
     def delete(self, app_model: App):
         """Delete app"""
         app_service = AppService()
@@ -778,10 +847,12 @@ class AppCopyApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @with_current_user
-    def post(self, current_user: Account, app_model: App):
+    @with_current_tenant_id
+    @get_app_model(mode=None)
+    def post(self, current_tenant_id: str, current_user: Account, app_model: App):
         """Copy app"""
         # The role of the current user in the ta table must be admin, owner, or editor
         args = CopyAppPayload.model_validate(console_ns.payload or {})
@@ -823,7 +894,17 @@ class AppCopyApi(Resource):
             stmt = select(App).where(App.id == result.app_id)
             app = session.scalar(stmt)
 
-        response_model = AppDetailWithSite.model_validate(app, from_attributes=True)
+        if not app:
+            raise NotFound("App not found")
+
+        permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(
+            str(current_tenant_id),
+            current_user.id,
+            [str(app.id)],
+        )
+        response_model = AppDetailWithSite.model_validate(app, from_attributes=True).model_copy(
+            update={"permission_keys": permission_keys_map.get(str(app.id), [])}
+        )
         return response_model.model_dump(mode="json"), 201
 
 
@@ -832,14 +913,15 @@ class AppExportApi(Resource):
     @console_ns.doc("export_app")
     @console_ns.doc(description="Export application configuration as DSL")
     @console_ns.doc(params={"app_id": "Application ID to export"})
-    @console_ns.expect(console_ns.models[AppExportQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(AppExportQuery))
     @console_ns.response(200, "App exported successfully", console_ns.models[AppExportResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL)
+    @get_app_model
     def get(self, app_model: App):
         """Export app"""
         args = AppExportQuery.model_validate(request.args.to_dict(flat=True))
@@ -860,12 +942,12 @@ class AppPublishToCreatorsPlatformApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL)
     @with_current_user_id
+    @get_app_model(mode=None)
     def post(self, current_user_id: str, app_model: App):
         """Publish app to Creators Platform"""
-        from configs import dify_config
         from core.helper.creators import get_redirect_url, upload_dsl
 
         if not dify_config.CREATORS_PLATFORM_FEATURES_ENABLED:
@@ -890,8 +972,9 @@ class AppNameApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model(mode=None)
     def post(self, app_model: App):
         args = AppNamePayload.model_validate(console_ns.payload)
 
@@ -907,13 +990,14 @@ class AppIconApi(Resource):
     @console_ns.doc(description="Update application icon")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AppIconPayload.__name__])
-    @console_ns.response(200, "Icon updated successfully")
+    @console_ns.response(200, "Icon updated successfully", console_ns.models[AppDetail.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model(mode=None)
     def post(self, app_model: App):
         args = AppIconPayload.model_validate(console_ns.payload or {})
 
@@ -939,8 +1023,9 @@ class AppSiteStatus(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    @get_app_model(mode=None)
     def post(self, app_model: App):
         args = AppSiteStatusPayload.model_validate(console_ns.payload)
 
@@ -962,6 +1047,7 @@ class AppApiStatus(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @get_app_model(mode=None)
     def post(self, app_model: App):
         args = AppApiStatusPayload.model_validate(console_ns.payload)
@@ -977,11 +1063,16 @@ class AppTraceApi(Resource):
     @console_ns.doc("get_app_trace")
     @console_ns.doc(description="Get app tracing configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Trace configuration retrieved successfully")
+    @console_ns.response(
+        200,
+        "Trace configuration retrieved successfully",
+        console_ns.models[AppTraceResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @with_session
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model
     def get(self, session: Session, app_model: App):
         """Get app trace"""
@@ -1003,6 +1094,7 @@ class AppTraceApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TRACING_CONFIG)
     @get_app_model
     def post(self, app_model: App):
         # add app trace

api/controllers/console/app/app_import.py

@@ -2,25 +2,36 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
+from configs import dify_config
 from controllers.common.schema import register_enum_models, register_schema_models
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     cloud_edition_billing_resource_check,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_user,
 )
 from extensions.ext_database import db
-from libs.login import login_required
+from extensions.ext_redis import redis_client
+from libs.login import current_account_with_tenant, login_required
 from models.account import Account
 from models.model import App
-from services.app_dsl_service import AppDslService, Import
+from services.app_dsl_service import (
+    IMPORT_INFO_REDIS_KEY_PREFIX,
+    AppDslService,
+    Import,
+    PendingData,
+)
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import CheckDependenciesResult, ImportStatus
 from services.feature_service import FeatureService
 
 from .. import console_ns
+from .permission_keys import get_app_permission_keys
 
 
 class AppImportPayload(BaseModel):
@@ -39,6 +50,24 @@ register_enum_models(console_ns, ImportStatus)
 register_schema_models(console_ns, AppImportPayload, Import, CheckDependenciesResult)
 
 
+def _current_user_and_tenant_id(current_user: Account | None) -> tuple[Account, str | None]:
+    if current_user is None:
+        account, tenant_id = current_account_with_tenant()
+        return account, str(tenant_id) if tenant_id else None
+
+    current_tenant_id = getattr(current_user, "current_tenant_id", None)
+    if current_tenant_id:
+        return current_user, str(current_tenant_id)
+
+    current_tenant = getattr(current_user, "current_tenant", None)
+    current_tenant_object_id = getattr(current_tenant, "id", None)
+    if current_tenant_object_id:
+        return current_user, str(current_tenant_object_id)
+
+    account, fallback_tenant_id = current_account_with_tenant()
+    return account, str(fallback_tenant_id) if fallback_tenant_id else None
+
+
 @console_ns.route("/apps/imports")
 class AppImportApi(Resource):
     @console_ns.expect(console_ns.models[AppImportPayload.__name__])
@@ -50,10 +79,11 @@ class AppImportApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("apps")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL, resource_required=False)
     @with_current_user
-    def post(self, current_user: Account):
-        # Check user role first
+    def post(self, current_user: Account | None = None):
         args = AppImportPayload.model_validate(console_ns.payload)
+        current_user = current_user if current_user is not None else _current_user_and_tenant_id(None)[0]
 
         # AppDslService performs internal commits for some creation paths, so use a plain
         # Session here instead of nesting it inside sessionmaker(...).begin().
@@ -77,6 +107,20 @@ class AppImportApi(Resource):
                 session.rollback()
             else:
                 session.commit()
+
+        is_created_app = args.app_id is None and result.status in {
+            ImportStatus.COMPLETED,
+            ImportStatus.COMPLETED_WITH_WARNINGS,
+        }
+        if dify_config.RBAC_ENABLED and is_created_app and result.app_id:
+            current_user, current_tenant_id = _current_user_and_tenant_id(current_user)
+            if current_tenant_id:
+                result.permission_keys = get_app_permission_keys(
+                    current_tenant_id,
+                    current_user.id,
+                    result.app_id,
+                )
+
         if result.app_id and FeatureService.get_system_features().webapp_auth.enabled:
             # update web app setting as private
             EnterpriseService.WebAppAuth.update_app_access_mode(result.app_id, "private")
@@ -99,9 +143,16 @@ class AppImportConfirmApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL, resource_required=False)
     @with_current_user
-    def post(self, current_user: Account, import_id: str):
-        # Check user role first
+    def post(self, current_user: Account | None = None, import_id: str = ""):
+        current_user = current_user if current_user is not None else _current_user_and_tenant_id(None)[0]
+        redis_key = f"{IMPORT_INFO_REDIS_KEY_PREFIX}{import_id}"
+        pending_data_raw = redis_client.get(redis_key)
+        pending_data: PendingData | None = None
+        if pending_data_raw:
+            pending_data = PendingData.model_validate_json(pending_data_raw)
+
         with Session(db.engine, expire_on_commit=False) as session:
             import_service = AppDslService(session)
             # Confirm import
@@ -112,6 +163,24 @@ class AppImportConfirmApi(Resource):
             else:
                 session.commit()
 
+        is_created_app = bool(
+            pending_data
+            and pending_data.app_id is None
+            and result.status
+            in {
+                ImportStatus.COMPLETED,
+                ImportStatus.COMPLETED_WITH_WARNINGS,
+            }
+        )
+        if dify_config.RBAC_ENABLED and is_created_app and result.app_id:
+            current_user, current_tenant_id = _current_user_and_tenant_id(current_user)
+            if current_tenant_id:
+                result.permission_keys = get_app_permission_keys(
+                    current_tenant_id,
+                    current_user.id,
+                    result.app_id,
+                )
+
         # Return appropriate status code based on result
         if result.status == ImportStatus.FAILED:
             return result.model_dump(mode="json"), 400
@@ -120,12 +189,17 @@ class AppImportConfirmApi(Resource):
 
 @console_ns.route("/apps/imports/<string:app_id>/check-dependencies")
 class AppImportCheckDependenciesApi(Resource):
-    @console_ns.response(200, "Dependencies checked", console_ns.models[CheckDependenciesResult.__name__])
+    @console_ns.response(
+        200,
+        "Dependencies checked",
+        console_ns.models[CheckDependenciesResult.__name__],
+    )
     @setup_required
     @login_required
     @get_app_model
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_model: App):
         with Session(db.engine, expire_on_commit=False) as session:
             import_service = AppDslService(session)

api/controllers/console/app/audio.py

@@ -1,12 +1,14 @@
 import logging
+from typing import Any
 
 from flask import request
-from flask_restx import Resource, fields
-from pydantic import BaseModel, Field
+from flask_restx import Resource
+from pydantic import BaseModel, Field, RootModel
 from werkzeug.exceptions import InternalServerError
 
 import services
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import AudioBinaryResponse
+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.error import (
     AppUnavailableError,
@@ -20,8 +22,15 @@ from controllers.console.app.error import (
     UnsupportedAudioTypeError,
 )
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+)
 from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
+from extensions.ext_database import db
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs.login import login_required
 from models import App, AppMode
@@ -51,7 +60,12 @@ class AudioTranscriptResponse(BaseModel):
     text: str = Field(description="Transcribed text from audio")
 
 
+class TextToSpeechVoiceListResponse(RootModel[list[dict[str, Any]]]):
+    root: list[dict[str, Any]]
+
+
 register_schema_models(console_ns, AudioTranscriptResponse, TextToSpeechPayload, TextToSpeechVoiceQuery)
+register_response_schema_models(console_ns, AudioBinaryResponse, TextToSpeechVoiceListResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/audio-to-text")
@@ -113,18 +127,23 @@ class ChatMessageTextApi(Resource):
     @console_ns.doc(description="Convert text to speech for chat messages")
     @console_ns.doc(params={"app_id": "App ID"})
     @console_ns.expect(console_ns.models[TextToSpeechPayload.__name__])
-    @console_ns.response(200, "Text to speech conversion successful")
+    @console_ns.response(
+        200,
+        "Text to speech conversion successful",
+        console_ns.models[AudioBinaryResponse.__name__],
+    )
     @console_ns.response(400, "Bad request - Invalid parameters")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @get_app_model
     def post(self, app_model: App):
         try:
             payload = TextToSpeechPayload.model_validate(console_ns.payload)
 
             response = AudioService.transcript_tts(
                 app_model=app_model,
+                session=db.session,
                 text=payload.text,
                 voice=payload.voice,
                 message_id=payload.message_id,
@@ -162,15 +181,18 @@ class TextModesApi(Resource):
     @console_ns.doc("get_text_to_speech_voices")
     @console_ns.doc(description="Get available TTS voices for a specific language")
     @console_ns.doc(params={"app_id": "App ID"})
-    @console_ns.expect(console_ns.models[TextToSpeechVoiceQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TextToSpeechVoiceQuery))
     @console_ns.response(
-        200, "TTS voices retrieved successfully", fields.List(fields.Raw(description="Available voices"))
+        200,
+        "TTS voices retrieved successfully",
+        console_ns.models[TextToSpeechVoiceListResponse.__name__],
     )
     @console_ns.response(400, "Invalid language parameter")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model
     def get(self, app_model: App):
         try:
             args = TextToSpeechVoiceQuery.model_validate(request.args.to_dict(flat=True))

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
@@ -7,9 +8,10 @@ from pydantic import BaseModel, Field, field_validator
 from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
 
 import services
-from controllers.common.fields import SimpleResultResponse
+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,
@@ -20,9 +22,13 @@ from controllers.console.app.error import (
 )
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
     with_current_user_id,
 )
@@ -34,12 +40,15 @@ from core.errors.error import (
     QuotaExceededError,
 )
 from core.helper.trace_id_helper import get_external_trace_id
+from extensions.ext_database import db
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs import helper
 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.errors import AgentNotFoundError
+from services.agent.roster_service import AgentRosterService
 from services.app_generate_service import AppGenerateService
 from services.app_task_service import AppTaskService
 from services.errors.llm import InvokeRateLimitError
@@ -64,8 +73,14 @@ class BaseMessagePayload(BaseModel):
     # Soul, so no override ``model_config`` is sent; chat / agent-chat / completion
     # debugging still pass it. Optional here, required in practice by those modes
     # downstream when their config is built from args.
-    model_config_data: dict[str, Any] = Field(default_factory=dict, alias="model_config")
-    files: list[Any] | None = Field(default=None, description="Uploaded files")
+    model_config_data: dict[str, Any] = Field(
+        default_factory=dict,
+        alias="model_config",
+    )
+    files: list[Any] | None = Field(
+        default=None,
+        description="Uploaded files",
+    )
     response_mode: Literal["blocking", "streaming"] = Field(default="blocking", description="Response mode")
     retriever_from: str = Field(default="dev", description="Retriever source")
 
@@ -88,7 +103,7 @@ class ChatMessagePayload(BaseMessagePayload):
 
 
 register_schema_models(console_ns, CompletionMessagePayload, ChatMessagePayload)
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(console_ns, GeneratedAppResponse, SimpleResultResponse)
 
 
 # define completion message api for user
@@ -98,14 +113,15 @@ class CompletionMessageApi(Resource):
     @console_ns.doc(description="Generate completion message for debugging")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[CompletionMessagePayload.__name__])
-    @console_ns.response(200, "Completion generated successfully")
+    @console_ns.response(200, "Completion generated successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(404, "App not found")
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @get_app_model(mode=AppMode.COMPLETION)
     def post(self, current_user: Account, app_model: App):
         args_model = CompletionMessagePayload.model_validate(console_ns.payload)
         args = args_model.model_dump(exclude_none=True, by_alias=True)
@@ -150,8 +166,8 @@ class CompletionMessageStopApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @with_current_user_id
+    @get_app_model(mode=AppMode.COMPLETION)
     def post(self, current_user_id: str, app_model: App, task_id: str):
 
         AppTaskService.stop_task(
@@ -170,61 +186,45 @@ class ChatMessageApi(Resource):
     @console_ns.doc(description="Generate chat message for debugging")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[ChatMessagePayload.__name__])
-    @console_ns.response(200, "Chat message generated successfully")
+    @console_ns.response(200, "Chat message generated successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(404, "App or conversation not found")
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.AGENT])
     @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)
+    @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.AGENT])
+    def post(self, current_tenant_id: str, current_user: Account, app_model: App):
+        return _create_chat_message(current_tenant_id=current_tenant_id, 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,
+
+@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
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @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_tenant_id=current_tenant_id,
+            current_user=current_user,
+            app_model=app_model,
+            agent_id=str(agent_id),
         )
-        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("/apps/<uuid:app_id>/chat-messages/<string:task_id>/stop")
@@ -236,15 +236,116 @@ class ChatMessageStopApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user_id
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     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 _resolve_current_user_agent_debug_conversation_id(
+    *, current_tenant_id: str, current_user: Account, app_model: App, agent_id: str | None
+) -> str:
+    roster_service = AgentRosterService(db.session)
+    if agent_id:
+        return roster_service.get_or_create_agent_app_debug_conversation_id(
+            tenant_id=current_tenant_id,
+            agent_id=agent_id,
+            account_id=current_user.id,
         )
 
-        return {"result": "success"}, 200
+    agent = roster_service.get_app_backing_agent(tenant_id=current_tenant_id, app_id=str(app_model.id))
+    if agent is None:
+        raise AgentNotFoundError()
+    return roster_service.get_or_create_agent_app_debug_conversation_id(
+        tenant_id=current_tenant_id,
+        agent_id=agent.id,
+        account_id=current_user.id,
+    )
+
+
+def _create_chat_message(
+    *, current_user: Account, app_model: App, current_tenant_id: str | None = None, agent_id: str | None = None
+):
+    raw_payload = console_ns.payload or {}
+    args_model = ChatMessagePayload.model_validate(raw_payload)
+    args = args_model.model_dump(exclude_none=True, by_alias=True)
+
+    if AppMode.value_of(app_model.mode) == AppMode.AGENT:
+        debug_conversation_id = _resolve_current_user_agent_debug_conversation_id(
+            current_tenant_id=current_tenant_id or app_model.tenant_id,
+            current_user=current_user,
+            app_model=app_model,
+            agent_id=agent_id,
+        )
+        if args_model.conversation_id and args_model.conversation_id != debug_conversation_id:
+            raise NotFound("Conversation Not Exists.")
+        args["conversation_id"] = debug_conversation_id
+
+    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()
+
+
+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/conversation.py

@@ -9,12 +9,15 @@ from sqlalchemy import func, or_
 from sqlalchemy.orm import selectinload
 from werkzeug.exceptions import NotFound
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_user,
 )
@@ -91,15 +94,16 @@ class CompletionConversationApi(Resource):
     @console_ns.doc("list_completion_conversations")
     @console_ns.doc(description="Get completion conversations with pagination and filtering")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[CompletionConversationQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(CompletionConversationQuery))
     @console_ns.response(200, "Success", console_ns.models[ConversationPaginationResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=AppMode.COMPLETION)
     def get(self, current_user: Account, app_model: App):
         args = CompletionConversationQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -169,9 +173,10 @@ class CompletionConversationDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=AppMode.COMPLETION)
     def get(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
         return ConversationMessageDetailResponse.model_validate(
@@ -187,9 +192,10 @@ class CompletionConversationDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
+    @get_app_model(mode=AppMode.COMPLETION)
     def delete(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
 
@@ -206,15 +212,16 @@ class ChatConversationApi(Resource):
     @console_ns.doc("list_chat_conversations")
     @console_ns.doc(description="Get chat conversations with pagination, filtering and summary")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[ChatConversationQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ChatConversationQuery))
     @console_ns.response(200, "Success", console_ns.models[ConversationWithSummaryPaginationResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def get(self, current_user: Account, app_model: App):
         args = ChatConversationQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -323,9 +330,10 @@ class ChatConversationDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def get(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
         return ConversationDetailResponse.model_validate(
@@ -340,10 +348,11 @@ class ChatConversationDetailApi(Resource):
     @console_ns.response(404, "Conversation not found")
     @setup_required
     @login_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def delete(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
 

api/controllers/console/app/conversation_variables.py

@@ -9,10 +9,16 @@ from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+)
 from extensions.ext_database import db
 from fields._value_type_serializer import serialize_value_type
 from fields.base import ResponseModel
@@ -84,7 +90,7 @@ class ConversationVariablesApi(Resource):
     @console_ns.doc("get_conversation_variables")
     @console_ns.doc(description="Get conversation variables for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[ConversationVariablesQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ConversationVariablesQuery))
     @console_ns.response(
         200,
         "Conversation variables retrieved successfully",
@@ -93,6 +99,7 @@ class ConversationVariablesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @get_app_model(mode=AppMode.ADVANCED_CHAT)
     def get(self, app_model: App):
         args = ConversationVariablesQuery.model_validate(request.args.to_dict(flat=True))

api/controllers/console/app/generator.py

@@ -1,11 +1,12 @@
 from collections.abc import Sequence
-from typing import Literal
+from typing import Any, Literal
 
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from sqlalchemy.orm import Session
 
-from controllers.common.schema import register_enum_models, register_schema_models
+from controllers.common.fields import SimpleDataResponse
+from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     CompletionRequestError,
@@ -36,7 +37,11 @@ class InstructionGeneratePayload(BaseModel):
     current: str = Field(default="", description="Current instruction text")
     language: str = Field(default="javascript", description="Programming language (javascript/python)")
     instruction: str = Field(..., description="Instruction for generation")
-    model_config_data: ModelConfig = Field(..., alias="model_config", description="Model configuration")
+    model_config_data: ModelConfig = Field(
+        ...,
+        alias="model_config",
+        description="Model configuration",
+    )
     ideal_output: str = Field(default="", description="Expected ideal output")
 
 
@@ -44,6 +49,13 @@ class InstructionTemplatePayload(BaseModel):
     type: str = Field(..., description="Instruction template type")
 
 
+# Upper bound for the generator's free-text inputs. Generous for prose (a
+# detailed instruction rarely passes 2k chars) while keeping the
+# planner+builder prompts well inside every mainstream context window.
+# Mirrored by the ``maxLength`` on the frontend generator textarea.
+_MAX_INSTRUCTION_LENGTH = 10_000
+
+
 class WorkflowGeneratePayload(BaseModel):
     """Payload for the cmd+k `/create` and `/refine` workflow generator endpoint.
 
@@ -55,13 +67,21 @@ class WorkflowGeneratePayload(BaseModel):
     mode: Literal["workflow", "advanced-chat"] = Field(..., description="Target app mode for the generated graph")
     instruction: str = Field(..., description="Natural-language workflow description")
     ideal_output: str = Field(default="", description="Optional sample output for grounding")
-    model_config_data: ModelConfig = Field(..., alias="model_config", description="Model configuration")
+    model_config_data: ModelConfig = Field(
+        ...,
+        alias="model_config",
+        description="Model configuration",
+    )
     current_graph: dict | None = Field(
         default=None,
         description="Existing draft graph to refine (cmd+k `/refine`); omit for create-from-scratch",
     )
 
 
+class GeneratorResponse(RootModel[Any]):
+    root: Any
+
+
 register_enum_models(console_ns, LLMMode)
 register_schema_models(
     console_ns,
@@ -73,6 +93,7 @@ register_schema_models(
     WorkflowGeneratePayload,
     ModelConfig,
 )
+register_response_schema_models(console_ns, GeneratorResponse, SimpleDataResponse)
 
 
 @console_ns.route("/rule-generate")
@@ -80,7 +101,11 @@ class RuleGenerateApi(Resource):
     @console_ns.doc("generate_rule_config")
     @console_ns.doc(description="Generate rule configuration using LLM")
     @console_ns.expect(console_ns.models[RuleGeneratePayload.__name__])
-    @console_ns.response(200, "Rule configuration generated successfully")
+    @console_ns.response(
+        200,
+        "Rule configuration generated successfully",
+        console_ns.models[GeneratorResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -109,7 +134,7 @@ class RuleCodeGenerateApi(Resource):
     @console_ns.doc("generate_rule_code")
     @console_ns.doc(description="Generate code rules using LLM")
     @console_ns.expect(console_ns.models[RuleCodeGeneratePayload.__name__])
-    @console_ns.response(200, "Code rules generated successfully")
+    @console_ns.response(200, "Code rules generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -141,7 +166,7 @@ class RuleStructuredOutputGenerateApi(Resource):
     @console_ns.doc("generate_structured_output")
     @console_ns.doc(description="Generate structured output rules using LLM")
     @console_ns.expect(console_ns.models[RuleStructuredOutputPayload.__name__])
-    @console_ns.response(200, "Structured output generated successfully")
+    @console_ns.response(200, "Structured output generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -173,7 +198,7 @@ class InstructionGenerateApi(Resource):
     @console_ns.doc("generate_instruction")
     @console_ns.doc(description="Generate instruction for workflow nodes or general use")
     @console_ns.expect(console_ns.models[InstructionGeneratePayload.__name__])
-    @console_ns.response(200, "Instruction generated successfully")
+    @console_ns.response(200, "Instruction generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters or flow/workflow not found")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -268,7 +293,7 @@ class InstructionGenerationTemplateApi(Resource):
     @console_ns.doc("get_instruction_template")
     @console_ns.doc(description="Get instruction generation template")
     @console_ns.expect(console_ns.models[InstructionTemplatePayload.__name__])
-    @console_ns.response(200, "Template retrieved successfully")
+    @console_ns.response(200, "Template retrieved successfully", console_ns.models[SimpleDataResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
@@ -300,7 +325,7 @@ class WorkflowGenerateApi(Resource):
     @console_ns.doc("generate_workflow_graph")
     @console_ns.doc(description="Generate a Dify workflow graph from natural language")
     @console_ns.expect(console_ns.models[WorkflowGeneratePayload.__name__])
-    @console_ns.response(200, "Workflow graph generated successfully")
+    @console_ns.response(200, "Workflow graph generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -320,6 +345,22 @@ class WorkflowGenerateApi(Resource):
                 "errors": [{"code": "EMPTY_INSTRUCTION", "detail": "Instruction is required"}],
             }, 400
 
+        # Bound the prompt at the boundary too: an arbitrarily long
+        # instruction (or pasted document) blows the planner/builder context
+        # window and fails with an opaque provider error after two slow LLM
+        # calls. The cap matches the frontend textarea's maxLength.
+        if len(args.instruction) > _MAX_INSTRUCTION_LENGTH or len(args.ideal_output) > _MAX_INSTRUCTION_LENGTH:
+            return {
+                "error": "Instruction is too long",
+                "errors": [
+                    {
+                        "code": "INSTRUCTION_TOO_LONG",
+                        "detail": f"Instruction and ideal output must each be at most "
+                        f"{_MAX_INSTRUCTION_LENGTH} characters",
+                    }
+                ],
+            }, 400
+
         try:
             result = WorkflowGeneratorService.generate_workflow_graph(
                 tenant_id=current_tenant_id,

api/controllers/console/app/mcp_server.py

@@ -12,8 +12,11 @@ from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
 )
@@ -27,13 +30,19 @@ from models.model import App, AppMCPServer
 
 class MCPServerCreatePayload(BaseModel):
     description: str | None = Field(default=None, description="Server description")
-    parameters: dict[str, Any] = Field(..., description="Server parameters configuration")
+    parameters: dict[str, Any] = Field(
+        ...,
+        description="Server parameters configuration",
+    )
 
 
 class MCPServerUpdatePayload(BaseModel):
     id: str = Field(..., description="Server ID")
     description: str | None = Field(default=None, description="Server description")
-    parameters: dict[str, Any] = Field(..., description="Server parameters configuration")
+    parameters: dict[str, Any] = Field(
+        ...,
+        description="Server parameters configuration",
+    )
     status: str | None = Field(default=None, description="Server status")
 
 
@@ -77,6 +86,7 @@ class AppMCPServerController(Resource):
     @login_required
     @account_initialization_required
     @setup_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model
     def get(self, app_model: App):
         server = db.session.scalar(select(AppMCPServer).where(AppMCPServer.app_id == app_model.id).limit(1))
@@ -93,11 +103,12 @@ class AppMCPServerController(Resource):
     )
     @console_ns.response(403, "Insufficient permissions")
     @account_initialization_required
-    @get_app_model
     @login_required
     @setup_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_tenant_id
+    @get_app_model
     def post(self, current_tenant_id: str, app_model: App):
         payload = MCPServerCreatePayload.model_validate(console_ns.payload or {})
 
@@ -127,11 +138,12 @@ class AppMCPServerController(Resource):
     )
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(404, "Server not found")
-    @get_app_model
     @login_required
     @setup_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model
     def put(self, app_model: App):
         payload = MCPServerUpdatePayload.model_validate(console_ns.payload or {})
         server = db.session.get(AppMCPServer, payload.id)
@@ -168,6 +180,7 @@ class AppMCPServerRefreshController(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @with_current_tenant_id
     def get(self, current_tenant_id: str, server_id: UUID):
         server = db.session.scalar(

api/controllers/console/app/message.py

@@ -10,9 +10,10 @@ from sqlalchemy import exists, func, select
 from werkzeug.exceptions import InternalServerError, NotFound
 
 from controllers.common.controller_schemas import MessageFeedbackPayload as _MessageFeedbackPayloadBase
-from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+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,
@@ -22,9 +23,13 @@ from controllers.console.app.error import (
 from controllers.console.app.wraps import get_app_model
 from controllers.console.explore.error import AppSuggestedQuestionsAfterAnswerDisabledError
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
 )
 from core.app.entities.app_invoke_entities import InvokeFrom
@@ -48,6 +53,7 @@ from libs.login import login_required
 from models.account import Account
 from models.enums import FeedbackFromSource, FeedbackRating
 from models.model import App, AppMode, Conversation, Message, MessageAnnotation, MessageFeedback
+from services.conversation_service import ConversationService
 from services.errors.conversation import ConversationNotExistsError
 from services.errors.message import MessageNotExistsError, SuggestedQuestionsAfterAnswerDisabledError
 from services.message_service import MessageService, attach_message_extra_contents
@@ -161,12 +167,16 @@ register_schema_models(
     ChatMessagesQuery,
     MessageFeedbackPayload,
     FeedbackExportQuery,
+)
+register_response_schema_models(
+    console_ns,
     AnnotationCountResponse,
     SuggestedQuestionsResponse,
     MessageDetailResponse,
     MessageInfiniteScrollPaginationResponse,
+    SimpleResultResponse,
+    TextFileResponse,
 )
-register_response_schema_models(console_ns, SimpleResultResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/chat-messages")
@@ -174,76 +184,38 @@ class ChatMessageListApi(Resource):
     @console_ns.doc("list_chat_messages")
     @console_ns.doc(description="Get chat messages for a conversation with pagination")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[ChatMessagesQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ChatMessagesQuery))
     @console_ns.response(200, "Success", console_ns.models[MessageInfiniteScrollPaginationResponse.__name__])
     @console_ns.response(404, "Conversation not found")
     @login_required
     @account_initialization_required
     @setup_required
-    @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())
+    @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
+    def get(self, current_user: Account, app_model: App):
+        return _list_chat_messages(app_model=app_model, current_user=current_user)
 
-        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
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_current_user
+    @with_current_tenant_id
+    def get(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 _list_chat_messages(app_model=app_model, current_user=current_user)
 
 
 @console_ns.route("/apps/<uuid:app_id>/feedbacks")
@@ -255,50 +227,31 @@ class MessageFeedbackApi(Resource):
     @console_ns.response(200, "Feedback updated successfully", console_ns.models[SimpleResultResponse.__name__])
     @console_ns.response(404, "Message not found")
     @console_ns.response(403, "Insufficient permissions")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_user
+    @get_app_model
     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")
@@ -311,10 +264,11 @@ class MessageAnnotationCountApi(Resource):
         "Annotation count retrieved successfully",
         console_ns.models[AnnotationCountResponse.__name__],
     )
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model
     def get(self, app_model: App):
         count = db.session.scalar(
             select(func.count(MessageAnnotation.id)).where(MessageAnnotation.app_id == app_model.id)
@@ -337,34 +291,32 @@ class MessageSuggestedQuestionApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     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")
@@ -372,14 +324,19 @@ class MessageFeedbackExportApi(Resource):
     @console_ns.doc("export_feedbacks")
     @console_ns.doc(description="Export user feedback data for Google Sheets")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[FeedbackExportQuery.__name__])
-    @console_ns.response(200, "Feedback data exported successfully")
+    @console_ns.doc(params=query_params_from_model(FeedbackExportQuery))
+    @console_ns.response(
+        200,
+        "Feedback data exported successfully",
+        console_ns.models[TextFileResponse.__name__],
+    )
     @console_ns.response(400, "Invalid parameters")
     @console_ns.response(500, "Internal server error")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model
     def get(self, app_model: App):
         args = FeedbackExportQuery.model_validate(request.args.to_dict())
 
@@ -388,7 +345,8 @@ class MessageFeedbackExportApi(Resource):
 
         try:
             export_data = FeedbackService.export_feedbacks(
-                app_id=app_model.id,
+                app_model.id,
+                session=db.session(),
                 from_source=args.from_source,
                 rating=args.rating,
                 has_comment=args.has_comment,
@@ -414,19 +372,183 @@ class MessageApi(Resource):
     @console_ns.doc(params={"app_id": "Application ID", "message_id": "Message ID"})
     @console_ns.response(200, "Message retrieved successfully", console_ns.models[MessageDetailResponse.__name__])
     @console_ns.response(404, "Message not found")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model
     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, current_user: Account | None = None):
+    args = ChatMessagesQuery.model_validate(request.args.to_dict())
+
+    if AppMode.value_of(app_model.mode) == AppMode.AGENT and current_user is not None:
+        try:
+            conversation = ConversationService.get_conversation(
+                app_model=app_model,
+                conversation_id=args.conversation_id,
+                user=current_user,
+            )
+        except ConversationNotExistsError:
+            raise NotFound("Conversation Not Exists.")
+    else:
+        conversation = db.session.scalar(
+            select(Conversation)
+            .where(Conversation.id == args.conversation_id, Conversation.app_id == app_model.id)
+            .limit(1)
         )
 
-        if not message:
-            raise NotFound("Message Not Exists.")
+    if not conversation:
+        raise NotFound("Conversation Not Exists.")
 
-        attach_message_extra_contents([message])
-        return MessageDetailResponse.model_validate(message, from_attributes=True).model_dump(mode="json")
+    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")
+
+
+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/model_config.py

@@ -5,12 +5,16 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
-from controllers.common.schema import register_schema_models
+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.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user_id,
@@ -29,19 +33,44 @@ from services.app_model_config_service import AppModelConfigService
 class ModelConfigRequest(BaseModel):
     provider: str | None = Field(default=None, description="Model provider")
     model: str | None = Field(default=None, description="Model name")
-    configs: dict[str, Any] | None = Field(default=None, description="Model configuration parameters")
+    configs: dict[str, Any] | None = Field(
+        default=None,
+        description="Model configuration parameters",
+    )
     opening_statement: str | None = Field(default=None, description="Opening statement")
     suggested_questions: list[str] | None = Field(default=None, description="Suggested questions")
-    more_like_this: dict[str, Any] | None = Field(default=None, description="More like this configuration")
-    speech_to_text: dict[str, Any] | None = Field(default=None, description="Speech to text configuration")
-    text_to_speech: dict[str, Any] | None = Field(default=None, description="Text to speech configuration")
-    retrieval_model: dict[str, Any] | None = Field(default=None, description="Retrieval model configuration")
-    tools: list[dict[str, Any]] | None = Field(default=None, description="Available tools")
-    dataset_configs: dict[str, Any] | None = Field(default=None, description="Dataset configurations")
-    agent_mode: dict[str, Any] | None = Field(default=None, description="Agent mode configuration")
+    more_like_this: dict[str, Any] | None = Field(
+        default=None,
+        description="More like this configuration",
+    )
+    speech_to_text: dict[str, Any] | None = Field(
+        default=None,
+        description="Speech to text configuration",
+    )
+    text_to_speech: dict[str, Any] | None = Field(
+        default=None,
+        description="Text to speech configuration",
+    )
+    retrieval_model: dict[str, Any] | None = Field(
+        default=None,
+        description="Retrieval model configuration",
+    )
+    tools: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Available tools",
+    )
+    dataset_configs: dict[str, Any] | None = Field(
+        default=None,
+        description="Dataset configurations",
+    )
+    agent_mode: dict[str, Any] | None = Field(
+        default=None,
+        description="Agent mode configuration",
+    )
 
 
 register_schema_models(console_ns, ModelConfigRequest)
+register_response_schema_models(console_ns, SimpleResultResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/model-config")
@@ -50,16 +79,21 @@ class ModelConfigResource(Resource):
     @console_ns.doc(description="Update application model configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[ModelConfigRequest.__name__])
-    @console_ns.response(200, "Model configuration updated successfully")
+    @console_ns.response(
+        200,
+        "Model configuration updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @console_ns.response(400, "Invalid configuration")
     @console_ns.response(404, "App not found")
     @setup_required
     @login_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT_CHAT, AppMode.CHAT, AppMode.COMPLETION])
     @with_current_user_id
     @with_current_tenant_id
+    @get_app_model(mode=[AppMode.AGENT_CHAT, AppMode.CHAT, AppMode.COMPLETION])
     def post(self, current_tenant_id: str, current_user_id: str, app_model: App):
         """Modify app model config"""
         # validate config

api/controllers/console/app/ops_trace.py

@@ -1,15 +1,23 @@
 from typing import Any
 
 from flask import request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field
 from werkzeug.exceptions import BadRequest
 
-from controllers.common.schema import register_schema_models
+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.error import TracingConfigCheckError, TracingConfigIsExist, TracingConfigNotExist
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    edit_permission_required,
+    rbac_permission_required,
+    setup_required,
+)
+from fields.base import ResponseModel
 from libs.login import login_required
 from models import App
 from services.ops_service import OpsService
@@ -21,10 +29,27 @@ class TraceProviderQuery(BaseModel):
 
 class TraceConfigPayload(BaseModel):
     tracing_provider: str = Field(..., description="Tracing provider name")
-    tracing_config: dict[str, Any] = Field(..., description="Tracing configuration data")
+    tracing_config: dict[str, Any] = Field(
+        ...,
+        description="Tracing configuration data",
+    )
+
+
+class TraceAppConfigResponse(ResponseModel):
+    result: str | None = None
+    error: str | None = None
+    has_not_configured: bool | None = None
+    id: str | None = None
+    app_id: str | None = None
+    tracing_provider: str | None = None
+    tracing_config: dict[str, Any] | None = Field(default=None)
+    is_active: bool | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
 
 
 register_schema_models(console_ns, TraceProviderQuery, TraceConfigPayload)
+register_response_schema_models(console_ns, TraceAppConfigResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/trace-config")
@@ -36,14 +61,17 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc("get_trace_app_config")
     @console_ns.doc(description="Get tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[TraceProviderQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TraceProviderQuery))
     @console_ns.response(
-        200, "Tracing configuration retrieved successfully", fields.Raw(description="Tracing configuration data")
+        200,
+        "Tracing configuration retrieved successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
     )
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TRACING_CONFIG)
     @get_app_model
     def get(self, app_model: App):
         args = TraceProviderQuery.model_validate(request.args.to_dict(flat=True))  # type: ignore
@@ -63,12 +91,17 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[TraceConfigPayload.__name__])
     @console_ns.response(
-        201, "Tracing configuration created successfully", fields.Raw(description="Created configuration data")
+        201,
+        "Tracing configuration created successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
     )
     @console_ns.response(400, "Invalid request parameters or configuration already exists")
+    @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
+    @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TRACING_CONFIG)
     @get_app_model
     def post(self, app_model: App):
         """Create a new trace app configuration"""
@@ -90,11 +123,18 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc(description="Update an existing tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[TraceConfigPayload.__name__])
-    @console_ns.response(200, "Tracing configuration updated successfully", fields.Raw(description="Success response"))
+    @console_ns.response(
+        200,
+        "Tracing configuration updated successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters or configuration not found")
+    @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
+    @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TRACING_CONFIG)
     @get_app_model
     def patch(self, app_model: App):
         """Update an existing trace app configuration"""
@@ -113,12 +153,15 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc("delete_trace_app_config")
     @console_ns.doc(description="Delete an existing tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[TraceProviderQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TraceProviderQuery))
     @console_ns.response(204, "Tracing configuration deleted successfully")
     @console_ns.response(400, "Invalid request parameters or configuration not found")
+    @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
+    @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TRACING_CONFIG)
     @get_app_model
     def delete(self, app_model: App):
         """Delete an existing trace app configuration"""

api/controllers/console/app/permission_keys.py

@@ -0,0 +1,6 @@
+from services.enterprise import rbac_service as enterprise_rbac_service
+
+
+def get_app_permission_keys(tenant_id: str, account_id: str | None, app_id: str) -> list[str]:
+    permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(tenant_id, account_id, [app_id])
+    return permission_keys_map.get(app_id, [])

api/controllers/console/app/site.py

@@ -10,9 +10,12 @@ from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
     is_admin_or_owner_required,
+    rbac_permission_required,
     setup_required,
     with_current_user,
 )
@@ -85,9 +88,10 @@ class AppSite(Resource):
     @setup_required
     @login_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @account_initialization_required
-    @get_app_model
     @with_current_user
+    @get_app_model
     def post(self, current_user: Account, app_model: App):
         args = AppSiteUpdatePayload.model_validate(console_ns.payload or {})
         site = db.session.scalar(select(Site).where(Site.app_id == app_model.id).limit(1))
@@ -134,9 +138,10 @@ class AppSiteAccessTokenReset(Resource):
     @setup_required
     @login_required
     @is_admin_or_owner_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @account_initialization_required
-    @get_app_model
     @with_current_user
+    @get_app_model
     def post(self, current_user: Account, app_model: App):
         site = db.session.scalar(select(Site).where(Site.app_id == app_model.id).limit(1))
 

api/controllers/console/app/statistic.py

@@ -2,15 +2,23 @@ from decimal import Decimal
 
 import sqlalchemy as sa
 from flask import abort, jsonify, request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 
-from controllers.common.schema import register_schema_models
+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.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+    with_current_user,
+)
 from core.app.entities.app_invoke_entities import InvokeFrom
 from extensions.ext_database import db
+from fields.base import ResponseModel
 from libs.datetime_utils import parse_time_range
 from libs.helper import convert_datetime_to_date
 from libs.login import login_required
@@ -31,7 +39,92 @@ class StatisticTimeRangeQuery(BaseModel):
         return value
 
 
+class DailyMessageStatisticItem(ResponseModel):
+    date: str
+    message_count: int
+
+
+class DailyMessageStatisticResponse(ResponseModel):
+    data: list[DailyMessageStatisticItem]
+
+
+class DailyConversationStatisticItem(ResponseModel):
+    date: str
+    conversation_count: int
+
+
+class DailyConversationStatisticResponse(ResponseModel):
+    data: list[DailyConversationStatisticItem]
+
+
+class DailyTerminalStatisticItem(ResponseModel):
+    date: str
+    terminal_count: int
+
+
+class DailyTerminalStatisticResponse(ResponseModel):
+    data: list[DailyTerminalStatisticItem]
+
+
+class DailyTokenCostStatisticItem(ResponseModel):
+    date: str
+    token_count: int
+    total_price: str | float
+    currency: str
+
+
+class DailyTokenCostStatisticResponse(ResponseModel):
+    data: list[DailyTokenCostStatisticItem]
+
+
+class AverageSessionInteractionStatisticItem(ResponseModel):
+    date: str
+    interactions: float
+
+
+class AverageSessionInteractionStatisticResponse(ResponseModel):
+    data: list[AverageSessionInteractionStatisticItem]
+
+
+class UserSatisfactionRateStatisticItem(ResponseModel):
+    date: str
+    rate: float
+
+
+class UserSatisfactionRateStatisticResponse(ResponseModel):
+    data: list[UserSatisfactionRateStatisticItem]
+
+
+class AverageResponseTimeStatisticItem(ResponseModel):
+    date: str
+    latency: float
+
+
+class AverageResponseTimeStatisticResponse(ResponseModel):
+    data: list[AverageResponseTimeStatisticItem]
+
+
+class TokensPerSecondStatisticItem(ResponseModel):
+    date: str
+    tps: float
+
+
+class TokensPerSecondStatisticResponse(ResponseModel):
+    data: list[TokensPerSecondStatisticItem]
+
+
 register_schema_models(console_ns, StatisticTimeRangeQuery)
+register_response_schema_models(
+    console_ns,
+    DailyMessageStatisticResponse,
+    DailyConversationStatisticResponse,
+    DailyTerminalStatisticResponse,
+    DailyTokenCostStatisticResponse,
+    AverageSessionInteractionStatisticResponse,
+    UserSatisfactionRateStatisticResponse,
+    AverageResponseTimeStatisticResponse,
+    TokensPerSecondStatisticResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/statistics/daily-messages")
@@ -39,17 +132,18 @@ class DailyMessageStatistic(Resource):
     @console_ns.doc("get_daily_message_statistics")
     @console_ns.doc(description="Get daily message statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily message statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily message count data")),
+        console_ns.models[DailyMessageStatisticResponse.__name__],
     )
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
+    @get_app_model
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -99,17 +193,18 @@ class DailyConversationStatistic(Resource):
     @console_ns.doc("get_daily_conversation_statistics")
     @console_ns.doc(description="Get daily conversation statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily conversation statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily conversation count data")),
+        console_ns.models[DailyConversationStatisticResponse.__name__],
     )
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
+    @get_app_model
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -158,17 +253,18 @@ class DailyTerminalsStatistic(Resource):
     @console_ns.doc("get_daily_terminals_statistics")
     @console_ns.doc(description="Get daily terminal/end-user statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily terminal statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily terminal count data")),
+        console_ns.models[DailyTerminalStatisticResponse.__name__],
     )
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
+    @get_app_model
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -218,17 +314,18 @@ class DailyTokenCostStatistic(Resource):
     @console_ns.doc("get_daily_token_cost_statistics")
     @console_ns.doc(description="Get daily token cost statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily token cost statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily token cost data")),
+        console_ns.models[DailyTokenCostStatisticResponse.__name__],
     )
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
+    @get_app_model
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -281,17 +378,18 @@ class AverageSessionInteractionStatistic(Resource):
     @console_ns.doc("get_average_session_interaction_statistics")
     @console_ns.doc(description="Get average session interaction statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Average session interaction statistics retrieved successfully",
-        fields.List(fields.Raw(description="Average session interaction data")),
+        console_ns.models[AverageSessionInteractionStatisticResponse.__name__],
     )
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -360,17 +458,18 @@ class UserSatisfactionRateStatistic(Resource):
     @console_ns.doc("get_user_satisfaction_rate_statistics")
     @console_ns.doc(description="Get user satisfaction rate statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "User satisfaction rate statistics retrieved successfully",
-        fields.List(fields.Raw(description="User satisfaction rate data")),
+        console_ns.models[UserSatisfactionRateStatisticResponse.__name__],
     )
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
+    @get_app_model
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -429,17 +528,18 @@ class AverageResponseTimeStatistic(Resource):
     @console_ns.doc("get_average_response_time_statistics")
     @console_ns.doc(description="Get average response time statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Average response time statistics retrieved successfully",
-        fields.List(fields.Raw(description="Average response time data")),
+        console_ns.models[AverageResponseTimeStatisticResponse.__name__],
     )
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
+    @get_app_model(mode=AppMode.COMPLETION)
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -489,17 +589,18 @@ class TokensPerSecondStatistic(Resource):
     @console_ns.doc("get_tokens_per_second_statistics")
     @console_ns.doc(description="Get tokens per second statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Tokens per second statistics retrieved successfully",
-        fields.List(fields.Raw(description="Tokens per second data")),
+        console_ns.models[TokensPerSecondStatisticResponse.__name__],
     )
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
+    @get_app_model
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 

api/controllers/console/app/workflow.py

@@ -2,26 +2,42 @@ 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, ValidationError, field_validator
-from sqlalchemy.orm import sessionmaker
+from pydantic import AliasChoices, BaseModel, Field, RootModel, ValidationError, field_validator
+from sqlalchemy.orm import Session, sessionmaker
 from werkzeug.exceptions import BadRequest, Forbidden, InternalServerError, NotFound
 
 import services
 from controllers.common.controller_schemas import DefaultBlockConfigQuery, WorkflowListQuery, WorkflowUpdatePayload
-from controllers.common.fields import NewAppResponse, SimpleResultResponse
+from controllers.common.errors import InvalidArgumentError
+from controllers.common.fields import GeneratedAppResponse, NewAppResponse, SimpleResultResponse
 from controllers.common.schema import (
+    query_params_from_model,
     register_response_schema_model,
     register_response_schema_models,
     register_schema_models,
 )
 from controllers.console import console_ns
-from controllers.console.app.error import ConversationCompletedError, DraftWorkflowNotExist, DraftWorkflowNotSync
+from controllers.console.app.error import (
+    ConversationCompletedError,
+    DraftWorkflowNotExist,
+    DraftWorkflowNotSync,
+)
+from controllers.console.app.permission_keys import get_app_permission_keys
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    edit_permission_required,
+    rbac_permission_required,
+    setup_required,
+    with_current_tenant_id,
+    with_current_user,
+)
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.app_config.features.file_upload.manager import FileUploadConfigManager
 from core.app.apps.base_app_queue_manager import AppQueueManager
@@ -50,11 +66,12 @@ from graphon.file import helpers as file_helpers
 from graphon.graph_engine.manager import GraphEngineManager
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from graphon.variables import SecretVariable, SegmentType, VariableBase
+from graphon.variables.exc import VariableError
 from libs import helper
 from libs.datetime_utils import naive_utc_now
 from libs.helper import TimestampField, dump_response, to_timestamp, uuid_value
-from libs.login import current_account_with_tenant, login_required
-from models import App
+from libs.login import login_required
+from models import Account, App
 from models.model import AppMode
 from models.workflow import Workflow
 from repositories.workflow_collaboration_repository import WORKFLOW_ONLINE_USERS_PREFIX
@@ -86,16 +103,20 @@ class SyncDraftWorkflowPayload(BaseModel):
     graph: dict[str, Any]
     features: dict[str, Any]
     hash: str | None = None
-    environment_variables: list[dict[str, Any]] = Field(default_factory=list)
-    conversation_variables: list[dict[str, Any]] = Field(default_factory=list)
+    environment_variables: list[dict[str, Any]] = Field(
+        default_factory=list,
+    )
+    conversation_variables: list[dict[str, Any]] = Field(
+        default_factory=list,
+    )
 
 
 class BaseWorkflowRunPayload(BaseModel):
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
 
 
 class AdvancedChatWorkflowRunPayload(BaseWorkflowRunPayload):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
     query: str = ""
     conversation_id: str | None = None
     parent_message_id: str | None = None
@@ -109,11 +130,11 @@ class AdvancedChatWorkflowRunPayload(BaseWorkflowRunPayload):
 
 
 class IterationNodeRunPayload(BaseModel):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class LoopNodeRunPayload(BaseModel):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class DraftWorkflowRunPayload(BaseWorkflowRunPayload):
@@ -138,7 +159,10 @@ class ConvertToWorkflowPayload(BaseModel):
 
 
 class WorkflowFeaturesPayload(BaseModel):
-    features: dict[str, Any] = Field(..., description="Workflow feature configuration")
+    features: dict[str, Any] = Field(
+        ...,
+        description="Workflow feature configuration",
+    )
 
 
 class WorkflowOnlineUsersPayload(BaseModel):
@@ -154,7 +178,7 @@ class WorkflowConversationVariableResponse(ResponseModel):
     id: str
     name: str
     value_type: str
-    value: Any = Field(json_schema_extra={"type": "object"})
+    value: Any
     description: str
 
     @field_validator("value_type", mode="before")
@@ -173,7 +197,7 @@ class PipelineVariableResponse(ResponseModel):
     max_length: int | None = None
     required: bool
     unit: str | None = None
-    default_value: Any = Field(default=None, json_schema_extra={"type": "object"})
+    default_value: Any = Field(default=None)
     options: list[str] | None = None
     placeholder: str | None = None
     tooltips: str | None = None
@@ -190,14 +214,18 @@ class WorkflowEnvironmentVariableResponse(ResponseModel):
     value_type: str
     id: str
     name: str
-    value: Any = Field(json_schema_extra={"type": "object"})
+    value: Any
     description: str
 
 
 class WorkflowResponse(ResponseModel):
     id: str
-    graph: dict[str, Any] = Field(validation_alias=AliasChoices("graph_dict", "graph"))
-    features: dict[str, Any] = Field(validation_alias=AliasChoices("features_dict", "features"))
+    graph: dict[str, Any] = Field(
+        validation_alias=AliasChoices("graph_dict", "graph"),
+    )
+    features: dict[str, Any] = Field(
+        validation_alias=AliasChoices("features_dict", "features"),
+    )
     hash: str = Field(validation_alias=AliasChoices("unique_hash", "hash"))
     version: str
     marked_name: str
@@ -254,6 +282,46 @@ class WorkflowOnlineUsersResponse(ResponseModel):
     data: list[WorkflowOnlineUsersByApp]
 
 
+class WorkflowPublishResponse(ResponseModel):
+    result: str
+    created_at: int
+
+
+class WorkflowRestoreResponse(ResponseModel):
+    result: str
+    hash: str
+    updated_at: int
+
+
+class DefaultBlockConfigsResponse(RootModel[list[dict[str, Any]]]):
+    root: list[dict[str, Any]]
+
+
+class DefaultBlockConfigResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class HumanInputFormPreviewResponse(ResponseModel):
+    form_id: str
+    node_id: str
+    node_title: str
+    form_content: str
+    inputs: list[dict[str, Any]] = Field(default_factory=list)
+    actions: list[dict[str, Any]] = Field(default_factory=list)
+    display_in_ui: bool | None = None
+    form_token: str | None = None
+    resolved_default_values: dict[str, Any] = Field(default_factory=dict)
+    expiration_time: int | None = None
+
+
+class HumanInputFormSubmitResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class EmptyObjectResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 class DraftWorkflowTriggerRunPayload(BaseModel):
     node_id: str
 
@@ -291,6 +359,14 @@ register_response_schema_models(
     WorkflowOnlineUser,
     WorkflowOnlineUsersByApp,
     WorkflowOnlineUsersResponse,
+    WorkflowPublishResponse,
+    WorkflowRestoreResponse,
+    DefaultBlockConfigsResponse,
+    DefaultBlockConfigResponse,
+    HumanInputFormPreviewResponse,
+    HumanInputFormSubmitResponse,
+    EmptyObjectResponse,
+    GeneratedAppResponse,
     NewAppResponse,
     SimpleResultResponse,
 )
@@ -364,8 +440,9 @@ class DraftWorkflowApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App):
         """
         Get draft workflow
@@ -377,8 +454,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
@@ -401,13 +486,13 @@ class DraftWorkflowApi(Resource):
     )
     @console_ns.response(400, "Invalid workflow configuration")
     @console_ns.response(403, "Permission denied")
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    def post(self, current_user: Account, app_model: App):
         """
         Sync draft workflow
         """
-        current_user, _ = current_account_with_tenant()
-
         content_type = request.headers.get("Content-Type", "")
 
         if "application/json" in content_type:
@@ -447,6 +532,8 @@ class DraftWorkflowApi(Resource):
             )
         except WorkflowHashNotEqualError:
             raise DraftWorkflowNotSync()
+        except VariableError as e:
+            raise InvalidArgumentError(description=str(e))
 
         return {
             "result": "success",
@@ -461,20 +548,20 @@ class AdvancedChatDraftWorkflowRunApi(Resource):
     @console_ns.doc(description="Run draft workflow for advanced chat application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AdvancedChatWorkflowRunPayload.__name__])
-    @console_ns.response(200, "Workflow run started successfully")
+    @console_ns.response(200, "Workflow run started successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Run draft workflow
         """
-        current_user, _ = current_account_with_tenant()
-
         args_model = AdvancedChatWorkflowRunPayload.model_validate(console_ns.payload or {})
         args = args_model.model_dump(exclude_none=True)
 
@@ -507,19 +594,24 @@ class AdvancedChatDraftRunIterationNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow iteration node for advanced chat")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[IterationNodeRunPayload.__name__])
-    @console_ns.response(200, "Iteration node run started successfully")
+    @console_ns.response(
+        200,
+        "Iteration node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow iteration node
         """
-        current_user, _ = current_account_with_tenant()
         args = IterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         try:
@@ -545,19 +637,24 @@ class WorkflowDraftRunIterationNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow iteration node")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[IterationNodeRunPayload.__name__])
-    @console_ns.response(200, "Workflow iteration node run started successfully")
+    @console_ns.response(
+        200,
+        "Workflow iteration node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow iteration node
         """
-        current_user, _ = current_account_with_tenant()
         args = IterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         try:
@@ -583,19 +680,20 @@ class AdvancedChatDraftRunLoopNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow loop node for advanced chat")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[LoopNodeRunPayload.__name__])
-    @console_ns.response(200, "Loop node run started successfully")
+    @console_ns.response(200, "Loop node run started successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow loop node
         """
-        current_user, _ = current_account_with_tenant()
         args = LoopNodeRunPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -621,19 +719,24 @@ class WorkflowDraftRunLoopNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow loop node")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[LoopNodeRunPayload.__name__])
-    @console_ns.response(200, "Workflow loop node run started successfully")
+    @console_ns.response(
+        200,
+        "Workflow loop node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow loop node
         """
-        current_user, _ = current_account_with_tenant()
         args = LoopNodeRunPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -661,7 +764,10 @@ class HumanInputFormPreviewPayload(BaseModel):
 
 
 class HumanInputFormSubmitPayload(BaseModel):
-    form_inputs: dict[str, Any] = Field(..., description="Values the user provides for the form's own fields")
+    form_inputs: dict[str, Any] = Field(
+        ...,
+        description="Values the user provides for the form's own fields",
+    )
     inputs: dict[str, Any] = Field(
         ...,
         description="Values used to fill missing upstream variables referenced in form_content",
@@ -691,16 +797,18 @@ class AdvancedChatDraftHumanInputFormPreviewApi(Resource):
     @console_ns.doc(description="Get human input form preview for advanced chat workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormPreviewPayload.__name__])
+    @console_ns.response(200, "Human input form preview", console_ns.models[HumanInputFormPreviewResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Preview human input form content and placeholders
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormPreviewPayload.model_validate(console_ns.payload or {})
         inputs = args.inputs
 
@@ -720,16 +828,22 @@ class AdvancedChatDraftHumanInputFormRunApi(Resource):
     @console_ns.doc(description="Submit human input form preview for advanced chat workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormSubmitPayload.__name__])
+    @console_ns.response(
+        200,
+        "Human input form submission result",
+        console_ns.models[HumanInputFormSubmitResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Submit human input form preview
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormSubmitPayload.model_validate(console_ns.payload or {})
         workflow_service = WorkflowService()
         result = workflow_service.submit_human_input_form_preview(
@@ -749,16 +863,18 @@ class WorkflowDraftHumanInputFormPreviewApi(Resource):
     @console_ns.doc(description="Get human input form preview for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormPreviewPayload.__name__])
+    @console_ns.response(200, "Human input form preview", console_ns.models[HumanInputFormPreviewResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Preview human input form content and placeholders
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormPreviewPayload.model_validate(console_ns.payload or {})
         inputs = args.inputs
 
@@ -778,16 +894,22 @@ class WorkflowDraftHumanInputFormRunApi(Resource):
     @console_ns.doc(description="Submit human input form preview for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormSubmitPayload.__name__])
+    @console_ns.response(
+        200,
+        "Human input form submission result",
+        console_ns.models[HumanInputFormSubmitResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Submit human input form preview
         """
-        current_user, _ = current_account_with_tenant()
         workflow_service = WorkflowService()
         args = HumanInputFormSubmitPayload.model_validate(console_ns.payload or {})
         result = workflow_service.submit_human_input_form_preview(
@@ -807,16 +929,18 @@ class WorkflowDraftHumanInputDeliveryTestApi(Resource):
     @console_ns.doc(description="Test human input delivery for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputDeliveryTestPayload.__name__])
+    @console_ns.response(200, "Human input delivery test result", console_ns.models[EmptyObjectResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Test human input delivery
         """
-        current_user, _ = current_account_with_tenant()
         workflow_service = WorkflowService()
         args = HumanInputDeliveryTestPayload.model_validate(console_ns.payload or {})
         workflow_service.test_human_input_delivery(
@@ -835,18 +959,23 @@ class DraftWorkflowRunApi(Resource):
     @console_ns.doc(description="Run draft workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[DraftWorkflowRunPayload.__name__])
-    @console_ns.response(200, "Draft workflow run started successfully")
+    @console_ns.response(
+        200,
+        "Draft workflow run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Run draft workflow
         """
-        current_user, _ = current_account_with_tenant()
         args = DraftWorkflowRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         external_trace_id = get_external_trace_id(request)
@@ -878,8 +1007,9 @@ class WorkflowTaskStopApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def post(self, app_model: App, task_id: str):
         """
         Stop workflow task
@@ -910,13 +1040,14 @@ class DraftWorkflowNodeRunApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow node
         """
-        current_user, _ = current_account_with_tenant()
         args_model = DraftWorkflowNodeRunPayload.model_validate(console_ns.payload or {})
         args = args_model.model_dump(exclude_none=True)
 
@@ -960,8 +1091,9 @@ class PublishedWorkflowApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App):
         """
         Get published workflow
@@ -977,16 +1109,18 @@ class PublishedWorkflowApi(Resource):
         return dump_response(WorkflowResponse, workflow)
 
     @console_ns.expect(console_ns.models[PublishWorkflowPayload.__name__])
+    @console_ns.response(200, "Workflow published successfully", console_ns.models[WorkflowPublishResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Publish workflow
         """
-        current_user, _ = current_account_with_tenant()
 
         args = PublishWorkflowPayload.model_validate(console_ns.payload or {})
 
@@ -1020,12 +1154,17 @@ class DefaultBlockConfigsApi(Resource):
     @console_ns.doc("get_default_block_configs")
     @console_ns.doc(description="Get default block configurations for workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Default block configurations retrieved successfully")
+    @console_ns.response(
+        200,
+        "Default block configurations retrieved successfully",
+        console_ns.models[DefaultBlockConfigsResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App):
         """
         Get default block config
@@ -1040,14 +1179,19 @@ class DefaultBlockConfigApi(Resource):
     @console_ns.doc("get_default_block_config")
     @console_ns.doc(description="Get default block configuration by type")
     @console_ns.doc(params={"app_id": "Application ID", "block_type": "Block type"})
-    @console_ns.response(200, "Default block configuration retrieved successfully")
+    @console_ns.response(
+        200,
+        "Default block configuration retrieved successfully",
+        console_ns.models[DefaultBlockConfigResponse.__name__],
+    )
     @console_ns.response(404, "Block type not found")
-    @console_ns.expect(console_ns.models[DefaultBlockConfigQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(DefaultBlockConfigQuery))
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, block_type: str):
         """
         Get default block config
@@ -1083,15 +1227,16 @@ class ConvertToWorkflowApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.COMPLETION])
+    @with_current_user
+    @with_current_tenant_id
     @edit_permission_required
-    def post(self, app_model: App):
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    def post(self, current_tenant_id: str, current_user: Account, app_model: App):
         """
         Convert basic mode of chatbot app to workflow mode
         Convert expert mode of chatbot app to workflow mode
         Convert Completion App to Workflow App
         """
-        current_user, _ = current_account_with_tenant()
-
         payload = console_ns.payload or {}
         args = ConvertToWorkflowPayload.model_validate(payload).model_dump(exclude_none=True)
 
@@ -1102,6 +1247,7 @@ class ConvertToWorkflowApi(Resource):
         # return app id
         return {
             "new_app_id": new_app_model.id,
+            "permission_keys": get_app_permission_keys(str(current_tenant_id), current_user.id, str(new_app_model.id)),
         }
 
 
@@ -1122,9 +1268,10 @@ class WorkflowFeaturesApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
-        current_user, _ = current_account_with_tenant()
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    def post(self, current_user: Account, app_model: App):
 
         args = WorkflowFeaturesPayload.model_validate(console_ns.payload or {})
         features = args.features
@@ -1137,7 +1284,7 @@ class WorkflowFeaturesApi(Resource):
 
 @console_ns.route("/apps/<uuid:app_id>/workflows")
 class PublishedAllWorkflowApi(Resource):
-    @console_ns.expect(console_ns.models[WorkflowListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowListQuery))
     @console_ns.doc("get_all_published_workflows")
     @console_ns.doc(description="Get all published workflows for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
@@ -1149,13 +1296,14 @@ class PublishedAllWorkflowApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def get(self, app_model: App):
+    def get(self, current_user: Account, app_model: App):
         """
         Get published workflows
         """
-        current_user, _ = current_account_with_tenant()
 
         args = WorkflowListQuery.model_validate(request.args.to_dict(flat=True))
         page = args.page
@@ -1192,16 +1340,17 @@ class DraftWorkflowRestoreApi(Resource):
     @console_ns.doc("restore_workflow_to_draft")
     @console_ns.doc(description="Restore a published workflow version into the draft workflow")
     @console_ns.doc(params={"app_id": "Application ID", "workflow_id": "Published workflow ID"})
-    @console_ns.response(200, "Workflow restored successfully")
+    @console_ns.response(200, "Workflow restored successfully", console_ns.models[WorkflowRestoreResponse.__name__])
     @console_ns.response(400, "Source workflow must be published")
     @console_ns.response(404, "Workflow not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, workflow_id: str):
-        current_user, _ = current_account_with_tenant()
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    def post(self, current_user: Account, app_model: App, workflow_id: str):
         workflow_service = WorkflowService()
 
         try:
@@ -1237,12 +1386,13 @@ class WorkflowByIdApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def patch(self, app_model: App, workflow_id: str):
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    def patch(self, current_user: Account, app_model: App, workflow_id: str):
         """
         Update workflow attributes
         """
-        current_user, _ = current_account_with_tenant()
         args = WorkflowUpdatePayload.model_validate(console_ns.payload or {})
 
         # Prepare update data
@@ -1277,6 +1427,8 @@ class WorkflowByIdApi(Resource):
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @console_ns.response(204, "Workflow deleted successfully")
     def delete(self, app_model: App, workflow_id: str):
         """
         Delete workflow
@@ -1314,6 +1466,7 @@ class DraftWorkflowNodeLastRunApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, node_id: str):
         srv = WorkflowService()
@@ -1348,19 +1501,24 @@ class DraftWorkflowTriggerRunApi(Resource):
             },
         )
     )
-    @console_ns.response(200, "Trigger event received and workflow executed successfully")
+    @console_ns.response(
+        200,
+        "Trigger event received and workflow executed successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Poll for trigger events and execute full workflow when event arrives
         """
-        current_user, _ = current_account_with_tenant()
         args = DraftWorkflowTriggerRunPayload.model_validate(console_ns.payload or {})
         node_id = args.node_id
         workflow_service = WorkflowService()
@@ -1412,19 +1570,24 @@ class DraftWorkflowTriggerNodeApi(Resource):
     @console_ns.doc("poll_draft_workflow_trigger_node")
     @console_ns.doc(description="Poll for trigger events and execute single node when event arrives")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
-    @console_ns.response(200, "Trigger event received and node executed successfully")
+    @console_ns.response(
+        200,
+        "Trigger event received and node executed successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Poll for trigger events and execute single node when event arrives
         """
-        current_user, _ = current_account_with_tenant()
 
         workflow_service = WorkflowService()
         draft_workflow = workflow_service.get_draft_workflow(app_model)
@@ -1492,19 +1655,20 @@ class DraftWorkflowTriggerRunAllApi(Resource):
     @console_ns.doc(description="Full workflow debug when the start node is a trigger")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[DraftWorkflowTriggerRunAllPayload.__name__])
-    @console_ns.response(200, "Workflow executed successfully")
+    @console_ns.response(200, "Workflow executed successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    def post(self, current_user: Account, app_model: App):
         """
         Full workflow debug when the start node is a trigger
         """
-        current_user, _ = current_account_with_tenant()
 
         args = DraftWorkflowTriggerRunAllPayload.model_validate(console_ns.payload or {})
         node_ids = args.node_ids
@@ -1565,7 +1729,8 @@ class WorkflowOnlineUsersApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
         args = WorkflowOnlineUsersPayload.model_validate(console_ns.payload or {})
 
         app_ids = args.app_ids
@@ -1575,7 +1740,6 @@ class WorkflowOnlineUsersApi(Resource):
         if not app_ids:
             return {"data": []}
 
-        _, current_tenant_id = current_account_with_tenant()
         workflow_service = WorkflowService()
         accessible_app_ids = workflow_service.get_accessible_app_ids(app_ids, current_tenant_id)
         ordered_accessible_app_ids = [app_id for app_id in app_ids if app_id in accessible_app_ids]

api/controllers/console/app/workflow_app_log.py

@@ -7,10 +7,16 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+)
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from fields.end_user_fields import SimpleEndUser
@@ -166,7 +172,7 @@ class WorkflowAppLogApi(Resource):
     @console_ns.doc("get_workflow_app_logs")
     @console_ns.doc(description="Get workflow application execution logs")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowAppLogQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowAppLogQuery))
     @console_ns.response(
         200,
         "Workflow app logs retrieved successfully",
@@ -175,6 +181,7 @@ class WorkflowAppLogApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_LOG_AND_ANNOTATION)
     @get_app_model(mode=[AppMode.WORKFLOW])
     def get(self, app_model: App):
         """
@@ -209,7 +216,7 @@ class WorkflowArchivedLogApi(Resource):
     @console_ns.doc("get_workflow_archived_logs")
     @console_ns.doc(description="Get workflow archived execution logs")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowAppLogQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowAppLogQuery))
     @console_ns.response(
         200,
         "Workflow archived logs retrieved successfully",
@@ -218,6 +225,7 @@ class WorkflowArchivedLogApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_LOG_AND_ANNOTATION)
     @get_app_model(mode=[AppMode.WORKFLOW])
     def get(self, app_model: App):
         """

api/controllers/console/app/workflow_comment.py

@@ -8,12 +8,16 @@ from controllers.common.schema import register_response_schema_models, register_
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user,
 )
+from extensions.ext_database import db
 from fields.base import ResponseModel
 from fields.member_fields import AccountWithRole
 from libs.helper import build_avatar_url, dump_response, to_timestamp
@@ -218,8 +222,9 @@ class WorkflowCommentListApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model()
     def get(self, current_tenant_id: str, app_model: App):
         """Get all comments for a workflow."""
         comments = WorkflowCommentService.get_comments(tenant_id=current_tenant_id, app_id=app_model.id)
@@ -234,10 +239,11 @@ class WorkflowCommentListApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
     @with_current_tenant_id
+    @get_app_model()
     def post(self, current_tenant_id: str, current_user: Account, app_model: App):
         """Create a new workflow comment."""
         payload = WorkflowCommentCreatePayload.model_validate(console_ns.payload or {})
@@ -266,8 +272,9 @@ class WorkflowCommentDetailApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model()
     def get(self, current_tenant_id: str, app_model: App, comment_id: str):
         """Get a specific workflow comment."""
         comment = WorkflowCommentService.get_comment(
@@ -284,10 +291,11 @@ class WorkflowCommentDetailApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
     @with_current_tenant_id
+    @get_app_model()
     def put(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str):
         """Update a workflow comment."""
         payload = WorkflowCommentUpdatePayload.model_validate(console_ns.payload or {})
@@ -312,10 +320,11 @@ class WorkflowCommentDetailApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
     @with_current_tenant_id
+    @get_app_model()
     def delete(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str):
         """Delete a workflow comment."""
         WorkflowCommentService.delete_comment(
@@ -339,10 +348,11 @@ class WorkflowCommentResolveApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
     @with_current_tenant_id
+    @get_app_model()
     def post(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str):
         """Resolve a workflow comment."""
         comment = WorkflowCommentService.resolve_comment(
@@ -367,10 +377,11 @@ class WorkflowCommentReplyApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
     @with_current_tenant_id
+    @get_app_model()
     def post(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str):
         """Add a reply to a workflow comment."""
         # Validate comment access first
@@ -402,10 +413,11 @@ class WorkflowCommentReplyDetailApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
     @with_current_tenant_id
+    @get_app_model()
     def put(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str, reply_id: str):
         """Update a comment reply."""
         # Validate comment access first
@@ -434,10 +446,11 @@ class WorkflowCommentReplyDetailApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
     @with_current_tenant_id
+    @get_app_model()
     def delete(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str, reply_id: str):
         """Delete a comment reply."""
         # Validate comment access first
@@ -469,14 +482,15 @@ class WorkflowCommentMentionUsersApi(Resource):
     @login_required
     @setup_required
     @account_initialization_required
-    @get_app_model()
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model()
     def get(self, current_user: Account, app_model: App):
         """Get all users in current tenant for mentions."""
         current_tenant = current_user.current_tenant  # need the tenant object here
         if current_tenant is None:
             raise ValueError("current tenant is required")
-        members = TenantService.get_tenant_members(current_tenant)
+        members = TenantService.get_tenant_members(current_tenant, session=db.session)
         users = TypeAdapter(list[AccountWithRole]).validate_python(members, from_attributes=True)
         response = WorkflowCommentMentionUsersPayload(users=users)
         return response.model_dump(mode="json"), 200

api/controllers/console/app/workflow_draft_variable.py

@@ -1,7 +1,7 @@
 import logging
 from collections.abc import Callable
 from functools import wraps
-from typing import Any, Concatenate, TypedDict
+from typing import Any, Concatenate, TypedDict, override
 from uuid import UUID
 
 from flask import Response, request
@@ -9,25 +9,30 @@ from flask_restx import Resource, fields, marshal, marshal_with
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.errors import InvalidArgumentError, NotFoundError
+from controllers.common.fields import SimpleResultResponse
+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.error import (
     DraftWorkflowNotExist,
 )
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_user,
 )
-from controllers.web.error import InvalidArgumentError, NotFoundError
 from core.app.file_access import DatabaseFileAccessController
 from core.workflow.variable_prefixes import CONVERSATION_VARIABLE_NODE_ID, SYSTEM_VARIABLE_NODE_ID
 from extensions.ext_database import db
 from factories import variable_factory
 from factories.file_factory import build_from_mapping, build_from_mappings
 from factories.variable_factory import build_segment_with_type
+from fields.base import ResponseModel
 from graphon.file import helpers as file_helpers
 from graphon.variables.segment_group import SegmentGroup
 from graphon.variables.segments import ArrayFileSegment, FileSegment, Segment
@@ -42,6 +47,28 @@ logger = logging.getLogger(__name__)
 _file_access_controller = DatabaseFileAccessController()
 
 
+class OpaqueRawField(fields.Raw):
+    @override
+    def schema(self) -> dict[str, object]:
+        return {"type": "object"}
+
+
+class JsonValueRawField(fields.Raw):
+    @override
+    def schema(self) -> dict[str, object]:
+        return {
+            "anyOf": [
+                {"type": "string"},
+                {"type": "integer"},
+                {"type": "number"},
+                {"type": "boolean"},
+                {"type": "object", "additionalProperties": True},
+                {"type": "array", "items": {}},
+                {"type": "null"},
+            ]
+        }
+
+
 class WorkflowDraftVariableListQuery(BaseModel):
     page: int = Field(default=1, ge=1, le=100_000, description="Page number")
     limit: int = Field(default=20, ge=1, le=100, description="Items per page")
@@ -54,12 +81,33 @@ class WorkflowDraftVariableUpdatePayload(BaseModel):
 
 class ConversationVariableUpdatePayload(BaseModel):
     conversation_variables: list[dict[str, Any]] = Field(
-        ..., description="Conversation variables for the draft workflow"
+        ...,
+        description="Conversation variables for the draft workflow",
     )
 
 
 class EnvironmentVariableUpdatePayload(BaseModel):
-    environment_variables: list[dict[str, Any]] = Field(..., description="Environment variables for the draft workflow")
+    environment_variables: list[dict[str, Any]] = Field(
+        ...,
+        description="Environment variables for the draft workflow",
+    )
+
+
+class EnvironmentVariableItemResponse(ResponseModel):
+    id: str
+    type: str
+    name: str
+    description: str | None = None
+    selector: list[str]
+    value_type: str
+    value: Any
+    edited: bool
+    visible: bool
+    editable: bool
+
+
+class EnvironmentVariableListResponse(ResponseModel):
+    items: list[EnvironmentVariableItemResponse]
 
 
 register_schema_models(
@@ -69,6 +117,7 @@ register_schema_models(
     ConversationVariableUpdatePayload,
     EnvironmentVariableUpdatePayload,
 )
+register_response_schema_models(console_ns, SimpleResultResponse, EnvironmentVariableListResponse)
 
 
 def _convert_values_to_json_serializable_object(value: Segment):
@@ -155,8 +204,8 @@ _WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS = {
 
 _WORKFLOW_DRAFT_VARIABLE_FIELDS = {
     **_WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS,
-    "value": fields.Raw(attribute=_serialize_var_value),
-    "full_content": fields.Raw(attribute=_serialize_full_content),
+    "value": JsonValueRawField(attribute=_serialize_var_value),
+    "full_content": OpaqueRawField(attribute=_serialize_full_content),
 }
 
 _WORKFLOW_DRAFT_ENV_VARIABLE_FIELDS = {
@@ -181,7 +230,7 @@ def _get_items(var_list: WorkflowDraftVariableList) -> list[WorkflowDraftVariabl
 
 _WORKFLOW_DRAFT_VARIABLE_LIST_WITHOUT_VALUE_FIELDS = {
     "items": fields.List(fields.Nested(_WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS), attribute=_get_items),
-    "total": fields.Raw(),
+    "total": fields.Integer,
 }
 
 _WORKFLOW_DRAFT_VARIABLE_LIST_FIELDS = {
@@ -237,6 +286,7 @@ def _api_prerequisite[T, **P, R](
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @with_current_user
     @wraps(f)
@@ -248,7 +298,7 @@ def _api_prerequisite[T, **P, R](
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/variables")
 class WorkflowVariableCollectionApi(Resource):
-    @console_ns.expect(console_ns.models[WorkflowDraftVariableListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowDraftVariableListQuery))
     @console_ns.doc("get_workflow_variables")
     @console_ns.doc(description="Get draft workflow variables")
     @console_ns.doc(params={"app_id": "Application ID"})
@@ -258,6 +308,7 @@ class WorkflowVariableCollectionApi(Resource):
     )
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_without_value_model)
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, current_user: Account, app_model: App):
         """
         Get draft workflow
@@ -322,6 +373,7 @@ class NodeVariableCollectionApi(Resource):
     @console_ns.response(200, "Node variables retrieved successfully", workflow_draft_variable_list_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, current_user: Account, app_model: App, node_id: str):
         validate_node_id(node_id)
         with sessionmaker(bind=db.engine, expire_on_commit=False).begin() as session:
@@ -356,6 +408,7 @@ class VariableApi(Resource):
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, current_user: Account, app_model: App, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
@@ -528,6 +581,7 @@ class ConversationVariableCollectionApi(Resource):
     @console_ns.response(404, "Draft workflow not found")
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, current_user: Account, app_model: App):
         # NOTE(QuantumGhost): Prefill conversation variables into the draft variables table
         # so their IDs can be returned to the caller.
@@ -544,13 +598,18 @@ class ConversationVariableCollectionApi(Resource):
     @console_ns.doc("update_conversation_variables")
     @console_ns.doc(description="Update conversation variables for workflow draft")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Conversation variables updated successfully")
+    @console_ns.response(
+        200,
+        "Conversation variables updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @get_app_model(mode=AppMode.ADVANCED_CHAT)
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
+    @get_app_model(mode=AppMode.ADVANCED_CHAT)
     def post(self, current_user: Account, app_model: App):
         payload = ConversationVariableUpdatePayload.model_validate(console_ns.payload or {})
 
@@ -578,6 +637,7 @@ class SystemVariableCollectionApi(Resource):
     @console_ns.response(200, "System variables retrieved successfully", workflow_draft_variable_list_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, current_user: Account, app_model: App):
         return _get_variable_list(app_model, SYSTEM_VARIABLE_NODE_ID, current_user.id)
 
@@ -587,9 +647,14 @@ class EnvironmentVariableCollectionApi(Resource):
     @console_ns.doc("get_environment_variables")
     @console_ns.doc(description="Get environment variables for workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Environment variables retrieved successfully")
+    @console_ns.response(
+        200,
+        "Environment variables retrieved successfully",
+        console_ns.models[EnvironmentVariableListResponse.__name__],
+    )
     @console_ns.response(404, "Draft workflow not found")
     @_api_prerequisite
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, _current_user: Account, app_model: App):
         """
         Get draft workflow
@@ -625,13 +690,18 @@ class EnvironmentVariableCollectionApi(Resource):
     @console_ns.doc("update_environment_variables")
     @console_ns.doc(description="Update environment variables for workflow draft")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Environment variables updated successfully")
+    @console_ns.response(
+        200,
+        "Environment variables updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def post(self, current_user: Account, app_model: App):
         payload = EnvironmentVariableUpdatePayload.model_validate(console_ns.payload or {})
 

api/controllers/console/app/workflow_node_output_inspector.py

@@ -30,16 +30,29 @@ from uuid import UUID
 from flask import Response
 from flask_restx import Resource
 
+from controllers.common.fields import EventStreamResponse
+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.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+)
 from libs.exception import BaseHTTPException
 from libs.login import login_required
 from models import App, AppMode
 from services.workflow import inspector_events
 from services.workflow.node_output_inspector_service import (
+    CheckResultView,
     NodeOutputInspectorError,
     NodeOutputInspectorService,
+    NodeOutputsView,
+    NodeOutputView,
+    OutputPreviewView,
+    WorkflowRunSnapshotView,
 )
 
 logger = logging.getLogger(__name__)
@@ -54,6 +67,16 @@ _HEARTBEAT_EVERY_TICKS = 15
 # many ticks (= seconds).
 _STREAM_HARD_TIMEOUT_TICKS = 1800  # 30 min
 
+register_response_schema_models(
+    console_ns,
+    EventStreamResponse,
+    CheckResultView,
+    NodeOutputView,
+    NodeOutputsView,
+    WorkflowRunSnapshotView,
+    OutputPreviewView,
+)
+
 
 def _service() -> NodeOutputInspectorService:
     """One-line factory so tests can monkeypatch a stub if needed."""
@@ -124,10 +147,12 @@ class WorkflowDraftRunNodeOutputsApi(Resource):
     @console_ns.doc("get_workflow_draft_run_node_outputs")
     @console_ns.doc(description="Snapshot of every node's declared outputs for a draft workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(200, "Workflow run node outputs", console_ns.models[WorkflowRunSnapshotView.__name__])
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID):
         return _serve_snapshot(app_model, run_id)
@@ -146,10 +171,12 @@ class WorkflowDraftRunNodeOutputDetailApi(Resource):
             "node_id": "Node ID inside the workflow graph",
         }
     )
+    @console_ns.response(200, "Workflow run node output detail", console_ns.models[NodeOutputsView.__name__])
     @console_ns.response(404, "Workflow run / node not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID, node_id: str):
         return _serve_node_detail(app_model, run_id, node_id)
@@ -171,10 +198,12 @@ class WorkflowDraftRunNodeOutputPreviewApi(Resource):
             "output_name": "Declared output name as exposed by Composer",
         }
     )
+    @console_ns.response(200, "Workflow run node output preview", console_ns.models[OutputPreviewView.__name__])
     @console_ns.response(404, "Workflow run / node / output not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID, node_id: str, output_name: str):
         return _serve_output_preview(app_model, run_id, node_id, output_name)
@@ -309,10 +338,16 @@ class WorkflowDraftRunNodeOutputEventsApi(Resource):
     @console_ns.doc("stream_workflow_draft_run_node_output_events")
     @console_ns.doc(description="Server-Sent Events stream of inspector deltas for a draft workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(
+        200,
+        "Workflow run node output event stream",
+        console_ns.models[EventStreamResponse.__name__],
+    )
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID):
         return Response(
@@ -338,10 +373,12 @@ class WorkflowPublishedRunNodeOutputsApi(Resource):
     @console_ns.doc("get_workflow_published_run_node_outputs")
     @console_ns.doc(description="Snapshot of every node's declared outputs for a published workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(200, "Workflow run node outputs", console_ns.models[WorkflowRunSnapshotView.__name__])
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID):
         return _serve_snapshot(app_model, run_id)
@@ -360,10 +397,12 @@ class WorkflowPublishedRunNodeOutputDetailApi(Resource):
             "node_id": "Node ID inside the workflow graph",
         }
     )
+    @console_ns.response(200, "Workflow run node output detail", console_ns.models[NodeOutputsView.__name__])
     @console_ns.response(404, "Workflow run / node not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID, node_id: str):
         return _serve_node_detail(app_model, run_id, node_id)
@@ -386,10 +425,12 @@ class WorkflowPublishedRunNodeOutputPreviewApi(Resource):
             "output_name": "Declared output name as exposed by Composer",
         }
     )
+    @console_ns.response(200, "Workflow run node output preview", console_ns.models[OutputPreviewView.__name__])
     @console_ns.response(404, "Workflow run / node / output not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID, node_id: str, output_name: str):
         return _serve_output_preview(app_model, run_id, node_id, output_name)
@@ -402,10 +443,16 @@ class WorkflowPublishedRunNodeOutputEventsApi(Resource):
     @console_ns.doc("stream_workflow_published_run_node_output_events")
     @console_ns.doc(description="Server-Sent Events stream of inspector deltas for a published workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(
+        200,
+        "Workflow run node output event stream",
+        console_ns.models[EventStreamResponse.__name__],
+    )
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID):
         return Response(

api/controllers/console/app/workflow_run.py

@@ -9,16 +9,19 @@ from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 
 from configs import dify_config
+from controllers.common.errors import NotFoundError
 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.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user,
 )
-from controllers.web.error import NotFoundError
 from core.workflow.human_input_forms import load_form_tokens_by_form_id as _load_form_tokens_by_form_id
 from extensions.ext_database import db
 from fields.base import ResponseModel
@@ -155,6 +158,7 @@ class AdvancedChatAppWorkflowRunListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
     def get(self, app_model: App):
         """
@@ -193,6 +197,7 @@ class WorkflowRunExportApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @get_app_model()
     def get(self, app_model: App, run_id: UUID):
         tenant_id = app_model.tenant_id
@@ -251,6 +256,7 @@ class AdvancedChatAppWorkflowRunCountApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
     def get(self, app_model: App):
         """
@@ -291,6 +297,7 @@ class WorkflowRunListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App):
         """
@@ -332,6 +339,7 @@ class WorkflowRunCountApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App):
         """
@@ -372,6 +380,7 @@ class WorkflowRunDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, app_model: App, run_id: UUID):
         """
@@ -401,8 +410,9 @@ class WorkflowRunNodeExecutionListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     def get(self, current_user: Account, app_model: App, run_id: UUID):
         """
         Get workflow run node execution list