update github action

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

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

@@ -28,9 +28,12 @@ Flag:
 - Missing `package.json#exports` entry for a new primitive.
 - Internal package imports using workspace subpaths instead of relative paths.
 - Exported props using internal-only types that consumers cannot import from the component subpath.
+- Canonical primitive boundaries or their associated public types using a redundant `Root` suffix when no higher-level convenience component exists in the same subpath.
 
 Consumers use subpath exports such as `@langgenius/dify-ui/button`.
 
+Canonical boundaries use the primitive name and matching public types (`Select` / `SelectProps`). Keep `Root` only to distinguish a low-level anatomy root from a higher-level convenience component (`CheckboxRoot` / `Checkbox`); implementation aliases should still show their Base UI source (`BaseSelect.Root.Props`).
+
 ## Props And State
 
 Flag:
@@ -45,17 +48,17 @@ Flag:
 
 Prefer Base UI/Dify UI data attributes and CSS variables for visual state: `data-open`, `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`, `group-data-*`, `peer-data-*`, `has-[:focus-visible]`, and primitive CSS variables such as anchor width or transform origin. Use JS conditional classes for product/business state that the primitive does not expose.
 
-For non-string `Select` and `RadioGroup` values, prefer explicit domain generics at the root and at child value carriers. JSX children do not inherit the parent generic, so `RadioGroup<PromptMode>` should compose with `Radio<PromptMode>`, `RadioRoot<PromptMode>`, or option values from a typed collection. For `Select`, prefer the Base UI `items` collection pattern for typed value-to-label rendering, and flag string coercion helpers used only to recover display labels.
+For non-string `Select` and `RadioGroup` values, prefer explicit domain generics at the root and at child value carriers. JSX children do not inherit the parent generic, so `RadioGroup<PromptMode>` should compose with `Radio<PromptMode>`, `RadioItem<PromptMode>`, or option values from a typed collection. For `Select`, prefer the Base UI `items` collection pattern for typed value-to-label rendering, and flag string coercion helpers used only to recover display labels.
 
 ## Forms
 
 Flag:
 
 - Form-like UI using unrelated `Input` and `Button` pieces without a submit boundary.
-- Text-like fields not composed through `FieldRoot`, `FieldLabel`, and `FieldControl` when using Dify UI form semantics.
+- Text-like fields not composed through `Field`, `FieldLabel`, and `FieldControl` when using Dify UI form semantics.
 - Select fields using `FieldLabel` instead of `SelectLabel`.
 - Slider fields using a generic label instead of `SliderLabel`.
-- Checkbox/radio groups missing `FieldsetRoot` and `FieldsetLegend`.
+- Checkbox/radio groups missing `Fieldset` and `FieldsetLegend`.
 - Field errors or descriptions rendered without `FieldDescription` / `FieldError` relationships.
 
 `Form` is the submit boundary. Dify UI form primitives are not a form state-management framework; business validation and schema-driven behavior belong in `web/`.

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

@@ -1,72 +1,36 @@
 # Testing Review Rules
 
-Use these rules when reviewing test files, testability of changed code, or risky frontend changes that should have tests.
+`web/docs/test.md` is the canonical frontend testing policy. Use this file only to translate that policy into review findings.
 
-## Missing Coverage
+## Request Missing Tests When Risk Justifies Them
 
-Flag missing tests when the change affects:
+Flag missing coverage when a change alters a reachable contract such as:
 
-- User-visible behavior, navigation, form submission, validation, permissions, or loading/error/empty states.
-- Query/mutation cache behavior.
-- Accessibility-critical behavior such as labels, keyboard flow, focus, disabled state, or popup reachability.
-- URL state parsing/serialization.
-- Storage persistence or one-shot signals.
-- Regression-prone workflow or generated contract migration paths.
+- User interaction, navigation, form submission, validation, or permissions.
+- Query or mutation behavior, URL state, persistence, or one-shot signals.
+- Loading, error, empty, and recovery states that users can encounter.
+- Accessibility-critical labels, keyboard flow, focus, disabled state, or overlay behavior.
+- A regression-prone business rule or bug fix that can be reproduced through a public boundary.
 
-Do not request tests for purely mechanical renames or styling-only changes unless the styling affects layout, focus, or interaction.
+Do not request tests for mechanical changes, pass-through wrappers, implementation details, or visual-only styling unless they affect behavior. Low coverage alone is not a finding.
 
-## Selectors
+## Flag Low-Value or Fragile Tests
 
-Flag:
+Flag tests that:
 
-- `getByTestId` used where role, label, text, placeholder, landmark, or scoped dialog/menu queries are available.
-- Production `data-testid` added only to satisfy tests.
-- Assertions against decorative icons rather than the named control.
-- Tests that cannot find controls semantically but leave broken markup unchanged.
+- Assert internal state, refs, hook usage, effect dependencies, private DOM structure, or cosmetic classes.
+- Exist only to render a component, exercise a prop, or cover generic invalid inputs without a product scenario.
+- Mock away the behavior under review or use mocks that do not match the public contract.
+- Add production `data-testid` attributes where semantic markup would work.
+- Use fake timers without timer behavior, leave async work unawaited, or leak shared state.
+- Duplicate a contract already protected at a more useful owner boundary.
 
-Prefer `getByRole` with accessible name, then `getByLabelText`, `getByPlaceholderText`, `getByText`, and `within(...)`.
+## Review the Test Boundary
 
-## Mocking
+- Prefer semantic queries and accessible names.
+- Prefer real feature components when integration semantics matter.
+- Allow intentional child or provider mocks when setup would dominate the test and that boundary is covered independently.
+- Do not accept semantically inaccurate mocks of Dify UI or legacy base primitives.
+- Require a real-browser or visual verification plan when `happy-dom` cannot represent the risk.
 
-Flag:
-
-- Mocking `@langgenius/dify-ui/*` primitives.
-- Mocking `@/app/components/base/*` components when the real component is practical.
-- Mocking sibling or child components in the same directory for integration behavior.
-- Mocks that do not match the real component's conditional rendering.
-- Module-level mock state not reset in `beforeEach`.
-- `vi.clearAllMocks()` in `afterEach` instead of `beforeEach`.
-
-Use real project components for integration behavior. Mock APIs, `next/navigation`, browser shims, or complex providers only when setup would dominate the test.
-
-## Behavior
-
-Flag:
-
-- Tests inspecting implementation details instead of user-observable behavior.
-- Assertions that hardcode brittle copy when pattern matching or semantic roles would express behavior better.
-- Fake timers used without real timing behavior.
-- Async assertions missing `await`, `findBy*`, or `waitFor`.
-- Test data missing required fields because inline partial objects bypass real types.
-
-Use typed factory functions with complete defaults and partial overrides.
-
-## URL State
-
-For `nuqs` or query-state hooks, flag tests that:
-
-- Mock URL state when URL synchronization is the behavior under review.
-- Do not test parser serialize/parse round trips for custom parsers.
-- Do not assert default-clearing behavior when defaults should be removed from the URL.
-
-Prefer shared `NuqsTestingAdapter` helpers when available.
-
-## Organization
-
-Flag:
-
-- Component/hook/util tests outside sibling `__tests__/` directories.
-- Directory-level reviews that test only `index.tsx` while other files in scope contain behavior.
-- Large test files with repeated setup that should use local builders.
-
-When a component is very complex, prefer a refactor finding before asking for exhaustive tests.
+Treat test quality, determinism, and regression value as the review criteria. Do not use test count or coverage percentage as a proxy for quality.

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

@@ -1,332 +1,35 @@
 ---
 name: frontend-testing
-description: Generate Vitest + React Testing Library tests for Dify frontend components, hooks, and utilities. Triggers on testing, spec files, coverage, Vitest, RTL, unit tests, integration tests, or write/review test requests.
+description: Write, update, or review Dify frontend tests using Vitest and Testing Library. Trigger for frontend specs, test coverage requests, regressions, testability, or testing strategy under web/ or packages/dify-ui/.
 ---
 
-# Dify Frontend Testing Skill
+# Dify Frontend Testing
 
-This skill enables Codex to generate high-quality, comprehensive frontend tests for the Dify project following established conventions and best practices.
+Use this skill for Vitest work under `web/` and `packages/dify-ui/`. Do not use it for Python tests or Cucumber/Playwright tests under `e2e/`.
 
-> **⚠️ Authoritative Source**: This skill is derived from `web/docs/test.md`. Use Vitest mock/timer APIs (`vi.*`).
+## Required Source
 
-## When to Apply This Skill
+Before writing, changing, or reviewing frontend tests, read `web/docs/test.md` completely. It is the single source of truth. This skill provides an execution checklist and must not redefine or extend that policy.
 
-Apply this skill when the user:
+## Workflow
 
-- Asks to **write tests** for a component, hook, or utility
-- Asks to **review existing tests** for completeness
-- Mentions **Vitest**, **React Testing Library**, **RTL**, or **spec files**
-- Requests **test coverage** improvement
-- Uses `pnpm analyze-component` output as context
-- Mentions **testing**, **unit tests**, or **integration tests** for frontend code
-- Wants to understand **testing patterns** in the Dify codebase
+1. Read the source, its behavior owner, nearby specs, and relevant public dependencies.
+1. Apply the canonical guide to decide whether a test is needed and choose its boundary.
+1. For a behavior change or bug fix, write or identify the failing scenario first when practical.
+1. Implement one coherent scenario at a time and run the focused spec before expanding scope.
+1. Finish with the affected suite and relevant repository checks.
+1. Report what behavior was verified and any risk that still requires browser, visual, or end-to-end validation.
 
-**Do NOT apply** when:
+When reviewing existing tests, recommend deleting low-value tests as readily as adding missing behavior coverage.
 
-- User is asking about backend/API tests (Python/pytest)
-- User is asking about E2E tests (Cucumber + Playwright under `e2e/`)
-- User is only asking conceptual questions without code context
-
-## Quick Reference
-
-### Key Commands
-
-Run these commands from `web/`. From the repository root, prefix them with `pnpm -C web`.
+Run focused tests from the owning workspace:
 
 ```bash
-# Run all tests
-pnpm test
+# web/
+vp test run path/to/spec-or-directory
 
-# Watch mode
-pnpm test --watch
-
-# Run specific file
-pnpm test path/to/file.spec.tsx
-
-# Generate coverage report
-pnpm test --coverage
-
-# Analyze component complexity
-pnpm analyze-component <path>
-
-# Review existing test
-pnpm analyze-component <path> --review
+# packages/dify-ui/
+vp test run --project unit src/path/to/spec
 ```
 
-### File Naming
-
-- Test files: `ComponentName.spec.tsx` inside a same-level `__tests__/` directory
-- Placement rule: Component, hook, and utility tests must live in a sibling `__tests__/` folder at the same level as the source under test. For example, `foo/index.tsx` maps to `foo/__tests__/index.spec.tsx`, and `foo/bar.ts` maps to `foo/__tests__/bar.spec.ts`.
-- Integration tests: `web/__tests__/` directory
-
-## Test Structure Template
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import Component from './index'
-
-// ✅ Import real project components (DO NOT mock these)
-// import Loading from '@/app/components/base/loading'
-// import { ChildComponent } from './child-component'
-
-// ✅ Mock external dependencies only
-vi.mock('@/service/api')
-vi.mock('next/navigation', () => ({
-  useRouter: () => ({ push: vi.fn() }),
-  usePathname: () => '/test',
-}))
-
-// ✅ Zustand stores: Use real stores (auto-mocked globally)
-// Set test state with: useAppStore.setState({ ... })
-
-// Shared state for mocks (if needed)
-let mockSharedState = false
-
-describe('ComponentName', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()  // ✅ Reset mocks BEFORE each test
-    mockSharedState = false  // ✅ Reset shared state
-  })
-
-  // Rendering tests (REQUIRED)
-  describe('Rendering', () => {
-    it('should render without crashing', () => {
-      // Arrange
-      const props = { title: 'Test' }
-      
-      // Act
-      render(<Component {...props} />)
-      
-      // Assert
-      expect(screen.getByText('Test')).toBeInTheDocument()
-    })
-  })
-
-  // Props tests (REQUIRED when props change observable behavior)
-  describe('Props', () => {
-    it('should disable the action when disabled', () => {
-      render(<Component disabled />)
-      expect(screen.getByRole('button')).toBeDisabled()
-    })
-  })
-
-  // User Interactions
-  describe('User Interactions', () => {
-    it('should handle click events', () => {
-      const handleClick = vi.fn()
-      render(<Component onClick={handleClick} />)
-      
-      fireEvent.click(screen.getByRole('button'))
-      
-      expect(handleClick).toHaveBeenCalledTimes(1)
-    })
-  })
-
-  // Edge Cases (REQUIRED)
-  describe('Edge Cases', () => {
-    it('should handle null data', () => {
-      render(<Component data={null} />)
-      expect(screen.getByText(/no data/i)).toBeInTheDocument()
-    })
-
-    it('should handle empty array', () => {
-      render(<Component items={[]} />)
-      expect(screen.getByText(/empty/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-## Testing Workflow (CRITICAL)
-
-### ⚠️ Incremental Approach Required
-
-**NEVER generate all test files at once.** For complex components or multi-file directories:
-
-1. **Analyze & Plan**: List all files, order by complexity (simple → complex)
-1. **Process ONE at a time**: Write test → Run test → Fix if needed → Next
-1. **Verify before proceeding**: Do NOT continue to next file until current passes
-
-```
-For each file:
-  ┌────────────────────────────────────────┐
-  │ 1. Write test                          │
-  │ 2. Run: pnpm test <file>.spec.tsx      │
-  │ 3. PASS? → Mark complete, next file    │
-  │    FAIL? → Fix first, then continue    │
-  └────────────────────────────────────────┘
-```
-
-### Complexity-Based Order
-
-Process in this order for multi-file testing:
-
-1. 🟢 Utility functions (simplest)
-1. 🟢 Custom hooks
-1. 🟡 Simple components (presentational)
-1. 🟡 Medium components (state, effects)
-1. 🔴 Complex components (API, routing)
-1. 🔴 Integration tests (index files - last)
-
-### When to Refactor First
-
-- **Complexity > 50**: Break into smaller pieces before testing
-- **500+ lines**: Consider splitting before testing
-- **Many dependencies**: Extract logic into hooks first
-
-> 📖 See `references/workflow.md` for complete workflow details and todo list format.
-
-## Testing Strategy
-
-### Path-Level Testing (Directory Testing)
-
-When assigned to test a directory/path, test **ALL content** within that path:
-
-- Test all components, hooks, utilities in the directory (not just `index` file)
-- Use incremental approach: one file at a time, verify each before proceeding
-- Goal: 100% coverage of ALL files in the directory
-
-### Integration Testing First
-
-**Prefer integration testing** when writing tests for a directory:
-
-- ✅ **Import real project components** directly (including base components and siblings)
-- ✅ **Only mock**: API services (`@/service/*`), `next/navigation`, complex context providers
-- ❌ **DO NOT mock** base components (`@/app/components/base/*`) or dify-ui primitives (`@langgenius/dify-ui/*`)
-- ❌ **DO NOT mock** sibling/child components in the same directory
-
-> See [Test Structure Template](#test-structure-template) for correct import/mock patterns.
-
-### `nuqs` Query State Testing (Required for URL State Hooks)
-
-When a component or hook uses `useQueryState` / `useQueryStates`:
-
-- ✅ Use `NuqsTestingAdapter` (prefer shared helpers in `web/test/nuqs-testing.tsx`)
-- ✅ Assert URL synchronization via `onUrlUpdate` (`searchParams`, `options.history`)
-- ✅ For custom parsers (`createParser`), keep `parse` and `serialize` bijective and add round-trip edge cases (`%2F`, `%25`, spaces, legacy encoded values)
-- ✅ Verify default-clearing behavior (default values should be removed from URL when applicable)
-- ⚠️ Only mock `nuqs` directly when URL behavior is explicitly out of scope for the test
-
-## Core Principles
-
-### 1. AAA Pattern (Arrange-Act-Assert)
-
-Every test should clearly separate:
-
-- **Arrange**: Setup test data and render component
-- **Act**: Perform user actions
-- **Assert**: Verify expected outcomes
-
-### 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.
-- Do not assert decorative icons by test id. Assert the named control that contains them, or mark decorative icons `aria-hidden`.
-- Avoid testing internal state directly
-- **Prefer pattern matching over hardcoded strings** in assertions:
-
-```typescript
-// ❌ Avoid: hardcoded text assertions
-expect(screen.getByText('Loading...')).toBeInTheDocument()
-
-// ✅ Better: role-based queries
-expect(screen.getByRole('status')).toBeInTheDocument()
-
-// ✅ Better: pattern matching
-expect(screen.getByText(/loading/i)).toBeInTheDocument()
-```
-
-### 3. Single Behavior Per Test
-
-Each test verifies ONE user-observable behavior:
-
-```typescript
-// ✅ Good: One behavior
-it('should disable button when loading', () => {
-  render(<Button loading />)
-  expect(screen.getByRole('button')).toBeDisabled()
-})
-
-// ❌ Bad: Multiple behaviors
-it('should handle loading state', () => {
-  render(<Button loading />)
-  expect(screen.getByRole('button')).toBeDisabled()
-  expect(screen.getByText('Loading...')).toBeInTheDocument()
-  expect(screen.getByRole('button')).toHaveClass('loading')
-})
-```
-
-### 4. Semantic Naming
-
-Use `should <behavior> when <condition>`:
-
-```typescript
-it('should show error message when validation fails')
-it('should call onSubmit when form is valid')
-it('should disable input when isReadOnly is true')
-```
-
-## Required Test Scenarios
-
-### Always Required (All Components)
-
-1. **Rendering**: Component renders without crashing
-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)
-
-| Feature | Test Focus |
-|---------|-----------|
-| `useState` | Initial state, transitions, cleanup |
-| `useEffect` | Execution, dependencies, cleanup |
-| Event handlers | All onClick, onChange, onSubmit, keyboard |
-| API calls | Loading, success, error states |
-| Routing | Navigation, params, query strings |
-| `useCallback`/`useMemo` | Referential equality |
-| Context | Provider values, consumer behavior |
-| Forms | Validation, submission, error display |
-
-## Coverage Goals (Per File)
-
-For each test file generated, aim for:
-
-- ✅ **100%** function coverage
-- ✅ **100%** statement coverage
-- ✅ **>95%** branch coverage
-- ✅ **>95%** line coverage
-
-> **Note**: For multi-file directories, process one file at a time with full coverage each. See `references/workflow.md`.
-
-## Detailed Guides
-
-For more detailed information, refer to:
-
-- `references/workflow.md` - **Incremental testing workflow** (MUST READ for multi-file testing)
-- `references/mocking.md` - Mock patterns, Zustand store testing, and best practices
-- `references/async-testing.md` - Async operations and API calls
-- `references/domain-components.md` - Workflow, Dataset, Configuration testing
-- `references/common-patterns.md` - Frequently used testing patterns
-- `references/checklist.md` - Test generation checklist and validation steps
-
-## Authoritative References
-
-### Primary Specification (MUST follow)
-
-- **`web/docs/test.md`** - The canonical testing specification. This skill is derived from this document.
-
-### Reference Examples in Codebase
-
-- `web/utils/classnames.spec.ts` - Utility function tests
-- `web/app/components/base/radio/__tests__/index.spec.tsx` - Component tests
-- `web/__mocks__/provider-context.ts` - Mock factory example
-
-### Project Configuration
-
-- `web/vite.config.ts` - Vite/Vitest configuration
-- `web/vitest.setup.ts` - Test environment setup
-- `web/scripts/analyze-component.js` - Component analysis tool
-- Modules are not mocked automatically. Global mocks live in `web/vitest.setup.ts` (for example `react-i18next`, `next/image`); mock other modules like `ky` or `mime` locally in test files.
+Run Dify UI Storybook tests with `vp test --project storybook --run`. Run broader checks only after the focused behavior passes.

.agents/skills/frontend-testing/assets/component-test.template.tsx

@@ -1,293 +0,0 @@
-/**
- * Test Template for React Components
- *
- * WHY THIS STRUCTURE?
- * - Organized sections make tests easy to navigate and maintain
- * - Mocks at top ensure consistent test isolation
- * - Factory functions reduce duplication and improve readability
- * - describe blocks group related scenarios for better debugging
- *
- * INSTRUCTIONS:
- * 1. Replace `ComponentName` with your component name
- * 2. Update import path
- * 3. Add/remove test sections based on component features (use analyze-component)
- * 4. Follow AAA pattern: Arrange → Act → Assert
- *
- * RUN FIRST: pnpm analyze-component <path> to identify required test scenarios
- */
-
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-// import ComponentName from './index'
-
-// ============================================================================
-// Mocks
-// ============================================================================
-// WHY: Mocks must be hoisted to top of file (Vitest requirement).
-// They run BEFORE imports, so keep them before component imports.
-
-// i18n (automatically mocked)
-// WHY: Global mock in web/vitest.setup.ts is auto-loaded by Vitest setup
-// The global mock provides: useTranslation, Trans, useMixedTranslation, useGetLanguage
-// No explicit mock needed for most tests
-//
-// Override only if custom translations are required:
-// import { createReactI18nextMock } from '@/test/i18n-mock'
-// vi.mock('react-i18next', () => createReactI18nextMock({
-//   'my.custom.key': 'Custom Translation',
-//   'button.save': 'Save',
-// }))
-
-// Router (if component uses useRouter, usePathname, useSearchParams)
-// WHY: Isolates tests from Next.js routing, enables testing navigation behavior
-// const mockPush = vi.fn()
-// vi.mock('@/next/navigation', () => ({
-//   useRouter: () => ({ push: mockPush }),
-//   usePathname: () => '/test-path',
-// }))
-
-// API services (if component fetches data)
-// WHY: Prevents real network calls, enables testing all states (loading/success/error)
-// vi.mock('@/service/api')
-// import * as api from '@/service/api'
-// const mockedApi = vi.mocked(api)
-
-// Shared mock state (for portal/dropdown components)
-// WHY: Portal components like PortalToFollowElem need shared state between
-// parent and child mocks to correctly simulate open/close behavior
-// let mockOpenState = false
-
-// ============================================================================
-// Test Data Factories
-// ============================================================================
-// WHY FACTORIES?
-// - Avoid hard-coded test data scattered across tests
-// - Easy to create variations with overrides
-// - Type-safe when using actual types from source
-// - Single source of truth for default test values
-
-// const createMockProps = (overrides = {}) => ({
-//   // Default props that make component render successfully
-//   ...overrides,
-// })
-
-// const createMockItem = (overrides = {}) => ({
-//   id: 'item-1',
-//   name: 'Test Item',
-//   ...overrides,
-// })
-
-// ============================================================================
-// Test Helpers
-// ============================================================================
-
-// const renderComponent = (props = {}) => {
-//   return render(<ComponentName {...createMockProps(props)} />)
-// }
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-describe('ComponentName', () => {
-  // WHY beforeEach with clearAllMocks?
-  // - Ensures each test starts with clean slate
-  // - Prevents mock call history from leaking between tests
-  // - MUST be beforeEach (not afterEach) to reset BEFORE assertions like toHaveBeenCalledTimes
-  beforeEach(() => {
-    vi.clearAllMocks()
-    // Reset shared mock state if used (CRITICAL for portal/dropdown tests)
-    // mockOpenState = false
-  })
-
-  // --------------------------------------------------------------------------
-  // Rendering Tests (REQUIRED - Every component MUST have these)
-  // --------------------------------------------------------------------------
-  // WHY: Catches import errors, missing providers, and basic render issues
-  describe('Rendering', () => {
-    it('should render without crashing', () => {
-      // Arrange - Setup data and mocks
-      // const props = createMockProps()
-
-      // Act - Render the component
-      // render(<ComponentName {...props} />)
-
-      // Assert - Verify expected output
-      // Prefer getByRole for accessibility; it's what users "see"
-      // expect(screen.getByRole('...')).toBeInTheDocument()
-    })
-
-    it('should render with default props', () => {
-      // WHY: Verifies component works without optional props
-      // render(<ComponentName />)
-      // expect(screen.getByText('...')).toBeInTheDocument()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Props Tests (REQUIRED - Every component MUST test prop behavior)
-  // --------------------------------------------------------------------------
-  // WHY: Props are the component's API contract. Test them thoroughly.
-  describe('Props', () => {
-    it('should apply custom className', () => {
-      // WHY: Common pattern in Dify - components should merge custom classes
-      // render(<ComponentName className="custom-class" />)
-      // expect(screen.getByTestId('component')).toHaveClass('custom-class')
-    })
-
-    it('should use default values for optional props', () => {
-      // WHY: Verifies TypeScript defaults work at runtime
-      // render(<ComponentName />)
-      // expect(screen.getByRole('...')).toHaveAttribute('...', 'default-value')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // User Interactions (if component has event handlers - on*, handle*)
-  // --------------------------------------------------------------------------
-  // WHY: Event handlers are core functionality. Test from user's perspective.
-  describe('User Interactions', () => {
-    it('should call onClick when clicked', async () => {
-      // WHY userEvent over fireEvent?
-      // - userEvent simulates real user behavior (focus, hover, then click)
-      // - fireEvent is lower-level, doesn't trigger all browser events
-      // const user = userEvent.setup()
-      // const handleClick = vi.fn()
-      // render(<ComponentName onClick={handleClick} />)
-      //
-      // await user.click(screen.getByRole('button'))
-      //
-      // expect(handleClick).toHaveBeenCalledTimes(1)
-    })
-
-    it('should call onChange when value changes', async () => {
-      // const user = userEvent.setup()
-      // const handleChange = vi.fn()
-      // render(<ComponentName onChange={handleChange} />)
-      //
-      // await user.type(screen.getByRole('textbox'), 'new value')
-      //
-      // expect(handleChange).toHaveBeenCalled()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // State Management (if component uses useState/useReducer)
-  // --------------------------------------------------------------------------
-  // WHY: Test state through observable UI changes, not internal state values
-  describe('State Management', () => {
-    it('should update state on interaction', async () => {
-      // WHY test via UI, not state?
-      // - State is implementation detail; UI is what users see
-      // - If UI works correctly, state must be correct
-      // const user = userEvent.setup()
-      // render(<ComponentName />)
-      //
-      // // Initial state - verify what user sees
-      // expect(screen.getByText('Initial')).toBeInTheDocument()
-      //
-      // // Trigger state change via user action
-      // await user.click(screen.getByRole('button'))
-      //
-      // // New state - verify UI updated
-      // expect(screen.getByText('Updated')).toBeInTheDocument()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Async Operations (if component fetches data - useQuery, fetch)
-  // --------------------------------------------------------------------------
-  // WHY: Async operations have 3 states users experience: loading, success, error
-  describe('Async Operations', () => {
-    it('should show loading state', () => {
-      // WHY never-resolving promise?
-      // - Keeps component in loading state for assertion
-      // - Alternative: use fake timers
-      // mockedApi.fetchData.mockImplementation(() => new Promise(() => {}))
-      // render(<ComponentName />)
-      //
-      // expect(screen.getByText(/loading/i)).toBeInTheDocument()
-    })
-
-    it('should show data on success', async () => {
-      // WHY waitFor?
-      // - Component updates asynchronously after fetch resolves
-      // - waitFor retries assertion until it passes or times out
-      // mockedApi.fetchData.mockResolvedValue({ items: ['Item 1'] })
-      // render(<ComponentName />)
-      //
-      // await waitFor(() => {
-      //   expect(screen.getByText('Item 1')).toBeInTheDocument()
-      // })
-    })
-
-    it('should show error on failure', async () => {
-      // mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-      // render(<ComponentName />)
-      //
-      // await waitFor(() => {
-      //   expect(screen.getByText(/error/i)).toBeInTheDocument()
-      // })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Edge Cases (REQUIRED - Every component MUST handle edge cases)
-  // --------------------------------------------------------------------------
-  // WHY: Real-world data is messy. Components must handle:
-  // - Null/undefined from API failures or optional fields
-  // - Empty arrays/strings from user clearing data
-  // - Boundary values (0, MAX_INT, special characters)
-  describe('Edge Cases', () => {
-    it('should handle null value', () => {
-      // WHY test null specifically?
-      // - API might return null for missing data
-      // - Prevents "Cannot read property of null" in production
-      // render(<ComponentName value={null} />)
-      // expect(screen.getByText(/no data/i)).toBeInTheDocument()
-    })
-
-    it('should handle undefined value', () => {
-      // WHY test undefined separately from null?
-      // - TypeScript treats them differently
-      // - Optional props are undefined, not null
-      // render(<ComponentName value={undefined} />)
-      // expect(screen.getByText(/no data/i)).toBeInTheDocument()
-    })
-
-    it('should handle empty array', () => {
-      // WHY: Empty state often needs special UI (e.g., "No items yet")
-      // render(<ComponentName items={[]} />)
-      // expect(screen.getByText(/empty/i)).toBeInTheDocument()
-    })
-
-    it('should handle empty string', () => {
-      // WHY: Empty strings are truthy in JS but visually empty
-      // render(<ComponentName text="" />)
-      // expect(screen.getByText(/placeholder/i)).toBeInTheDocument()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Accessibility (optional but recommended for Dify's enterprise users)
-  // --------------------------------------------------------------------------
-  // WHY: Dify has enterprise customers who may require accessibility compliance
-  describe('Accessibility', () => {
-    it('should have accessible name', () => {
-      // WHY getByRole with name?
-      // - Tests that screen readers can identify the element
-      // - Enforces proper labeling practices
-      // render(<ComponentName label="Test Label" />)
-      // expect(screen.getByRole('button', { name: /test label/i })).toBeInTheDocument()
-    })
-
-    it('should support keyboard navigation', async () => {
-      // WHY: Some users can't use a mouse
-      // const user = userEvent.setup()
-      // render(<ComponentName />)
-      //
-      // await user.tab()
-      // expect(screen.getByRole('button')).toHaveFocus()
-    })
-  })
-})

.agents/skills/frontend-testing/assets/hook-test.template.ts

@@ -1,207 +0,0 @@
-/**
- * Test Template for Custom Hooks
- *
- * Instructions:
- * 1. Replace `useHookName` with your hook name
- * 2. Update import path
- * 3. Add/remove test sections based on hook features
- */
-
-import { renderHook, act, waitFor } from '@testing-library/react'
-// import { useHookName } from './use-hook-name'
-
-// ============================================================================
-// Mocks
-// ============================================================================
-
-// API services (if hook fetches data)
-// vi.mock('@/service/api')
-// import * as api from '@/service/api'
-// const mockedApi = vi.mocked(api)
-
-// ============================================================================
-// Test Helpers
-// ============================================================================
-
-// Wrapper for hooks that need context
-// const createWrapper = (contextValue = {}) => {
-//   return ({ children }: { children: React.ReactNode }) => (
-//     <SomeContext.Provider value={contextValue}>
-//       {children}
-//     </SomeContext.Provider>
-//   )
-// }
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-describe('useHookName', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  // --------------------------------------------------------------------------
-  // Initial State
-  // --------------------------------------------------------------------------
-  describe('Initial State', () => {
-    it('should return initial state', () => {
-      // const { result } = renderHook(() => useHookName())
-      //
-      // expect(result.current.value).toBe(initialValue)
-      // expect(result.current.isLoading).toBe(false)
-    })
-
-    it('should accept initial value from props', () => {
-      // const { result } = renderHook(() => useHookName({ initialValue: 'custom' }))
-      //
-      // expect(result.current.value).toBe('custom')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // State Updates
-  // --------------------------------------------------------------------------
-  describe('State Updates', () => {
-    it('should update value when setValue is called', () => {
-      // const { result } = renderHook(() => useHookName())
-      //
-      // act(() => {
-      //   result.current.setValue('new value')
-      // })
-      //
-      // expect(result.current.value).toBe('new value')
-    })
-
-    it('should reset to initial value', () => {
-      // const { result } = renderHook(() => useHookName({ initialValue: 'initial' }))
-      //
-      // act(() => {
-      //   result.current.setValue('changed')
-      // })
-      // expect(result.current.value).toBe('changed')
-      //
-      // act(() => {
-      //   result.current.reset()
-      // })
-      // expect(result.current.value).toBe('initial')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Async Operations
-  // --------------------------------------------------------------------------
-  describe('Async Operations', () => {
-    it('should fetch data on mount', async () => {
-      // mockedApi.fetchData.mockResolvedValue({ data: 'test' })
-      //
-      // const { result } = renderHook(() => useHookName())
-      //
-      // // Initially loading
-      // expect(result.current.isLoading).toBe(true)
-      //
-      // // Wait for data
-      // await waitFor(() => {
-      //   expect(result.current.isLoading).toBe(false)
-      // })
-      //
-      // expect(result.current.data).toEqual({ data: 'test' })
-    })
-
-    it('should handle fetch error', async () => {
-      // mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-      //
-      // const { result } = renderHook(() => useHookName())
-      //
-      // await waitFor(() => {
-      //   expect(result.current.error).toBeTruthy()
-      // })
-      //
-      // expect(result.current.error?.message).toBe('Network error')
-    })
-
-    it('should refetch when dependency changes', async () => {
-      // mockedApi.fetchData.mockResolvedValue({ data: 'test' })
-      //
-      // const { result, rerender } = renderHook(
-      //   ({ id }) => useHookName(id),
-      //   { initialProps: { id: '1' } }
-      // )
-      //
-      // await waitFor(() => {
-      //   expect(mockedApi.fetchData).toHaveBeenCalledWith('1')
-      // })
-      //
-      // rerender({ id: '2' })
-      //
-      // await waitFor(() => {
-      //   expect(mockedApi.fetchData).toHaveBeenCalledWith('2')
-      // })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Side Effects
-  // --------------------------------------------------------------------------
-  describe('Side Effects', () => {
-    it('should call callback when value changes', () => {
-      // const callback = vi.fn()
-      // const { result } = renderHook(() => useHookName({ onChange: callback }))
-      //
-      // act(() => {
-      //   result.current.setValue('new value')
-      // })
-      //
-      // expect(callback).toHaveBeenCalledWith('new value')
-    })
-
-    it('should cleanup on unmount', () => {
-      // const cleanup = vi.fn()
-      // vi.spyOn(window, 'addEventListener')
-      // vi.spyOn(window, 'removeEventListener')
-      //
-      // const { unmount } = renderHook(() => useHookName())
-      //
-      // expect(window.addEventListener).toHaveBeenCalled()
-      //
-      // unmount()
-      //
-      // expect(window.removeEventListener).toHaveBeenCalled()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Edge Cases
-  // --------------------------------------------------------------------------
-  describe('Edge Cases', () => {
-    it('should handle null input', () => {
-      // const { result } = renderHook(() => useHookName(null))
-      //
-      // expect(result.current.value).toBeNull()
-    })
-
-    it('should handle rapid updates', () => {
-      // const { result } = renderHook(() => useHookName())
-      //
-      // act(() => {
-      //   result.current.setValue('1')
-      //   result.current.setValue('2')
-      //   result.current.setValue('3')
-      // })
-      //
-      // expect(result.current.value).toBe('3')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // With Context (if hook uses context)
-  // --------------------------------------------------------------------------
-  describe('With Context', () => {
-    it('should use context value', () => {
-      // const wrapper = createWrapper({ someValue: 'context-value' })
-      // const { result } = renderHook(() => useHookName(), { wrapper })
-      //
-      // expect(result.current.contextValue).toBe('context-value')
-    })
-  })
-})

.agents/skills/frontend-testing/assets/utility-test.template.ts

@@ -1,154 +0,0 @@
-/**
- * Test Template for Utility Functions
- *
- * Instructions:
- * 1. Replace `utilityFunction` with your function name
- * 2. Update import path
- * 3. Use test.each for data-driven tests
- */
-
-// import { utilityFunction } from './utility'
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-describe('utilityFunction', () => {
-  // --------------------------------------------------------------------------
-  // Basic Functionality
-  // --------------------------------------------------------------------------
-  describe('Basic Functionality', () => {
-    it('should return expected result for valid input', () => {
-      // expect(utilityFunction('input')).toBe('expected-output')
-    })
-
-    it('should handle multiple arguments', () => {
-      // expect(utilityFunction('a', 'b', 'c')).toBe('abc')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Data-Driven Tests
-  // --------------------------------------------------------------------------
-  describe('Input/Output Mapping', () => {
-    test.each([
-      // [input, expected]
-      ['input1', 'output1'],
-      ['input2', 'output2'],
-      ['input3', 'output3'],
-    ])('should return %s for input %s', (input, expected) => {
-      // expect(utilityFunction(input)).toBe(expected)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Edge Cases
-  // --------------------------------------------------------------------------
-  describe('Edge Cases', () => {
-    it('should handle empty string', () => {
-      // expect(utilityFunction('')).toBe('')
-    })
-
-    it('should handle null', () => {
-      // expect(utilityFunction(null)).toBe(null)
-      // or
-      // expect(() => utilityFunction(null)).toThrow()
-    })
-
-    it('should handle undefined', () => {
-      // expect(utilityFunction(undefined)).toBe(undefined)
-      // or
-      // expect(() => utilityFunction(undefined)).toThrow()
-    })
-
-    it('should handle empty array', () => {
-      // expect(utilityFunction([])).toEqual([])
-    })
-
-    it('should handle empty object', () => {
-      // expect(utilityFunction({})).toEqual({})
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Boundary Conditions
-  // --------------------------------------------------------------------------
-  describe('Boundary Conditions', () => {
-    it('should handle minimum value', () => {
-      // expect(utilityFunction(0)).toBe(0)
-    })
-
-    it('should handle maximum value', () => {
-      // expect(utilityFunction(Number.MAX_SAFE_INTEGER)).toBe(...)
-    })
-
-    it('should handle negative numbers', () => {
-      // expect(utilityFunction(-1)).toBe(...)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Type Coercion (if applicable)
-  // --------------------------------------------------------------------------
-  describe('Type Handling', () => {
-    it('should handle numeric string', () => {
-      // expect(utilityFunction('123')).toBe(123)
-    })
-
-    it('should handle boolean', () => {
-      // expect(utilityFunction(true)).toBe(...)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Error Cases
-  // --------------------------------------------------------------------------
-  describe('Error Handling', () => {
-    it('should throw for invalid input', () => {
-      // expect(() => utilityFunction('invalid')).toThrow('Error message')
-    })
-
-    it('should throw with specific error type', () => {
-      // expect(() => utilityFunction('invalid')).toThrow(ValidationError)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Complex Objects (if applicable)
-  // --------------------------------------------------------------------------
-  describe('Object Handling', () => {
-    it('should preserve object structure', () => {
-      // const input = { a: 1, b: 2 }
-      // expect(utilityFunction(input)).toEqual({ a: 1, b: 2 })
-    })
-
-    it('should handle nested objects', () => {
-      // const input = { nested: { deep: 'value' } }
-      // expect(utilityFunction(input)).toEqual({ nested: { deep: 'transformed' } })
-    })
-
-    it('should not mutate input', () => {
-      // const input = { a: 1 }
-      // const inputCopy = { ...input }
-      // utilityFunction(input)
-      // expect(input).toEqual(inputCopy)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Array Handling (if applicable)
-  // --------------------------------------------------------------------------
-  describe('Array Handling', () => {
-    it('should process all elements', () => {
-      // expect(utilityFunction([1, 2, 3])).toEqual([2, 4, 6])
-    })
-
-    it('should handle single element array', () => {
-      // expect(utilityFunction([1])).toEqual([2])
-    })
-
-    it('should preserve order', () => {
-      // expect(utilityFunction(['c', 'a', 'b'])).toEqual(['c', 'a', 'b'])
-    })
-  })
-})

.agents/skills/frontend-testing/references/async-testing.md

@@ -1,345 +0,0 @@
-# Async Testing Guide
-
-## Core Async Patterns
-
-### 1. waitFor - Wait for Condition
-
-```typescript
-import { render, screen, waitFor } from '@testing-library/react'
-
-it('should load and display data', async () => {
-  render(<DataComponent />)
-  
-  // Wait for element to appear
-  await waitFor(() => {
-    expect(screen.getByText('Loaded Data')).toBeInTheDocument()
-  })
-})
-
-it('should hide loading spinner after load', async () => {
-  render(<DataComponent />)
-  
-  // Wait for element to disappear
-  await waitFor(() => {
-    expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
-  })
-})
-```
-
-### 2. findBy\* - Async Queries
-
-```typescript
-it('should show user name after fetch', async () => {
-  render(<UserProfile />)
-  
-  // findBy returns a promise, auto-waits up to 1000ms
-  const userName = await screen.findByText('John Doe')
-  expect(userName).toBeInTheDocument()
-  
-  // findByRole with options
-  const button = await screen.findByRole('button', { name: /submit/i })
-  expect(button).toBeEnabled()
-})
-```
-
-### 3. userEvent for Async Interactions
-
-```typescript
-import userEvent from '@testing-library/user-event'
-
-it('should submit form', async () => {
-  const user = userEvent.setup()
-  const onSubmit = vi.fn()
-  
-  render(<Form onSubmit={onSubmit} />)
-  
-  // userEvent methods are async
-  await user.type(screen.getByLabelText('Email'), 'test@example.com')
-  await user.click(screen.getByRole('button', { name: /submit/i }))
-  
-  await waitFor(() => {
-    expect(onSubmit).toHaveBeenCalledWith({ email: 'test@example.com' })
-  })
-})
-```
-
-## Fake Timers
-
-### When to Use Fake Timers
-
-- Testing components with `setTimeout`/`setInterval`
-- Testing debounce/throttle behavior
-- Testing animations or delayed transitions
-- Testing polling or retry logic
-
-### Basic Fake Timer Setup
-
-```typescript
-describe('Debounced Search', () => {
-  beforeEach(() => {
-    vi.useFakeTimers()
-  })
-
-  afterEach(() => {
-    vi.useRealTimers()
-  })
-
-  it('should debounce search input', async () => {
-    const onSearch = vi.fn()
-    render(<SearchInput onSearch={onSearch} debounceMs={300} />)
-    
-    // Type in the input
-    fireEvent.change(screen.getByRole('textbox'), { target: { value: 'query' } })
-    
-    // Search not called immediately
-    expect(onSearch).not.toHaveBeenCalled()
-    
-    // Advance timers
-    vi.advanceTimersByTime(300)
-    
-    // Now search is called
-    expect(onSearch).toHaveBeenCalledWith('query')
-  })
-})
-```
-
-### Fake Timers with Async Code
-
-```typescript
-it('should retry on failure', async () => {
-  vi.useFakeTimers()
-  const fetchData = vi.fn()
-    .mockRejectedValueOnce(new Error('Network error'))
-    .mockResolvedValueOnce({ data: 'success' })
-  
-  render(<RetryComponent fetchData={fetchData} retryDelayMs={1000} />)
-  
-  // First call fails
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledTimes(1)
-  })
-  
-  // Advance timer for retry
-  vi.advanceTimersByTime(1000)
-  
-  // Second call succeeds
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledTimes(2)
-    expect(screen.getByText('success')).toBeInTheDocument()
-  })
-  
-  vi.useRealTimers()
-})
-```
-
-### Common Fake Timer Utilities
-
-```typescript
-// Run all pending timers
-vi.runAllTimers()
-
-// Run only pending timers (not new ones created during execution)
-vi.runOnlyPendingTimers()
-
-// Advance by specific time
-vi.advanceTimersByTime(1000)
-
-// Get current fake time
-Date.now()
-
-// Clear all timers
-vi.clearAllTimers()
-```
-
-## API Testing Patterns
-
-### Loading → Success → Error States
-
-```typescript
-describe('DataFetcher', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('should show loading state', () => {
-    mockedApi.fetchData.mockImplementation(() => new Promise(() => {})) // Never resolves
-    
-    render(<DataFetcher />)
-    
-    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument()
-  })
-
-  it('should show data on success', async () => {
-    mockedApi.fetchData.mockResolvedValue({ items: ['Item 1', 'Item 2'] })
-    
-    render(<DataFetcher />)
-    
-    // Use findBy* for multiple async elements (better error messages than waitFor with multiple assertions)
-    const item1 = await screen.findByText('Item 1')
-    const item2 = await screen.findByText('Item 2')
-    expect(item1).toBeInTheDocument()
-    expect(item2).toBeInTheDocument()
-    
-    expect(screen.queryByTestId('loading-spinner')).not.toBeInTheDocument()
-  })
-
-  it('should show error on failure', async () => {
-    mockedApi.fetchData.mockRejectedValue(new Error('Failed to fetch'))
-    
-    render(<DataFetcher />)
-    
-    await waitFor(() => {
-      expect(screen.getByText(/failed to fetch/i)).toBeInTheDocument()
-    })
-  })
-
-  it('should retry on error', async () => {
-    mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-    
-    render(<DataFetcher />)
-    
-    await waitFor(() => {
-      expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
-    })
-    
-    mockedApi.fetchData.mockResolvedValue({ items: ['Item 1'] })
-    fireEvent.click(screen.getByRole('button', { name: /retry/i }))
-    
-    await waitFor(() => {
-      expect(screen.getByText('Item 1')).toBeInTheDocument()
-    })
-  })
-})
-```
-
-### Testing Mutations
-
-```typescript
-it('should submit form and show success', async () => {
-  const user = userEvent.setup()
-  mockedApi.createItem.mockResolvedValue({ id: '1', name: 'New Item' })
-  
-  render(<CreateItemForm />)
-  
-  await user.type(screen.getByLabelText('Name'), 'New Item')
-  await user.click(screen.getByRole('button', { name: /create/i }))
-  
-  // Button should be disabled during submission
-  expect(screen.getByRole('button', { name: /creating/i })).toBeDisabled()
-  
-  await waitFor(() => {
-    expect(screen.getByText(/created successfully/i)).toBeInTheDocument()
-  })
-  
-  expect(mockedApi.createItem).toHaveBeenCalledWith({ name: 'New Item' })
-})
-```
-
-## useEffect Testing
-
-### Testing Effect Execution
-
-```typescript
-it('should fetch data on mount', async () => {
-  const fetchData = vi.fn().mockResolvedValue({ data: 'test' })
-  
-  render(<ComponentWithEffect fetchData={fetchData} />)
-  
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledTimes(1)
-  })
-})
-```
-
-### Testing Effect Dependencies
-
-```typescript
-it('should refetch when id changes', async () => {
-  const fetchData = vi.fn().mockResolvedValue({ data: 'test' })
-  
-  const { rerender } = render(<ComponentWithEffect id="1" fetchData={fetchData} />)
-  
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledWith('1')
-  })
-  
-  rerender(<ComponentWithEffect id="2" fetchData={fetchData} />)
-  
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledWith('2')
-    expect(fetchData).toHaveBeenCalledTimes(2)
-  })
-})
-```
-
-### Testing Effect Cleanup
-
-```typescript
-it('should cleanup subscription on unmount', () => {
-  const subscribe = vi.fn()
-  const unsubscribe = vi.fn()
-  subscribe.mockReturnValue(unsubscribe)
-  
-  const { unmount } = render(<SubscriptionComponent subscribe={subscribe} />)
-  
-  expect(subscribe).toHaveBeenCalledTimes(1)
-  
-  unmount()
-  
-  expect(unsubscribe).toHaveBeenCalledTimes(1)
-})
-```
-
-## Common Async Pitfalls
-
-### ❌ Don't: Forget to await
-
-```typescript
-// Bad - test may pass even if assertion fails
-it('should load data', () => {
-  render(<Component />)
-  waitFor(() => {
-    expect(screen.getByText('Data')).toBeInTheDocument()
-  })
-})
-
-// Good - properly awaited
-it('should load data', async () => {
-  render(<Component />)
-  await waitFor(() => {
-    expect(screen.getByText('Data')).toBeInTheDocument()
-  })
-})
-```
-
-### ❌ Don't: Use multiple assertions in single waitFor
-
-```typescript
-// Bad - if first assertion fails, won't know about second
-await waitFor(() => {
-  expect(screen.getByText('Title')).toBeInTheDocument()
-  expect(screen.getByText('Description')).toBeInTheDocument()
-})
-
-// Good - separate waitFor or use findBy
-const title = await screen.findByText('Title')
-const description = await screen.findByText('Description')
-expect(title).toBeInTheDocument()
-expect(description).toBeInTheDocument()
-```
-
-### ❌ Don't: Mix fake timers with real async
-
-```typescript
-// Bad - fake timers don't work well with real Promises
-vi.useFakeTimers()
-await waitFor(() => {
-  expect(screen.getByText('Data')).toBeInTheDocument()
-}) // May timeout!
-
-// Good - use runAllTimers or advanceTimersByTime
-vi.useFakeTimers()
-render(<Component />)
-vi.runAllTimers()
-expect(screen.getByText('Data')).toBeInTheDocument()
-```

.agents/skills/frontend-testing/references/checklist.md

@@ -1,208 +0,0 @@
-# Test Generation Checklist
-
-Use this checklist when generating or reviewing tests for Dify frontend components.
-
-## Pre-Generation
-
-- [ ] Read the component source code completely
-- [ ] Identify component type (component, hook, utility, page)
-- [ ] Run `pnpm analyze-component <path>` if available
-- [ ] Note complexity score and features detected
-- [ ] Check for existing tests in the same directory
-- [ ] **Identify ALL files in the directory** that need testing (not just index)
-
-## Testing Strategy
-
-### ⚠️ Incremental Workflow (CRITICAL for Multi-File)
-
-- [ ] **NEVER generate all tests at once** - process one file at a time
-- [ ] Order files by complexity: utilities → hooks → simple → complex → integration
-- [ ] Create a todo list to track progress before starting
-- [ ] For EACH file: write → run test → verify pass → then next
-- [ ] **DO NOT proceed** to next file until current one passes
-
-### Path-Level Coverage
-
-- [ ] **Test ALL files** in the assigned directory/path
-- [ ] List all components, hooks, utilities that need coverage
-- [ ] Decide: single spec file (integration) or multiple spec files (unit)
-
-### Complexity Assessment
-
-- [ ] Run `pnpm analyze-component <path>` for complexity score
-- [ ] **Complexity > 50**: Consider refactoring before testing
-- [ ] **500+ lines**: Consider splitting before testing
-- [ ] **30-50 complexity**: Use multiple describe blocks, organized structure
-
-### Integration vs Mocking
-
-- [ ] **DO NOT mock base components or dify-ui primitives** (base `Loading`, `Input`, `Badge`; dify-ui `Button`, `Tooltip`, `Dialog`, etc.)
-- [ ] Import real project components instead of mocking
-- [ ] Only mock: API calls, complex context providers, third-party libs with side effects
-- [ ] Prefer integration testing when using single spec file
-
-## Required Test Sections
-
-### All Components MUST Have
-
-- [ ] **Rendering tests** - Component renders without crashing
-- [ ] **Props tests** - Required props, optional props, default values
-- [ ] **Edge cases** - null, undefined, empty values, boundaries
-
-### Conditional Sections (Add When Feature Present)
-
-| Feature | Add Tests For |
-|---------|---------------|
-| `useState` | Initial state, transitions, cleanup |
-| `useEffect` | Execution, dependencies, cleanup |
-| Event handlers | onClick, onChange, onSubmit, keyboard |
-| API calls | Loading, success, error states |
-| Routing | Navigation, params, query strings |
-| `useCallback`/`useMemo` | Referential equality |
-| Context | Provider values, consumer behavior |
-| Forms | Validation, submission, error display |
-
-## Code Quality Checklist
-
-### Structure
-
-- [ ] Uses `describe` blocks to group related tests
-- [ ] Test names follow `should <behavior> when <condition>` pattern
-- [ ] AAA pattern (Arrange-Act-Assert) is clear
-- [ ] Comments explain complex test scenarios
-
-### Mocks
-
-- [ ] **DO NOT mock base components or dify-ui primitives** (`@/app/components/base/*` or `@langgenius/dify-ui/*`)
-- [ ] `vi.clearAllMocks()` in `beforeEach` (not `afterEach`)
-- [ ] Shared mock state reset in `beforeEach`
-- [ ] i18n uses global mock (auto-loaded in `web/vitest.setup.ts`); only override locally for custom translations
-- [ ] Router mocks match actual Next.js API
-- [ ] Mocks reflect actual component conditional behavior
-- [ ] Only mock: API services, complex context providers, third-party libs
-- [ ] For `nuqs` URL-state tests, wrap with `NuqsTestingAdapter` (prefer `web/test/nuqs-testing.tsx`)
-- [ ] For `nuqs` URL-state tests, assert `onUrlUpdate` payload (`searchParams`, `options.history`)
-- [ ] If custom `nuqs` parser exists, add round-trip tests for encoded edge cases (`%2F`, `%25`, spaces, legacy encoded values)
-
-### Queries
-
-- [ ] Prefer semantic queries (`getByRole`, `getByLabelText`)
-- [ ] Use `queryBy*` for absence assertions
-- [ ] Use `findBy*` for async elements
-- [ ] `getByTestId` only as last resort
-
-### Async
-
-- [ ] All async tests use `async/await`
-- [ ] `waitFor` wraps async assertions
-- [ ] Fake timers properly setup/teardown
-- [ ] No floating promises
-
-### TypeScript
-
-- [ ] No `any` types without justification
-- [ ] Mock data uses actual types from source
-- [ ] Factory functions have proper return types
-
-## Coverage Goals (Per File)
-
-For the current file being tested:
-
-- [ ] 100% function coverage
-- [ ] 100% statement coverage
-- [ ] >95% branch coverage
-- [ ] >95% line coverage
-
-## Post-Generation (Per File)
-
-**Run these checks after EACH test file, not just at the end:**
-
-- [ ] Run `pnpm test path/to/file.spec.tsx` - **MUST PASS before next file**
-- [ ] Fix any failures immediately
-- [ ] Mark file as complete in todo list
-- [ ] Only then proceed to next file
-
-### After All Files Complete
-
-- [ ] Run full directory test: `pnpm test path/to/directory/`
-- [ ] Check coverage report: `pnpm test:coverage`
-- [ ] Run `pnpm lint:fix` on all test files
-- [ ] Run `pnpm type-check`
-
-## Common Issues to Watch
-
-### False Positives
-
-```typescript
-// ❌ Mock doesn't match actual behavior
-vi.mock('./Component', () => () => <div>Mocked</div>)
-
-// ✅ Mock matches actual conditional logic
-vi.mock('./Component', () => ({ isOpen }: any) =>
-  isOpen ? <div>Content</div> : null
-)
-```
-
-### State Leakage
-
-```typescript
-// ❌ Shared state not reset
-let mockState = false
-vi.mock('./useHook', () => () => mockState)
-
-// ✅ Reset in beforeEach
-beforeEach(() => {
-  mockState = false
-})
-```
-
-### Async Race Conditions
-
-```typescript
-// ❌ Not awaited
-it('loads data', () => {
-  render(<Component />)
-  expect(screen.getByText('Data')).toBeInTheDocument()
-})
-
-// ✅ Properly awaited
-it('loads data', async () => {
-  render(<Component />)
-  await waitFor(() => {
-    expect(screen.getByText('Data')).toBeInTheDocument()
-  })
-})
-```
-
-### Missing Edge Cases
-
-Always test these scenarios:
-
-- `null` / `undefined` inputs
-- Empty strings / arrays / objects
-- Boundary values (0, -1, MAX_INT)
-- Error states
-- Loading states
-- Disabled states
-
-## Quick Commands
-
-```bash
-# Run specific test
-pnpm test path/to/file.spec.tsx
-
-# Run with coverage
-pnpm test:coverage path/to/file.spec.tsx
-
-# Watch mode
-pnpm test:watch path/to/file.spec.tsx
-
-# Update snapshots (use sparingly)
-pnpm test -u path/to/file.spec.tsx
-
-# Analyze component
-pnpm analyze-component path/to/component.tsx
-
-# Review existing test
-pnpm analyze-component path/to/component.tsx --review
-```

.agents/skills/frontend-testing/references/common-patterns.md

@@ -1,449 +0,0 @@
-# Common Testing Patterns
-
-## Query Priority
-
-Use queries in this order (most to least preferred):
-
-```typescript
-// 1. getByRole - Most recommended (accessibility)
-screen.getByRole('button', { name: /submit/i })
-screen.getByRole('textbox', { name: /email/i })
-screen.getByRole('heading', { level: 1 })
-
-// 2. getByLabelText - Form fields
-screen.getByLabelText('Email address')
-screen.getByLabelText(/password/i)
-
-// 3. getByPlaceholderText - When no label
-screen.getByPlaceholderText('Search...')
-
-// 4. getByText - Non-interactive elements
-screen.getByText('Welcome to Dify')
-screen.getByText(/loading/i)
-
-// 5. getByDisplayValue - Current input value
-screen.getByDisplayValue('current value')
-
-// 6. getByAltText - Images
-screen.getByAltText('Company logo')
-
-// 7. getByTitle - Tooltip elements
-screen.getByTitle('Close')
-
-// 8. getByTestId - Last resort only!
-screen.getByTestId('custom-element')
-```
-
-## Event Handling Patterns
-
-### Click Events
-
-```typescript
-// Basic click
-fireEvent.click(screen.getByRole('button'))
-
-// With userEvent (preferred for realistic interaction)
-const user = userEvent.setup()
-await user.click(screen.getByRole('button'))
-
-// Double click
-await user.dblClick(screen.getByRole('button'))
-
-// Right click
-await user.pointer({ keys: '[MouseRight]', target: screen.getByRole('button') })
-```
-
-### Form Input
-
-```typescript
-const user = userEvent.setup()
-
-// Type in input
-await user.type(screen.getByRole('textbox'), 'Hello World')
-
-// Clear and type
-await user.clear(screen.getByRole('textbox'))
-await user.type(screen.getByRole('textbox'), 'New value')
-
-// Select option
-await user.selectOptions(screen.getByRole('combobox'), 'option-value')
-
-// Check checkbox
-await user.click(screen.getByRole('checkbox'))
-
-// Upload file
-const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-await user.upload(screen.getByLabelText(/upload/i), file)
-```
-
-### Keyboard Events
-
-```typescript
-const user = userEvent.setup()
-
-// Press Enter
-await user.keyboard('{Enter}')
-
-// Press Escape
-await user.keyboard('{Escape}')
-
-// Keyboard shortcut
-await user.keyboard('{Control>}a{/Control}') // Ctrl+A
-
-// Tab navigation
-await user.tab()
-
-// Arrow keys
-await user.keyboard('{ArrowDown}')
-await user.keyboard('{ArrowUp}')
-```
-
-## Component State Testing
-
-### Testing State Transitions
-
-```typescript
-describe('Counter', () => {
-  it('should increment count', async () => {
-    const user = userEvent.setup()
-    render(<Counter initialCount={0} />)
-    
-    // Initial state
-    expect(screen.getByText('Count: 0')).toBeInTheDocument()
-    
-    // Trigger transition
-    await user.click(screen.getByRole('button', { name: /increment/i }))
-    
-    // New state
-    expect(screen.getByText('Count: 1')).toBeInTheDocument()
-  })
-})
-```
-
-### Testing Controlled Components
-
-```typescript
-describe('ControlledInput', () => {
-  it('should call onChange with new value', async () => {
-    const user = userEvent.setup()
-    const handleChange = vi.fn()
-    
-    render(<ControlledInput value="" onChange={handleChange} />)
-    
-    await user.type(screen.getByRole('textbox'), 'a')
-    
-    expect(handleChange).toHaveBeenCalledWith('a')
-  })
-
-  it('should display controlled value', () => {
-    render(<ControlledInput value="controlled" onChange={vi.fn()} />)
-    
-    expect(screen.getByRole('textbox')).toHaveValue('controlled')
-  })
-})
-```
-
-## Conditional Rendering Testing
-
-```typescript
-describe('ConditionalComponent', () => {
-  it('should show loading state', () => {
-    render(<DataDisplay isLoading={true} data={null} />)
-    
-    expect(screen.getByText(/loading/i)).toBeInTheDocument()
-    expect(screen.queryByTestId('data-content')).not.toBeInTheDocument()
-  })
-
-  it('should show error state', () => {
-    render(<DataDisplay isLoading={false} data={null} error="Failed to load" />)
-    
-    expect(screen.getByText(/failed to load/i)).toBeInTheDocument()
-  })
-
-  it('should show data when loaded', () => {
-    render(<DataDisplay isLoading={false} data={{ name: 'Test' }} />)
-    
-    expect(screen.getByText('Test')).toBeInTheDocument()
-  })
-
-  it('should show empty state when no data', () => {
-    render(<DataDisplay isLoading={false} data={[]} />)
-    
-    expect(screen.getByText(/no data/i)).toBeInTheDocument()
-  })
-})
-```
-
-## List Rendering Testing
-
-```typescript
-describe('ItemList', () => {
-  const items = [
-    { id: '1', name: 'Item 1' },
-    { id: '2', name: 'Item 2' },
-    { id: '3', name: 'Item 3' },
-  ]
-
-  it('should render all items', () => {
-    render(<ItemList items={items} />)
-    
-    expect(screen.getAllByRole('listitem')).toHaveLength(3)
-    items.forEach(item => {
-      expect(screen.getByText(item.name)).toBeInTheDocument()
-    })
-  })
-
-  it('should handle item selection', async () => {
-    const user = userEvent.setup()
-    const onSelect = vi.fn()
-    
-    render(<ItemList items={items} onSelect={onSelect} />)
-    
-    await user.click(screen.getByText('Item 2'))
-    
-    expect(onSelect).toHaveBeenCalledWith(items[1])
-  })
-
-  it('should handle empty list', () => {
-    render(<ItemList items={[]} />)
-    
-    expect(screen.getByText(/no items/i)).toBeInTheDocument()
-  })
-})
-```
-
-## Modal/Dialog Testing
-
-```typescript
-describe('Modal', () => {
-  it('should not render when closed', () => {
-    render(<Modal isOpen={false} onClose={vi.fn()} />)
-    
-    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
-  })
-
-  it('should render when open', () => {
-    render(<Modal isOpen={true} onClose={vi.fn()} />)
-    
-    expect(screen.getByRole('dialog')).toBeInTheDocument()
-  })
-
-  it('should call onClose when clicking overlay', async () => {
-    const user = userEvent.setup()
-    const handleClose = vi.fn()
-    
-    render(<Modal isOpen={true} onClose={handleClose} />)
-    
-    await user.click(screen.getByTestId('modal-overlay'))
-    
-    expect(handleClose).toHaveBeenCalled()
-  })
-
-  it('should call onClose when pressing Escape', async () => {
-    const user = userEvent.setup()
-    const handleClose = vi.fn()
-    
-    render(<Modal isOpen={true} onClose={handleClose} />)
-    
-    await user.keyboard('{Escape}')
-    
-    expect(handleClose).toHaveBeenCalled()
-  })
-
-  it('should trap focus inside modal', async () => {
-    const user = userEvent.setup()
-    
-    render(
-      <Modal isOpen={true} onClose={vi.fn()}>
-        <button>First</button>
-        <button>Second</button>
-      </Modal>
-    )
-    
-    // Focus should cycle within modal
-    await user.tab()
-    expect(screen.getByText('First')).toHaveFocus()
-    
-    await user.tab()
-    expect(screen.getByText('Second')).toHaveFocus()
-    
-    await user.tab()
-    expect(screen.getByText('First')).toHaveFocus() // Cycles back
-  })
-})
-```
-
-## Form Testing
-
-```typescript
-describe('LoginForm', () => {
-  it('should submit valid form', async () => {
-    const user = userEvent.setup()
-    const onSubmit = vi.fn()
-    
-    render(<LoginForm onSubmit={onSubmit} />)
-    
-    await user.type(screen.getByLabelText(/email/i), 'test@example.com')
-    await user.type(screen.getByLabelText(/password/i), 'password123')
-    await user.click(screen.getByRole('button', { name: /sign in/i }))
-    
-    expect(onSubmit).toHaveBeenCalledWith({
-      email: 'test@example.com',
-      password: 'password123',
-    })
-  })
-
-  it('should show validation errors', async () => {
-    const user = userEvent.setup()
-    
-    render(<LoginForm onSubmit={vi.fn()} />)
-    
-    // Submit empty form
-    await user.click(screen.getByRole('button', { name: /sign in/i }))
-    
-    expect(screen.getByText(/email is required/i)).toBeInTheDocument()
-    expect(screen.getByText(/password is required/i)).toBeInTheDocument()
-  })
-
-  it('should validate email format', async () => {
-    const user = userEvent.setup()
-    
-    render(<LoginForm onSubmit={vi.fn()} />)
-    
-    await user.type(screen.getByLabelText(/email/i), 'invalid-email')
-    await user.click(screen.getByRole('button', { name: /sign in/i }))
-    
-    expect(screen.getByText(/invalid email/i)).toBeInTheDocument()
-  })
-
-  it('should disable submit button while submitting', async () => {
-    const user = userEvent.setup()
-    const onSubmit = vi.fn(() => new Promise(resolve => setTimeout(resolve, 100)))
-    
-    render(<LoginForm onSubmit={onSubmit} />)
-    
-    await user.type(screen.getByLabelText(/email/i), 'test@example.com')
-    await user.type(screen.getByLabelText(/password/i), 'password123')
-    await user.click(screen.getByRole('button', { name: /sign in/i }))
-    
-    expect(screen.getByRole('button', { name: /signing in/i })).toBeDisabled()
-    
-    await waitFor(() => {
-      expect(screen.getByRole('button', { name: /sign in/i })).toBeEnabled()
-    })
-  })
-})
-```
-
-## Data-Driven Tests with test.each
-
-```typescript
-describe('StatusBadge', () => {
-  test.each([
-    ['success', 'bg-green-500'],
-    ['warning', 'bg-yellow-500'],
-    ['error', 'bg-red-500'],
-    ['info', 'bg-blue-500'],
-  ])('should apply correct class for %s status', (status, expectedClass) => {
-    render(<StatusBadge status={status} />)
-    
-    expect(screen.getByTestId('status-badge')).toHaveClass(expectedClass)
-  })
-
-  test.each([
-    { input: null, expected: 'Unknown' },
-    { input: undefined, expected: 'Unknown' },
-    { input: '', expected: 'Unknown' },
-    { input: 'invalid', expected: 'Unknown' },
-  ])('should show "Unknown" for invalid input: $input', ({ input, expected }) => {
-    render(<StatusBadge status={input} />)
-    
-    expect(screen.getByText(expected)).toBeInTheDocument()
-  })
-})
-```
-
-## Debugging Tips
-
-```typescript
-// Print entire DOM
-screen.debug()
-
-// Print specific element
-screen.debug(screen.getByRole('button'))
-
-// Log testing playground URL
-screen.logTestingPlaygroundURL()
-
-// Pretty print DOM
-import { prettyDOM } from '@testing-library/react'
-console.log(prettyDOM(screen.getByRole('dialog')))
-
-// Check available roles
-import { getRoles } from '@testing-library/react'
-console.log(getRoles(container))
-```
-
-## Common Mistakes to Avoid
-
-### ❌ Don't Use Implementation Details
-
-```typescript
-// Bad - testing implementation
-expect(component.state.isOpen).toBe(true)
-expect(wrapper.find('.internal-class').length).toBe(1)
-
-// Good - testing behavior
-expect(screen.getByRole('dialog')).toBeInTheDocument()
-```
-
-### ❌ Don't Forget Cleanup
-
-```typescript
-// Bad - may leak state between tests
-it('test 1', () => {
-  render(<Component />)
-})
-
-// Good - cleanup is automatic with RTL, but reset mocks
-beforeEach(() => {
-  vi.clearAllMocks()
-})
-```
-
-### ❌ Don't Use Exact String Matching (Prefer Black-Box Assertions)
-
-```typescript
-// ❌ Bad - hardcoded strings are brittle
-expect(screen.getByText('Submit Form')).toBeInTheDocument()
-expect(screen.getByText('Loading...')).toBeInTheDocument()
-
-// ✅ Good - role-based queries (most semantic)
-expect(screen.getByRole('button', { name: /submit/i })).toBeInTheDocument()
-expect(screen.getByRole('status')).toBeInTheDocument()
-
-// ✅ Good - pattern matching (flexible)
-expect(screen.getByText(/submit/i)).toBeInTheDocument()
-expect(screen.getByText(/loading/i)).toBeInTheDocument()
-
-// ✅ Good - test behavior, not exact UI text
-expect(screen.getByRole('button')).toBeDisabled()
-expect(screen.getByRole('alert')).toBeInTheDocument()
-```
-
-**Why prefer black-box assertions?**
-
-- Text content may change (i18n, copy updates)
-- Role-based queries test accessibility
-- Pattern matching is resilient to minor changes
-- Tests focus on behavior, not implementation details
-
-### ❌ Don't Assert on Absence Without Query
-
-```typescript
-// Bad - throws if not found
-expect(screen.getByText('Error')).not.toBeInTheDocument() // Error!
-
-// Good - use queryBy for absence assertions
-expect(screen.queryByText('Error')).not.toBeInTheDocument()
-```

.agents/skills/frontend-testing/references/domain-components.md

@@ -1,523 +0,0 @@
-# Domain-Specific Component Testing
-
-This guide covers testing patterns for Dify's domain-specific components.
-
-## Workflow Components (`workflow/`)
-
-Workflow components handle node configuration, data flow, and graph operations.
-
-### Key Test Areas
-
-1. **Node Configuration**
-1. **Data Validation**
-1. **Variable Passing**
-1. **Edge Connections**
-1. **Error Handling**
-
-### Example: Node Configuration Panel
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import NodeConfigPanel from './node-config-panel'
-import { createMockNode, createMockWorkflowContext } from '@/__mocks__/workflow'
-
-// Mock workflow context
-vi.mock('@/app/components/workflow/hooks', () => ({
-  useWorkflowStore: () => mockWorkflowStore,
-  useNodesInteractions: () => mockNodesInteractions,
-}))
-
-let mockWorkflowStore = {
-  nodes: [],
-  edges: [],
-  updateNode: vi.fn(),
-}
-
-let mockNodesInteractions = {
-  handleNodeSelect: vi.fn(),
-  handleNodeDelete: vi.fn(),
-}
-
-describe('NodeConfigPanel', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockWorkflowStore = {
-      nodes: [],
-      edges: [],
-      updateNode: vi.fn(),
-    }
-  })
-
-  describe('Node Configuration', () => {
-    it('should render node type selector', () => {
-      const node = createMockNode({ type: 'llm' })
-      render(<NodeConfigPanel node={node} />)
-      
-      expect(screen.getByLabelText(/model/i)).toBeInTheDocument()
-    })
-
-    it('should update node config on change', async () => {
-      const user = userEvent.setup()
-      const node = createMockNode({ type: 'llm' })
-      
-      render(<NodeConfigPanel node={node} />)
-      
-      await user.selectOptions(screen.getByLabelText(/model/i), 'gpt-4')
-      
-      expect(mockWorkflowStore.updateNode).toHaveBeenCalledWith(
-        node.id,
-        expect.objectContaining({ model: 'gpt-4' })
-      )
-    })
-  })
-
-  describe('Data Validation', () => {
-    it('should show error for invalid input', async () => {
-      const user = userEvent.setup()
-      const node = createMockNode({ type: 'code' })
-      
-      render(<NodeConfigPanel node={node} />)
-      
-      // Enter invalid code
-      const codeInput = screen.getByLabelText(/code/i)
-      await user.clear(codeInput)
-      await user.type(codeInput, 'invalid syntax {{{')
-      
-      await waitFor(() => {
-        expect(screen.getByText(/syntax error/i)).toBeInTheDocument()
-      })
-    })
-
-    it('should validate required fields', async () => {
-      const node = createMockNode({ type: 'http', data: { url: '' } })
-      
-      render(<NodeConfigPanel node={node} />)
-      
-      fireEvent.click(screen.getByRole('button', { name: /save/i }))
-      
-      await waitFor(() => {
-        expect(screen.getByText(/url is required/i)).toBeInTheDocument()
-      })
-    })
-  })
-
-  describe('Variable Passing', () => {
-    it('should display available variables from upstream nodes', () => {
-      const upstreamNode = createMockNode({
-        id: 'node-1',
-        type: 'start',
-        data: { outputs: [{ name: 'user_input', type: 'string' }] },
-      })
-      const currentNode = createMockNode({
-        id: 'node-2',
-        type: 'llm',
-      })
-      
-      mockWorkflowStore.nodes = [upstreamNode, currentNode]
-      mockWorkflowStore.edges = [{ source: 'node-1', target: 'node-2' }]
-      
-      render(<NodeConfigPanel node={currentNode} />)
-      
-      // Variable selector should show upstream variables
-      fireEvent.click(screen.getByRole('button', { name: /add variable/i }))
-      
-      expect(screen.getByText('user_input')).toBeInTheDocument()
-    })
-
-    it('should insert variable into prompt template', async () => {
-      const user = userEvent.setup()
-      const node = createMockNode({ type: 'llm' })
-      
-      render(<NodeConfigPanel node={node} />)
-      
-      // Click variable button
-      await user.click(screen.getByRole('button', { name: /insert variable/i }))
-      await user.click(screen.getByText('user_input'))
-      
-      const promptInput = screen.getByLabelText(/prompt/i)
-      expect(promptInput).toHaveValue(expect.stringContaining('{{user_input}}'))
-    })
-  })
-})
-```
-
-## Dataset Components (`dataset/`)
-
-Dataset components handle file uploads, data display, and search/filter operations.
-
-### Key Test Areas
-
-1. **File Upload**
-1. **File Type Validation**
-1. **Pagination**
-1. **Search & Filtering**
-1. **Data Format Handling**
-
-### Example: Document Uploader
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import DocumentUploader from './document-uploader'
-
-vi.mock('@/service/datasets', () => ({
-  uploadDocument: vi.fn(),
-  parseDocument: vi.fn(),
-}))
-
-import * as datasetService from '@/service/datasets'
-const mockedService = vi.mocked(datasetService)
-
-describe('DocumentUploader', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  describe('File Upload', () => {
-    it('should accept valid file types', async () => {
-      const user = userEvent.setup()
-      const onUpload = vi.fn()
-      mockedService.uploadDocument.mockResolvedValue({ id: 'doc-1' })
-      
-      render(<DocumentUploader onUpload={onUpload} />)
-      
-      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-      const input = screen.getByLabelText(/upload/i)
-      
-      await user.upload(input, file)
-      
-      await waitFor(() => {
-        expect(mockedService.uploadDocument).toHaveBeenCalledWith(
-          expect.any(FormData)
-        )
-      })
-    })
-
-    it('should reject invalid file types', async () => {
-      const user = userEvent.setup()
-      
-      render(<DocumentUploader />)
-      
-      const file = new File(['content'], 'test.exe', { type: 'application/x-msdownload' })
-      const input = screen.getByLabelText(/upload/i)
-      
-      await user.upload(input, file)
-      
-      expect(screen.getByText(/unsupported file type/i)).toBeInTheDocument()
-      expect(mockedService.uploadDocument).not.toHaveBeenCalled()
-    })
-
-    it('should show upload progress', async () => {
-      const user = userEvent.setup()
-      
-      // Mock upload with progress
-      mockedService.uploadDocument.mockImplementation(() => {
-        return new Promise((resolve) => {
-          setTimeout(() => resolve({ id: 'doc-1' }), 100)
-        })
-      })
-      
-      render(<DocumentUploader />)
-      
-      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-      await user.upload(screen.getByLabelText(/upload/i), file)
-      
-      expect(screen.getByRole('progressbar')).toBeInTheDocument()
-      
-      await waitFor(() => {
-        expect(screen.queryByRole('progressbar')).not.toBeInTheDocument()
-      })
-    })
-  })
-
-  describe('Error Handling', () => {
-    it('should handle upload failure', async () => {
-      const user = userEvent.setup()
-      mockedService.uploadDocument.mockRejectedValue(new Error('Upload failed'))
-      
-      render(<DocumentUploader />)
-      
-      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-      await user.upload(screen.getByLabelText(/upload/i), file)
-      
-      await waitFor(() => {
-        expect(screen.getByText(/upload failed/i)).toBeInTheDocument()
-      })
-    })
-
-    it('should allow retry after failure', async () => {
-      const user = userEvent.setup()
-      mockedService.uploadDocument
-        .mockRejectedValueOnce(new Error('Network error'))
-        .mockResolvedValueOnce({ id: 'doc-1' })
-      
-      render(<DocumentUploader />)
-      
-      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-      await user.upload(screen.getByLabelText(/upload/i), file)
-      
-      await waitFor(() => {
-        expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
-      })
-      
-      await user.click(screen.getByRole('button', { name: /retry/i }))
-      
-      await waitFor(() => {
-        expect(screen.getByText(/uploaded successfully/i)).toBeInTheDocument()
-      })
-    })
-  })
-})
-```
-
-### Example: Document List with Pagination
-
-```typescript
-describe('DocumentList', () => {
-  describe('Pagination', () => {
-    it('should load first page on mount', async () => {
-      mockedService.getDocuments.mockResolvedValue({
-        data: [{ id: '1', name: 'Doc 1' }],
-        total: 50,
-        page: 1,
-        pageSize: 10,
-      })
-      
-      render(<DocumentList datasetId="ds-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByText('Doc 1')).toBeInTheDocument()
-      })
-      
-      expect(mockedService.getDocuments).toHaveBeenCalledWith('ds-1', { page: 1 })
-    })
-
-    it('should navigate to next page', async () => {
-      const user = userEvent.setup()
-      mockedService.getDocuments.mockResolvedValue({
-        data: [{ id: '1', name: 'Doc 1' }],
-        total: 50,
-        page: 1,
-        pageSize: 10,
-      })
-      
-      render(<DocumentList datasetId="ds-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByText('Doc 1')).toBeInTheDocument()
-      })
-      
-      mockedService.getDocuments.mockResolvedValue({
-        data: [{ id: '11', name: 'Doc 11' }],
-        total: 50,
-        page: 2,
-        pageSize: 10,
-      })
-      
-      await user.click(screen.getByRole('button', { name: /next/i }))
-      
-      await waitFor(() => {
-        expect(screen.getByText('Doc 11')).toBeInTheDocument()
-      })
-    })
-  })
-
-  describe('Search & Filtering', () => {
-    it('should filter by search query', async () => {
-      const user = userEvent.setup()
-      vi.useFakeTimers()
-      
-      render(<DocumentList datasetId="ds-1" />)
-      
-      await user.type(screen.getByPlaceholderText(/search/i), 'test query')
-      
-      // Debounce
-      vi.advanceTimersByTime(300)
-      
-      await waitFor(() => {
-        expect(mockedService.getDocuments).toHaveBeenCalledWith(
-          'ds-1',
-          expect.objectContaining({ search: 'test query' })
-        )
-      })
-      
-      vi.useRealTimers()
-    })
-  })
-})
-```
-
-## Configuration Components (`app/configuration/`, `config/`)
-
-Configuration components handle forms, validation, and data persistence.
-
-### Key Test Areas
-
-1. **Form Validation**
-1. **Save/Reset**
-1. **Required vs Optional Fields**
-1. **Configuration Persistence**
-1. **Error Feedback**
-
-### Example: App Configuration Form
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import AppConfigForm from './app-config-form'
-
-vi.mock('@/service/apps', () => ({
-  updateAppConfig: vi.fn(),
-  getAppConfig: vi.fn(),
-}))
-
-import * as appService from '@/service/apps'
-const mockedService = vi.mocked(appService)
-
-describe('AppConfigForm', () => {
-  const defaultConfig = {
-    name: 'My App',
-    description: '',
-    icon: 'default',
-    openingStatement: '',
-  }
-
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockedService.getAppConfig.mockResolvedValue(defaultConfig)
-  })
-
-  describe('Form Validation', () => {
-    it('should require app name', async () => {
-      const user = userEvent.setup()
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      // Clear name field
-      await user.clear(screen.getByLabelText(/name/i))
-      await user.click(screen.getByRole('button', { name: /save/i }))
-      
-      expect(screen.getByText(/name is required/i)).toBeInTheDocument()
-      expect(mockedService.updateAppConfig).not.toHaveBeenCalled()
-    })
-
-    it('should validate name length', async () => {
-      const user = userEvent.setup()
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toBeInTheDocument()
-      })
-      
-      // Enter very long name
-      await user.clear(screen.getByLabelText(/name/i))
-      await user.type(screen.getByLabelText(/name/i), 'a'.repeat(101))
-      
-      expect(screen.getByText(/name must be less than 100 characters/i)).toBeInTheDocument()
-    })
-
-    it('should allow empty optional fields', async () => {
-      const user = userEvent.setup()
-      mockedService.updateAppConfig.mockResolvedValue({ success: true })
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      // Leave description empty (optional)
-      await user.click(screen.getByRole('button', { name: /save/i }))
-      
-      await waitFor(() => {
-        expect(mockedService.updateAppConfig).toHaveBeenCalled()
-      })
-    })
-  })
-
-  describe('Save/Reset Functionality', () => {
-    it('should save configuration', async () => {
-      const user = userEvent.setup()
-      mockedService.updateAppConfig.mockResolvedValue({ success: true })
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      await user.clear(screen.getByLabelText(/name/i))
-      await user.type(screen.getByLabelText(/name/i), 'Updated App')
-      await user.click(screen.getByRole('button', { name: /save/i }))
-      
-      await waitFor(() => {
-        expect(mockedService.updateAppConfig).toHaveBeenCalledWith(
-          'app-1',
-          expect.objectContaining({ name: 'Updated App' })
-        )
-      })
-      
-      expect(screen.getByText(/saved successfully/i)).toBeInTheDocument()
-    })
-
-    it('should reset to default values', async () => {
-      const user = userEvent.setup()
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      // Make changes
-      await user.clear(screen.getByLabelText(/name/i))
-      await user.type(screen.getByLabelText(/name/i), 'Changed Name')
-      
-      // Reset
-      await user.click(screen.getByRole('button', { name: /reset/i }))
-      
-      expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-    })
-
-    it('should show unsaved changes warning', async () => {
-      const user = userEvent.setup()
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      // Make changes
-      await user.type(screen.getByLabelText(/name/i), ' Updated')
-      
-      expect(screen.getByText(/unsaved changes/i)).toBeInTheDocument()
-    })
-  })
-
-  describe('Error Handling', () => {
-    it('should show error on save failure', async () => {
-      const user = userEvent.setup()
-      mockedService.updateAppConfig.mockRejectedValue(new Error('Server error'))
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      await user.click(screen.getByRole('button', { name: /save/i }))
-      
-      await waitFor(() => {
-        expect(screen.getByText(/failed to save/i)).toBeInTheDocument()
-      })
-    })
-  })
-})
-```

.agents/skills/frontend-testing/references/mocking.md

@@ -1,535 +0,0 @@
-# Mocking Guide for Dify Frontend Tests
-
-## ⚠️ Important: What NOT to Mock
-
-### DO NOT Mock Base Components or dify-ui Primitives
-
-**Never mock components from `@/app/components/base/` or from `@langgenius/dify-ui/*`** such as:
-
-- Legacy base (`@/app/components/base/*`): `Loading`, `Spinner`, `Input`, `Badge`, `Tag`
-- dify-ui primitives (`@langgenius/dify-ui/*`): `Button`, `Tooltip`, `Dialog`, `Popover`, `DropdownMenu`, `ContextMenu`, `Select`, `AlertDialog`, `Toast`
-
-**Why?**
-
-- These components have their own dedicated tests
-- Mocking them creates false positives (tests pass but real integration fails)
-- Using real components tests actual integration behavior
-
-```typescript
-// ❌ WRONG: Don't mock base components or dify-ui primitives
-vi.mock('@/app/components/base/loading', () => () => <div>Loading</div>)
-vi.mock('@langgenius/dify-ui/button', () => ({ Button: ({ children }: any) => <button>{children}</button> }))
-
-// ✅ CORRECT: Import and use the real components
-import Loading from '@/app/components/base/loading'
-import { Button } from '@langgenius/dify-ui/button'
-// They will render normally in tests
-```
-
-### What TO Mock
-
-Only mock these categories:
-
-1. **API services** (`@/service/*`) - Network calls
-1. **Complex context providers** - When setup is too difficult
-1. **Third-party libraries with side effects** - `next/navigation`, external SDKs
-1. **i18n** - Always mock to return keys
-
-### Zustand Stores - DO NOT Mock Manually
-
-**Zustand is globally mocked** in `web/vitest.setup.ts`. Use real stores with `setState()`:
-
-```typescript
-// ✅ CORRECT: Use real store, set test state
-import { useAppStore } from '@/app/components/app/store'
-
-useAppStore.setState({ appDetail: { id: 'test', name: 'Test' } })
-render(<MyComponent />)
-
-// ❌ WRONG: Don't mock the store module
-vi.mock('@/app/components/app/store', () => ({ ... }))
-```
-
-See [Zustand Store Testing](#zustand-store-testing) section for full details.
-
-## Mock Placement
-
-| Location | Purpose |
-|----------|---------|
-| `web/vitest.setup.ts` | Global mocks shared by all tests (`react-i18next`, `zustand`, clipboard, FloatingPortal, Monaco, localStorage`) |
-| `web/__mocks__/zustand.ts` | Zustand mock implementation (auto-resets stores after each test) |
-| `web/__mocks__/` | Reusable mock factories shared across multiple test files |
-| Test file | Test-specific mocks, inline with `vi.mock()` |
-
-Modules are not mocked automatically. Use `vi.mock` in test files, or add global mocks in `web/vitest.setup.ts`.
-
-**Note**: Zustand is special - it's globally mocked but you should NOT mock store modules manually. See [Zustand Store Testing](#zustand-store-testing).
-
-## Essential Mocks
-
-### 1. i18n (Auto-loaded via Global Mock)
-
-A global mock is defined in `web/vitest.setup.ts` and is auto-loaded by Vitest setup.
-
-The global mock provides:
-
-- `useTranslation` - returns translation keys with namespace prefix
-- `Trans` component - renders i18nKey and components
-- `useMixedTranslation` (from `@/app/components/plugins/marketplace/hooks`)
-- `useGetLanguage` (from `@/context/i18n`) - returns `'en-US'`
-
-**Default behavior**: Most tests should use the global mock (no local override needed).
-
-**For custom translations**: Use the helper function from `@/test/i18n-mock`:
-
-```typescript
-import { createReactI18nextMock } from '@/test/i18n-mock'
-
-vi.mock('react-i18next', () => createReactI18nextMock({
-  'my.custom.key': 'Custom translation',
-  'button.save': 'Save',
-}))
-```
-
-**Avoid**: Manually defining `useTranslation` mocks that just return the key - the global mock already does this.
-
-### 2. Next.js Router
-
-```typescript
-const mockPush = vi.fn()
-const mockReplace = vi.fn()
-
-vi.mock('next/navigation', () => ({
-  useRouter: () => ({
-    push: mockPush,
-    replace: mockReplace,
-    back: vi.fn(),
-    prefetch: vi.fn(),
-  }),
-  usePathname: () => '/current-path',
-  useSearchParams: () => new URLSearchParams('?key=value'),
-}))
-
-describe('Component', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('should navigate on click', () => {
-    render(<Component />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(mockPush).toHaveBeenCalledWith('/expected-path')
-  })
-})
-```
-
-### 2.1 `nuqs` Query State (Preferred: Testing Adapter)
-
-For tests that validate URL query behavior, use `NuqsTestingAdapter` instead of mocking `nuqs` directly.
-
-```typescript
-import { renderHookWithNuqs } from '@/test/nuqs-testing'
-
-it('should sync query to URL with push history', async () => {
-  const { result, onUrlUpdate } = renderHookWithNuqs(() => useMyQueryState(), {
-    searchParams: '?page=1',
-  })
-
-  act(() => {
-    result.current.setQuery({ page: 2 })
-  })
-
-  await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-  const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-  expect(update.options.history).toBe('push')
-  expect(update.searchParams.get('page')).toBe('2')
-})
-```
-
-Use direct `vi.mock('nuqs')` only when URL synchronization is intentionally out of scope.
-
-### 3. Portal Components (with Shared State)
-
-```typescript
-// ⚠️ Important: Use shared state for components that depend on each other
-let mockPortalOpenState = false
-
-vi.mock('@/app/components/base/portal-to-follow-elem', () => ({
-  PortalToFollowElem: ({ children, open, ...props }: any) => {
-    mockPortalOpenState = open || false  // Update shared state
-    return <div data-testid="portal" data-open={open}>{children}</div>
-  },
-  PortalToFollowElemContent: ({ children }: any) => {
-    // ✅ Matches actual: returns null when portal is closed
-    if (!mockPortalOpenState) return null
-    return <div data-testid="portal-content">{children}</div>
-  },
-  PortalToFollowElemTrigger: ({ children }: any) => (
-    <div data-testid="portal-trigger">{children}</div>
-  ),
-}))
-
-describe('Component', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockPortalOpenState = false  // ✅ Reset shared state
-  })
-})
-```
-
-### 4. API Service Mocks
-
-```typescript
-import * as api from '@/service/api'
-
-vi.mock('@/service/api')
-
-const mockedApi = vi.mocked(api)
-
-describe('Component', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    
-    // Setup default mock implementation
-    mockedApi.fetchData.mockResolvedValue({ data: [] })
-  })
-
-  it('should show data on success', async () => {
-    mockedApi.fetchData.mockResolvedValue({ data: [{ id: 1 }] })
-    
-    render(<Component />)
-    
-    await waitFor(() => {
-      expect(screen.getByText('1')).toBeInTheDocument()
-    })
-  })
-
-  it('should show error on failure', async () => {
-    mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-    
-    render(<Component />)
-    
-    await waitFor(() => {
-      expect(screen.getByText(/error/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-### 5. HTTP and `fetch` Mocking
-
-```typescript
-describe('GithubComponent', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('should display repo info', async () => {
-    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
-      new Response(JSON.stringify({ name: 'dify', stars: 1000 }), {
-        status: 200,
-        headers: { 'Content-Type': 'application/json' },
-      }),
-    )
-    
-    render(<GithubComponent />)
-    
-    await waitFor(() => {
-      expect(screen.getByText('dify')).toBeInTheDocument()
-    })
-  })
-
-  it('should handle API error', async () => {
-    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
-      new Response(JSON.stringify({ message: 'Server error' }), {
-        status: 500,
-        headers: { 'Content-Type': 'application/json' },
-      }),
-    )
-    
-    render(<GithubComponent />)
-    
-    await waitFor(() => {
-      expect(screen.getByText(/error/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-Prefer mocking `@/service/*` modules or spying on `global.fetch` / `ky` clients with deterministic responses. Do not introduce an HTTP interception dependency such as `nock` or MSW unless it is already declared in the workspace or adding it is part of the task.
-
-### 6. Context Providers
-
-```typescript
-import { ProviderContext } from '@/context/provider-context'
-import { createMockProviderContextValue, createMockPlan } from '@/__mocks__/provider-context'
-
-describe('Component with Context', () => {
-  it('should render for free plan', () => {
-    const mockContext = createMockPlan('sandbox')
-    
-    render(
-      <ProviderContext.Provider value={mockContext}>
-        <Component />
-      </ProviderContext.Provider>
-    )
-    
-    expect(screen.getByText('Upgrade')).toBeInTheDocument()
-  })
-
-  it('should render for pro plan', () => {
-    const mockContext = createMockPlan('professional')
-    
-    render(
-      <ProviderContext.Provider value={mockContext}>
-        <Component />
-      </ProviderContext.Provider>
-    )
-    
-    expect(screen.queryByText('Upgrade')).not.toBeInTheDocument()
-  })
-})
-```
-
-### 7. React Query
-
-```typescript
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-
-const createTestQueryClient = () => new QueryClient({
-  defaultOptions: {
-    queries: { retry: false },
-    mutations: { retry: false },
-  },
-})
-
-const renderWithQueryClient = (ui: React.ReactElement) => {
-  const queryClient = createTestQueryClient()
-  return render(
-    <QueryClientProvider client={queryClient}>
-      {ui}
-    </QueryClientProvider>
-  )
-}
-```
-
-## Mock Best Practices
-
-### ✅ DO
-
-1. **Use real base components and dify-ui primitives** - Import from `@/app/components/base/` or `@langgenius/dify-ui/*` directly
-1. **Use real project components** - Prefer importing over mocking
-1. **Use real Zustand stores** - Set test state via `store.setState()`
-1. **Reset mocks in `beforeEach`**, not `afterEach`
-1. **Match actual component behavior** in mocks (when mocking is necessary)
-1. **Use factory functions** for complex mock data
-1. **Import actual types** for type safety
-1. **Reset shared mock state** in `beforeEach`
-
-### ❌ DON'T
-
-1. **Don't mock base components or dify-ui primitives** (`Loading`, `Input`, `Button`, `Tooltip`, `Dialog`, etc.)
-1. **Don't mock Zustand store modules** - Use real stores with `setState()`
-1. Don't mock components you can import directly
-1. Don't create overly simplified mocks that miss conditional logic
-1. Don't leave HTTP mocks or service mock state leaking between tests
-1. Don't use `any` types in mocks without necessity
-
-### Mock Decision Tree
-
-```
-Need to use a component in test?
-│
-├─ Is it from @/app/components/base/* or @langgenius/dify-ui/*?
-│  └─ YES → Import real component, DO NOT mock
-│
-├─ Is it a project component?
-│  └─ YES → Prefer importing real component
-│           Only mock if setup is extremely complex
-│
-├─ Is it an API service (@/service/*)?
-│  └─ YES → Mock it
-│
-├─ Is it a third-party lib with side effects?
-│  └─ YES → Mock it (next/navigation, external SDKs)
-│
-├─ Is it a Zustand store?
-│  └─ YES → DO NOT mock the module!
-│           Use real store + setState() to set test state
-│           (Global mock handles auto-reset)
-│
-└─ Is it i18n?
-   └─ YES → Uses shared mock (auto-loaded). Override only for custom translations
-```
-
-## Zustand Store Testing
-
-### Global Zustand Mock (Auto-loaded)
-
-Zustand is globally mocked in `web/vitest.setup.ts` following the [official Zustand testing guide](https://zustand.docs.pmnd.rs/guides/testing). The mock in `web/__mocks__/zustand.ts` provides:
-
-- Real store behavior with `getState()`, `setState()`, `subscribe()` methods
-- Automatic store reset after each test via `afterEach`
-- Proper test isolation between tests
-
-### ✅ Recommended: Use Real Stores (Official Best Practice)
-
-**DO NOT mock store modules manually.** Import and use the real store, then use `setState()` to set test state:
-
-```typescript
-// ✅ CORRECT: Use real store with setState
-import { useAppStore } from '@/app/components/app/store'
-
-describe('MyComponent', () => {
-  it('should render app details', () => {
-    // Arrange: Set test state via setState
-    useAppStore.setState({
-      appDetail: {
-        id: 'test-app',
-        name: 'Test App',
-        mode: 'chat',
-      },
-    })
-
-    // Act
-    render(<MyComponent />)
-
-    // Assert
-    expect(screen.getByText('Test App')).toBeInTheDocument()
-    // Can also verify store state directly
-    expect(useAppStore.getState().appDetail?.name).toBe('Test App')
-  })
-
-  // No cleanup needed - global mock auto-resets after each test
-})
-```
-
-### ❌ Avoid: Manual Store Module Mocking
-
-Manual mocking conflicts with the global Zustand mock and loses store functionality:
-
-```typescript
-// ❌ WRONG: Don't mock the store module
-vi.mock('@/app/components/app/store', () => ({
-  useStore: (selector) => mockSelector(selector),  // Missing getState, setState!
-}))
-
-// ❌ WRONG: This conflicts with global zustand mock
-vi.mock('@/app/components/workflow/store', () => ({
-  useWorkflowStore: vi.fn(() => mockState),
-}))
-```
-
-**Problems with manual mocking:**
-
-1. Loses `getState()`, `setState()`, `subscribe()` methods
-1. Conflicts with global Zustand mock behavior
-1. Requires manual maintenance of store API
-1. Tests don't reflect actual store behavior
-
-### When Manual Store Mocking is Necessary
-
-In rare cases where the store has complex initialization or side effects, you can mock it, but ensure you provide the full store API:
-
-```typescript
-// If you MUST mock (rare), include full store API
-const mockStore = {
-  appDetail: { id: 'test', name: 'Test' },
-  setAppDetail: vi.fn(),
-}
-
-vi.mock('@/app/components/app/store', () => ({
-  useStore: Object.assign(
-    (selector: (state: typeof mockStore) => unknown) => selector(mockStore),
-    {
-      getState: () => mockStore,
-      setState: vi.fn(),
-      subscribe: vi.fn(),
-    },
-  ),
-}))
-```
-
-### Store Testing Decision Tree
-
-```
-Need to test a component using Zustand store?
-│
-├─ Can you use the real store?
-│  └─ YES → Use real store + setState (RECOMMENDED)
-│           useAppStore.setState({ ... })
-│
-├─ Does the store have complex initialization/side effects?
-│  └─ YES → Consider mocking, but include full API
-│           (getState, setState, subscribe)
-│
-└─ Are you testing the store itself (not a component)?
-   └─ YES → Test store directly with getState/setState
-            const store = useMyStore
-            store.setState({ count: 0 })
-            store.getState().increment()
-            expect(store.getState().count).toBe(1)
-```
-
-### Example: Testing Store Actions
-
-```typescript
-import { useCounterStore } from '@/stores/counter'
-
-describe('Counter Store', () => {
-  it('should increment count', () => {
-    // Initial state (auto-reset by global mock)
-    expect(useCounterStore.getState().count).toBe(0)
-
-    // Call action
-    useCounterStore.getState().increment()
-
-    // Verify state change
-    expect(useCounterStore.getState().count).toBe(1)
-  })
-
-  it('should reset to initial state', () => {
-    // Set some state
-    useCounterStore.setState({ count: 100 })
-    expect(useCounterStore.getState().count).toBe(100)
-
-    // After this test, global mock will reset to initial state
-  })
-})
-```
-
-## Factory Function Pattern
-
-```typescript
-// __mocks__/data-factories.ts
-import type { User, Project } from '@/types'
-
-export const createMockUser = (overrides: Partial<User> = {}): User => ({
-  id: 'user-1',
-  name: 'Test User',
-  email: 'test@example.com',
-  role: 'member',
-  createdAt: new Date().toISOString(),
-  ...overrides,
-})
-
-export const createMockProject = (overrides: Partial<Project> = {}): Project => ({
-  id: 'project-1',
-  name: 'Test Project',
-  description: 'A test project',
-  owner: createMockUser(),
-  members: [],
-  createdAt: new Date().toISOString(),
-  ...overrides,
-})
-
-// Usage in tests
-it('should display project owner', () => {
-  const project = createMockProject({
-    owner: createMockUser({ name: 'John Doe' }),
-  })
-  
-  render(<ProjectCard project={project} />)
-  expect(screen.getByText('John Doe')).toBeInTheDocument()
-})
-```

.agents/skills/frontend-testing/references/workflow.md

@@ -1,269 +0,0 @@
-# Testing Workflow Guide
-
-This guide defines the workflow for generating tests, especially for complex components or directories with multiple files.
-
-## Scope Clarification
-
-This guide addresses **multi-file workflow** (how to process multiple test files). For coverage requirements within a single test file, see `web/docs/test.md` § Coverage Goals.
-
-| Scope | Rule |
-|-------|------|
-| **Single file** | Complete coverage in one generation (100% function, >95% branch) |
-| **Multi-file directory** | Process one file at a time, verify each before proceeding |
-
-## ⚠️ Critical Rule: Incremental Approach for Multi-File Testing
-
-When testing a **directory with multiple files**, **NEVER generate all test files at once.** Use an incremental, verify-as-you-go approach.
-
-### Why Incremental?
-
-| Batch Approach (❌) | Incremental Approach (✅) |
-|---------------------|---------------------------|
-| Generate 5+ tests at once | Generate 1 test at a time |
-| Run tests only at the end | Run test immediately after each file |
-| Multiple failures compound | Single point of failure, easy to debug |
-| Hard to identify root cause | Clear cause-effect relationship |
-| Mock issues affect many files | Mock issues caught early |
-| Messy git history | Clean, atomic commits possible |
-
-## Single File Workflow
-
-When testing a **single component, hook, or utility**:
-
-```
-1. Read source code completely
-2. Run `pnpm analyze-component <path>` (if available)
-3. Check complexity score and features detected
-4. Write the test file
-5. Run test: `pnpm test <file>.spec.tsx`
-6. Fix any failures
-7. Verify coverage meets goals (100% function, >95% branch)
-```
-
-## Directory/Multi-File Workflow (MUST FOLLOW)
-
-When testing a **directory or multiple files**, follow this strict workflow:
-
-### Step 1: Analyze and Plan
-
-1. **List all files** that need tests in the directory
-1. **Categorize by complexity**:
-   - 🟢 **Simple**: Utility functions, simple hooks, presentational components
-   - 🟡 **Medium**: Components with state, effects, or event handlers
-   - 🔴 **Complex**: Components with API calls, routing, or many dependencies
-1. **Order by dependency**: Test dependencies before dependents
-1. **Create a todo list** to track progress
-
-### Step 2: Determine Processing Order
-
-Process files in this recommended order:
-
-```
-1. Utility functions (simplest, no React)
-2. Custom hooks (isolated logic)
-3. Simple presentational components (few/no props)
-4. Medium complexity components (state, effects)
-5. Complex components (API, routing, many deps)
-6. Container/index components (integration tests - last)
-```
-
-**Rationale**:
-
-- Simpler files help establish mock patterns
-- Hooks used by components should be tested first
-- Integration tests (index files) depend on child components working
-
-### Step 3: Process Each File Incrementally
-
-**For EACH file in the ordered list:**
-
-```
-┌─────────────────────────────────────────────┐
-│  1. Write test file                         │
-│  2. Run: pnpm test <file>.spec.tsx          │
-│  3. If FAIL → Fix immediately, re-run       │
-│  4. If PASS → Mark complete in todo list    │
-│  5. ONLY THEN proceed to next file          │
-└─────────────────────────────────────────────┘
-```
-
-**DO NOT proceed to the next file until the current one passes.**
-
-### Step 4: Final Verification
-
-After all individual tests pass:
-
-```bash
-# Run all tests in the directory together
-pnpm test path/to/directory/
-
-# Check coverage
-pnpm test:coverage path/to/directory/
-```
-
-## Component Complexity Guidelines
-
-Use `pnpm analyze-component <path>` to assess complexity before testing.
-
-### 🔴 Very Complex Components (Complexity > 50)
-
-**Consider refactoring BEFORE testing:**
-
-- Break component into smaller, testable pieces
-- Extract complex logic into custom hooks
-- Separate container and presentational layers
-
-**If testing as-is:**
-
-- Use integration tests for complex workflows
-- Use `test.each()` for data-driven testing
-- Multiple `describe` blocks for organization
-- Consider testing major sections separately
-
-### 🟡 Medium Complexity (Complexity 30-50)
-
-- Group related tests in `describe` blocks
-- Test integration scenarios between internal parts
-- Focus on state transitions and side effects
-- Use helper functions to reduce test complexity
-
-### 🟢 Simple Components (Complexity < 30)
-
-- Standard test structure
-- Focus on props, rendering, and edge cases
-- Usually straightforward to test
-
-### 📏 Large Files (500+ lines)
-
-Regardless of complexity score:
-
-- **Strongly consider refactoring** before testing
-- If testing as-is, test major sections separately
-- Create helper functions for test setup
-- May need multiple test files
-
-## Todo List Format
-
-When testing multiple files, use a todo list like this:
-
-```
-Testing: path/to/directory/
-
-Ordered by complexity (simple → complex):
-
-☐ utils/helper.ts           [utility, simple]
-☐ hooks/use-custom-hook.ts  [hook, simple]
-☐ empty-state.tsx           [component, simple]
-☐ item-card.tsx             [component, medium]
-☐ list.tsx                  [component, complex]
-☐ index.tsx                 [integration]
-
-Progress: 0/6 complete
-```
-
-Update status as you complete each:
-
-- ☐ → ⏳ (in progress)
-- ⏳ → ✅ (complete and verified)
-- ⏳ → ❌ (blocked, needs attention)
-
-## When to Stop and Verify
-
-**Always run tests after:**
-
-- Completing a test file
-- Making changes to fix a failure
-- Modifying shared mocks
-- Updating test utilities or helpers
-
-**Signs you should pause:**
-
-- More than 2 consecutive test failures
-- Mock-related errors appearing
-- Unclear why a test is failing
-- Test passing but coverage unexpectedly low
-
-## Common Pitfalls to Avoid
-
-### ❌ Don't: Generate Everything First
-
-```
-# BAD: Writing all files then testing
-Write component-a.spec.tsx
-Write component-b.spec.tsx  
-Write component-c.spec.tsx
-Write component-d.spec.tsx
-Run pnpm test  ← Multiple failures, hard to debug
-```
-
-### ✅ Do: Verify Each Step
-
-```
-# GOOD: Incremental with verification
-Write component-a.spec.tsx
-Run pnpm test component-a.spec.tsx ✅
-Write component-b.spec.tsx
-Run pnpm test component-b.spec.tsx ✅
-...continue...
-```
-
-### ❌ Don't: Skip Verification for "Simple" Components
-
-Even simple components can have:
-
-- Import errors
-- Missing mock setup
-- Incorrect assumptions about props
-
-**Always verify, regardless of perceived simplicity.**
-
-### ❌ Don't: Continue When Tests Fail
-
-Failing tests compound:
-
-- A mock issue in file A affects files B, C, D
-- Fixing A later requires revisiting all dependent tests
-- Time wasted on debugging cascading failures
-
-**Fix failures immediately before proceeding.**
-
-## Integration with Codex's Todo Feature
-
-When using Codex for multi-file testing:
-
-1. **Create a todo list** before starting
-1. **Process one file at a time**
-1. **Verify each test passes** before asking for the next
-1. **Mark todos complete** as you progress
-
-Example prompt:
-
-```
-Test all components in `path/to/directory/`.
-First, analyze the directory and create a todo list ordered by complexity.
-Then, process ONE file at a time, waiting for my confirmation that tests pass
-before proceeding to the next.
-```
-
-## Summary Checklist
-
-Before starting multi-file testing:
-
-- [ ] Listed all files needing tests
-- [ ] Ordered by complexity (simple → complex)
-- [ ] Created todo list for tracking
-- [ ] Understand dependencies between files
-
-During testing:
-
-- [ ] Processing ONE file at a time
-- [ ] Running tests after EACH file
-- [ ] Fixing failures BEFORE proceeding
-- [ ] Updating todo list progress
-
-After completion:
-
-- [ ] All individual tests pass
-- [ ] Full directory test run passes
-- [ ] Coverage goals met
-- [ ] Todo list shows all complete

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

@@ -18,6 +18,7 @@ Use this as the component decision guide for Dify web. Existing code is referenc
 | 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. |
+| Where should a hotkey live? | Keep a single-owner hotkey constant in its component. | Multiple production files share one command, or the feature owns a real command registry with shared metadata and behavior. |
 | 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
@@ -77,6 +78,19 @@ Use this as the component decision guide for Dify web. Existing code is referenc
 - 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.
 
+## Keyboard Shortcuts
+
+- Distinguish application commands from local keyboard semantics before choosing an API. Use `@tanstack/react-hotkeys` for application commands. Keep menu navigation, dialog Escape handling owned by a primitive, editor commands, and other widget-scoped ARIA interactions in their local component or primitive.
+- Use `useHotkey` or `useHotkeys` for registered commands. For a command intentionally owned by an existing `onKeyDown`, use `matchesKeyboardEvent` instead of hand-written `metaKey` / `ctrlKey` parsing or a second global listener.
+- Define a reusable string command with `satisfies Hotkey` and an object-form command with `satisfies RawHotkey`. Reserve `RegisterableHotkey` for API boundaries that intentionally accept either form. A one-time inline literal passed directly to TanStack is already type-checked; extract it when registration, display, metadata, or another production consumer needs the same source.
+- Keep registered hotkeys distinct from held keys and display-only accelerators. Use `IndividualKey` with `useKeyHold` for held-key interactions, and use an explicitly named `displayKey` for local widget accelerators that are not registered `Hotkey` values.
+- Keep registration and keycap/menu display derived from one canonical command. Do not maintain a hotkey string beside a separate `['Mod', ...]` display array.
+- Keep a single-owner command constant in its owning component. Create a feature-local `hotkeys.ts` only when multiple production files consume the same command. Keep a dedicated definitions/registry module when a feature owns a real command system with IDs, metadata, alternate bindings, and centralized registration. Tests do not count as another production owner, and file-name uniformity alone is not a reason to extract.
+- Make scope and availability explicit. Use `enabled` for business or surface lifecycle, `ignoreInputs` for whether input-like elements may trigger the command, and `target` when the command belongs to a concrete DOM subtree. Global application commands may use the document target; inline editors and composed overlays should prefer the actual editor or Base UI Popup ref when that owner is exposed.
+- Put a scoped ref on the real behavior owner. Do not add a wrapper DOM element solely to obtain a hotkey target. If a shared overlay convenience component hides the Popup ref, either rely on its modal lifecycle/focus boundary when that is sufficient or design the primitive API separately; do not create a fake owner at the call site.
+- Set `preventDefault` and `stopPropagation` according to the existing product behavior and browser interaction. Do not silently accept TanStack defaults when migrating from another listener if that changes typing, submission, or propagation semantics.
+- Test observable command behavior, disabled/input/target scope, and the shared registration/display contract at the owning feature boundary. Prefer partial mocks that retain TanStack formatting and matching behavior when a registration boundary must be isolated.
+
 ## 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/*`.

.codex/hooks.json

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

.dockerignore

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

.github/CODEOWNERS

@@ -6,7 +6,8 @@
 
 * @crazywoola @laipz8200
 
-# ESLint suppression file is maintained by autofix.ci pruning.
+# Lint bulk suppression baselines.
+/oxlint-suppressions.json
 /eslint-suppressions.json
 
 # CODEOWNERS file

.github/dependabot.yml

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

.github/workflows/api-tests.yml

@@ -16,7 +16,7 @@ concurrency:
 jobs:
   api-unit:
     name: API Unit Tests
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     env:
       COVERAGE_FILE: coverage-unit
     defaults:
@@ -35,7 +35,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -75,7 +75,7 @@ jobs:
 
   api-integration:
     name: API Integration Tests
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     env:
       COVERAGE_FILE: coverage-integration
       STORAGE_TYPE: opendal
@@ -97,7 +97,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -129,7 +129,7 @@ jobs:
 
   api-coverage:
     name: API Coverage
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     needs:
       - api-unit
       - api-integration
@@ -148,7 +148,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           python-version: "3.12"

.github/workflows/autofix.yml

@@ -13,7 +13,7 @@ permissions:
 jobs:
   autofix:
     if: github.repository == 'langgenius/dify'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Complete merge group check
         if: github.event_name == 'merge_group'
@@ -39,11 +39,22 @@ jobs:
         with:
           files: |
             web/**
+            cli/**
+            e2e/**
             packages/**
+            sdks/nodejs-client/**
             package.json
             pnpm-lock.yaml
             pnpm-workspace.yaml
             .nvmrc
+            vite.config.ts
+            lint.config.ts
+            eslint.config.mjs
+            oxlint-suppressions.json
+            eslint-suppressions.json
+            .vscode/**
+            .github/workflows/autofix.yml
+            .github/workflows/style.yml
       - name: Check api inputs
         if: github.event_name != 'merge_group'
         id: api-changes
@@ -78,7 +89,7 @@ jobs:
           python-version: "3.11"
 
       - if: github.event_name != 'merge_group'
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Generate Docker Compose
         if: github.event_name != 'merge_group' && steps.docker-compose-changes.outputs.any_changed == 'true'
@@ -158,10 +169,13 @@ jobs:
         if: github.event_name != 'merge_group' && steps.frontend-contract-changes.outputs.any_changed == 'true'
         run: pnpm --dir packages/contracts gen-api-contract
 
-      - name: ESLint autofix
+      - name: ESLint fallback autofix
         if: github.event_name != 'merge_group' && steps.web-changes.outputs.any_changed == 'true'
-        run: |
-          vp exec eslint --concurrency=2 --prune-suppressions --quiet || true
+        run: pnpm lint:eslint:fix --quiet || true
+
+      - name: Vite+ static autofix
+        if: github.event_name != 'merge_group' && (steps.web-changes.outputs.any_changed == 'true' || steps.frontend-contract-changes.outputs.any_changed == 'true')
+        run: vp check --fix || true
 
       - if: github.event_name != 'merge_group'
         uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a # v1.3.4

.github/workflows/build-push.yml

@@ -78,15 +78,15 @@ jobs:
           - 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"
+            build_context: "{{defaultContext}}:dify-agent-runtime"
+            file: "docker/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"
+            build_context: "{{defaultContext}}:dify-agent-runtime"
+            file: "docker/Dockerfile"
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
 
@@ -120,6 +120,7 @@ jobs:
           file: ${{ matrix.file }}
           platforms: ${{ matrix.platform }}
           build-args: COMMIT_SHA=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}
+          build-contexts: ${{ matrix.build_contexts }}
           labels: ${{ steps.meta.outputs.labels }}
           outputs: type=image,name=${{ env[matrix.image_name_env] }},push-by-digest=true,name-canonical=true,push=true
 
@@ -155,8 +156,8 @@ jobs:
             build_context: "{{defaultContext}}"
             file: "dify-agent/Dockerfile"
           - service_name: "validate-agent-local-sandbox-amd64"
-            build_context: "{{defaultContext}}:dify-agent"
-            file: "docker/local-sandbox/Dockerfile"
+            build_context: "{{defaultContext}}:dify-agent-runtime"
+            file: "docker/Dockerfile"
     steps:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
@@ -167,11 +168,12 @@ jobs:
           push: false
           context: ${{ matrix.build_context }}
           file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
           platforms: linux/amd64
 
   create-manifest:
     needs: build
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     if: github.repository == 'langgenius/dify'
     strategy:
       matrix:

.github/workflows/cli-release.yml

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

.github/workflows/cli-tests.yml

@@ -46,7 +46,7 @@ jobs:
         if: matrix.os == 'depot-ubuntu-24.04'
         run: scripts/release-validate-manifest.sh
 
-      - name: CI pipeline (typecheck, lint, coverage, build)
+      - name: CI pipeline (tree, coverage, build)
         run: pnpm run ci
 
       - name: Report coverage

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

@@ -9,7 +9,7 @@ concurrency:
 
 jobs:
   db-migration-test-postgres:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     steps:
       - name: Checkout code
@@ -19,7 +19,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           python-version: "3.12"
@@ -59,7 +59,7 @@ jobs:
         run: uv run --directory api flask upgrade-db
 
   db-migration-test-mysql:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     steps:
       - name: Checkout code
@@ -69,7 +69,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           python-version: "3.12"

.github/workflows/deploy-agent.yml

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

.github/workflows/deploy-dev.yml

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

.github/workflows/deploy-enterprise.yml

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

.github/workflows/deploy-saas.yml

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

.github/workflows/docker-build.yml

@@ -13,6 +13,11 @@ on:
       - dify-agent/README.md
       - dify-agent/src/**
       - web/Dockerfile
+      - dify-agent-runtime/docker/Dockerfile
+      - dify-agent-runtime/go.mod
+      - dify-agent-runtime/go.sum
+      - dify-agent-runtime/cmd/**
+      - dify-agent-runtime/internal/**
 
 concurrency:
   group: docker-build-${{ github.head_ref || github.run_id }}
@@ -48,6 +53,16 @@ jobs:
             runs_on: depot-ubuntu-24.04-4
             context: "{{defaultContext}}"
             file: "web/Dockerfile"
+          - service_name: "local-sandbox-amd64"
+            platform: linux/amd64
+            runs_on: depot-ubuntu-24.04-4
+            context: "{{defaultContext}}:dify-agent-runtime"
+            file: "docker/Dockerfile"
+          - service_name: "local-sandbox-arm64"
+            platform: linux/arm64
+            runs_on: depot-ubuntu-24.04-4
+            context: "{{defaultContext}}:dify-agent-runtime"
+            file: "docker/Dockerfile"
     steps:
       - name: Set up Depot CLI
         uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
@@ -59,6 +74,7 @@ jobs:
           push: false
           context: ${{ matrix.context }}
           file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
           platforms: ${{ matrix.platform }}
 
   build-docker-fork:
@@ -75,6 +91,9 @@ jobs:
           - service_name: "web-amd64"
             context: "{{defaultContext}}"
             file: "web/Dockerfile"
+          - service_name: "local-sandbox-amd64"
+            context: "{{defaultContext}}:dify-agent-runtime"
+            file: "docker/Dockerfile"
     steps:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
@@ -85,4 +104,5 @@ jobs:
           push: false
           context: ${{ matrix.context }}
           file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
           platforms: linux/amd64

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

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

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

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

.github/workflows/labeler.yml

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

.github/workflows/main-ci.yml

@@ -21,13 +21,13 @@ concurrency:
 jobs:
   pre_job:
     name: Skip Duplicate Checks
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     outputs:
       should_skip: ${{ steps.skip_check.outputs.should_skip || 'false' }}
     steps:
       - id: skip_check
         continue-on-error: true
-        uses: fkirc/skip-duplicate-actions@f75f66ce1886f00957d99748a42c724f4330bdcf # v5.3.1
+        uses: fkirc/skip-duplicate-actions@b974a9395958c231af965b70070979a577efa578 # v5.3.2
         with:
           cancel_others: 'true'
           concurrent_skipping: same_content_newer
@@ -37,7 +37,7 @@ jobs:
     name: Check Changed Files
     needs: pre_job
     if: needs.pre_job.outputs.should_skip != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     outputs:
       api-changed: ${{ steps.changes.outputs.api }}
       cli-changed: ${{ steps.changes.outputs.cli }}
@@ -45,6 +45,7 @@ jobs:
       web-changed: ${{ steps.changes.outputs.web }}
       vdb-changed: ${{ steps.changes.outputs.vdb }}
       migration-changed: ${{ steps.changes.outputs.migration }}
+      sandbox-runtime-changed: ${{ steps.changes.outputs.sandbox-runtime }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
@@ -53,8 +54,12 @@ jobs:
           filters: |
             api:
               - 'api/**'
+              - 'scripts/ast_grep_guard.py'
               - 'scripts/check_no_new_getattr.py'
+              - 'scripts/check_no_new_controller_sqlalchemy.py'
+              - 'scripts/lint_controller_sqlalchemy.py'
               - 'scripts/ast_grep_rules/no_new_getattr.yml'
+              - 'scripts/ast_grep_rules/no_new_controller_sqlalchemy.yml'
               - '.github/workflows/style.yml'
               - '.github/workflows/main-ci.yml'
               - '.github/workflows/api-tests.yml'
@@ -67,11 +72,12 @@ jobs:
               - 'docker/volumes/sandbox/conf/**'
             cli:
               - 'cli/**'
+              - 'packages/contracts/**'
               - 'packages/tsconfig/**'
               - 'package.json'
               - 'pnpm-lock.yaml'
               - 'pnpm-workspace.yaml'
-              - 'eslint.config.mjs'
+              - 'lint.config.ts'
               - '.npmrc'
               - '.nvmrc'
               - '.github/workflows/cli-tests.yml'
@@ -100,6 +106,7 @@ jobs:
               - 'docker/docker-compose.middleware.yaml'
               - 'docker/envs/middleware.env.example'
               - '.github/workflows/web-e2e.yml'
+              - '.github/workflows/main-ci.yml'
               - '.github/actions/setup-web/**'
             vdb:
               - 'api/core/rag/datasource/**'
@@ -126,6 +133,9 @@ jobs:
               - 'docker/volumes/**'
               - 'api/uv.lock'
               - 'api/pyproject.toml'
+            sandbox-runtime:
+              - 'dify-agent-runtime/**'
+              - '.github/workflows/sandbox-runtime-tests.yml'
             migration:
               - 'api/migrations/**'
               - 'api/.env.example'
@@ -154,7 +164,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.api-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped API tests
         run: echo "No API-related changes detected; skipping API tests."
@@ -167,7 +177,7 @@ jobs:
       - check-changes
       - api-tests-run
       - api-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize API Tests status
         env:
@@ -214,7 +224,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.cli-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped CLI tests
         run: echo "No CLI-related changes detected; skipping CLI tests."
@@ -227,7 +237,7 @@ jobs:
       - check-changes
       - cli-tests-run
       - cli-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize CLI Tests status
         env:
@@ -274,7 +284,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.web-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped web tests
         run: echo "No web-related changes detected; skipping web tests."
@@ -287,7 +297,7 @@ jobs:
       - check-changes
       - web-tests-run
       - web-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize Web Tests status
         env:
@@ -334,7 +344,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.e2e-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped web full-stack e2e
         run: echo "No E2E-related changes detected; skipping web full-stack E2E."
@@ -347,7 +357,7 @@ jobs:
       - check-changes
       - web-e2e-run
       - web-e2e-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize Web Full-Stack E2E status
         env:
@@ -401,7 +411,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.vdb-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped VDB tests
         run: echo "No VDB-related changes detected; skipping VDB tests."
@@ -414,7 +424,7 @@ jobs:
       - check-changes
       - vdb-tests-run
       - vdb-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize VDB Tests status
         env:
@@ -460,7 +470,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.migration-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped DB migration tests
         run: echo "No migration-related changes detected; skipping DB migration tests."
@@ -473,7 +483,7 @@ jobs:
       - check-changes
       - db-migration-test-run
       - db-migration-test-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize DB Migration Test status
         env:
@@ -504,3 +514,63 @@ jobs:
 
           echo "DB migration tests were not required, but the skip job finished with result: $SKIP_RESULT" >&2
           exit 1
+
+  sandbox-runtime-tests-run:
+    name: Run Sandbox Runtime Tests
+    needs:
+      - pre_job
+      - check-changes
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.sandbox-runtime-changed == 'true'
+    uses: ./.github/workflows/sandbox-runtime-tests.yml
+    secrets: inherit
+
+  sandbox-runtime-tests-skip:
+    name: Skip Sandbox Runtime Tests
+    needs:
+      - pre_job
+      - check-changes
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.sandbox-runtime-changed != 'true'
+    runs-on: depot-ubuntu-24.04-4
+    steps:
+      - name: Report skipped sandbox runtime tests
+        run: echo "No sandbox-runtime-related changes detected; skipping sandbox runtime tests."
+
+  sandbox-runtime-tests:
+    name: Sandbox Runtime Tests
+    if: ${{ always() }}
+    needs:
+      - pre_job
+      - check-changes
+      - sandbox-runtime-tests-run
+      - sandbox-runtime-tests-skip
+    runs-on: depot-ubuntu-24.04-4
+    steps:
+      - name: Finalize Sandbox Runtime Tests status
+        env:
+          SHOULD_SKIP_WORKFLOW: ${{ needs.pre_job.outputs.should_skip }}
+          TESTS_CHANGED: ${{ needs.check-changes.outputs.sandbox-runtime-changed }}
+          RUN_RESULT: ${{ needs.sandbox-runtime-tests-run.result }}
+          SKIP_RESULT: ${{ needs.sandbox-runtime-tests-skip.result }}
+        run: |
+          if [[ "$SHOULD_SKIP_WORKFLOW" == 'true' ]]; then
+            echo "Sandbox runtime tests were skipped because this workflow run duplicated a successful or newer run."
+            exit 0
+          fi
+
+          if [[ "$TESTS_CHANGED" == 'true' ]]; then
+            if [[ "$RUN_RESULT" == 'success' ]]; then
+              echo "Sandbox runtime tests ran successfully."
+              exit 0
+            fi
+
+            echo "Sandbox runtime tests were required but finished with result: $RUN_RESULT" >&2
+            exit 1
+          fi
+
+          if [[ "$SKIP_RESULT" == 'success' ]]; then
+            echo "Sandbox runtime tests were skipped because no sandbox-runtime-related files changed."
+            exit 0
+          fi
+
+          echo "Sandbox runtime tests were not required, but the skip job finished with result: $SKIP_RESULT" >&2
+          exit 1

.github/workflows/post-merge.yml

@@ -14,7 +14,7 @@ concurrency:
 jobs:
   check-changes:
     name: Check Changed Files
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     outputs:
       external-e2e-changed: ${{ steps.changes.outputs.external_e2e }}
     steps:
@@ -25,12 +25,20 @@ jobs:
           filters: |
             external_e2e:
               - 'e2e/features/agent-v2/**'
+              - 'e2e/features/step-definitions/agent-v2/**'
+              - 'e2e/features/support/**'
+              - 'e2e/fixtures/test-materials/**'
               - 'e2e/scripts/**'
               - 'e2e/support/**'
+              - 'e2e/cucumber.config.ts'
+              - 'e2e/package.json'
+              - 'e2e/test-env.ts'
+              - 'e2e/tsx-register.js'
               - '.github/workflows/post-merge.yml'
               - '.github/workflows/web-e2e.yml'
               - '.github/actions/setup-web/**'
               - 'dify-agent/**'
+              - 'dify-agent-runtime/**'
               - 'api/clients/agent_backend/**'
               - 'api/core/app/apps/agent_app/**'
               - 'api/core/workflow/nodes/agent_v2/**'
@@ -40,9 +48,25 @@ jobs:
               - 'api/services/plugin/**'
               - 'api/core/tools/**'
               - 'api/services/tools/**'
+              - 'packages/contracts/generated/api/console/agent/**'
+              - 'packages/contracts/generated/api/console/orpc.gen.ts'
               - 'web/features/agent-v2/**'
+              - 'web/app/(commonLayout)/agents/**'
+              - 'web/app/(commonLayout)/@detailSidebar/agents/**'
               - 'web/app/(commonLayout)/roster/**'
+              - 'web/app/components/base/chat/chat/**'
+              - 'web/app/components/base/voice-input/**'
               - 'web/app/components/workflow/nodes/agent-v2/**'
+              - 'web/i18n/en-US/agent-v-2.json'
+              - 'web/i18n/en-US/common.json'
+              - 'web/service/base.ts'
+              - 'web/service/client.ts'
+              - 'web/service/console-link.ts'
+              - 'web/service/console-openapi-url.ts'
+              - 'web/service/console-router-loader.ts'
+              - 'web/service/share.ts'
+              - 'web/package.json'
+              - 'pnpm-workspace.yaml'
 
   external-e2e:
     name: External Runtime E2E

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

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

.github/workflows/pyrefly-diff.yml

@@ -10,7 +10,7 @@ permissions:
 
 jobs:
   pyrefly-diff:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       contents: read
       issues: write
@@ -22,7 +22,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
 

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

@@ -12,7 +12,7 @@ permissions: {}
 jobs:
   comment:
     name: Comment PR with type coverage
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       actions: read
       contents: read
@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
 

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

@@ -10,7 +10,7 @@ permissions:
 
 jobs:
   pyrefly-type-coverage:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       contents: read
       issues: write
@@ -22,7 +22,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
 

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

@@ -0,0 +1,98 @@
+name: Sandbox Runtime Tests
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sandbox-runtime-tests-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  sandbox-runtime-unit:
+    name: Sandbox Runtime Unit Tests
+    runs-on: depot-ubuntu-24.04-4
+    defaults:
+      run:
+        shell: bash
+        working-directory: dify-agent-runtime
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: dify-agent-runtime/go.mod
+          cache-dependency-path: dify-agent-runtime/go.sum
+
+      - name: Run unit tests
+        run: go test -race -count=1 ./...
+
+  sandbox-runtime-lint:
+    name: Sandbox Runtime Lint
+    runs-on: depot-ubuntu-24.04-4
+    defaults:
+      run:
+        shell: bash
+        working-directory: dify-agent-runtime
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: dify-agent-runtime/go.mod
+          cache-dependency-path: dify-agent-runtime/go.sum
+
+      - name: Run golangci-lint
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v6.5.0
+        with:
+          working-directory: dify-agent-runtime
+          version: latest
+
+  sandbox-runtime-integration:
+    name: Sandbox Runtime Integration Tests
+    runs-on: depot-ubuntu-24.04-4
+    defaults:
+      run:
+        shell: bash
+        working-directory: dify-agent-runtime
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: dify-agent-runtime/go.mod
+          cache-dependency-path: dify-agent-runtime/go.sum
+
+      - name: Build and start runtime
+        run: make integration-up
+
+      - name: Run integration tests
+        run: make integration-test
+
+      - name: Dump container logs on failure
+        if: failure()
+        run: make integration-logs || true
+
+      - name: Stop runtime container
+        if: always()
+        run: make integration-down

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

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

.github/workflows/stale.yml

@@ -12,13 +12,13 @@ on:
 jobs:
   stale:
 
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       issues: write
       pull-requests: write
 
     steps:
-      - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 # v10.3.0
+      - uses: actions/stale@1e223db275d687790206a7acac4d1a11bd6fe629 # v10.4.0
         with:
           days-before-issue-stale: 15
           days-before-issue-close: 3

.github/workflows/style.yml

@@ -19,7 +19,7 @@ permissions:
 jobs:
   python-style:
     name: Python Style
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     steps:
       - name: Checkout code
@@ -34,14 +34,18 @@ jobs:
         with:
           files: |
             api/**
+            scripts/ast_grep_guard.py
             scripts/check_no_new_getattr.py
+            scripts/check_no_new_controller_sqlalchemy.py
+            scripts/lint_controller_sqlalchemy.py
             scripts/ast_grep_rules/no_new_getattr.yml
+            scripts/ast_grep_rules/no_new_controller_sqlalchemy.yml
             .github/workflows/style.yml
             .github/workflows/main-ci.yml
 
       - name: Setup UV and Python
         if: steps.changed-files.outputs.any_changed == 'true'
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: false
           python-version: "3.12"
@@ -63,6 +67,10 @@ jobs:
         if: steps.changed-files.outputs.any_changed == 'true'
         run: uv run --project api python scripts/check_no_new_getattr.py --base-rev "${{ inputs.base-rev }}"
 
+      - name: Run No New Controller SQLAlchemy Guard
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: uv run --project api python scripts/check_no_new_controller_sqlalchemy.py --base-rev "${{ inputs.base-rev }}"
+
       - name: Run Type Checks
         if: steps.changed-files.outputs.any_changed == 'true'
         env:
@@ -75,7 +83,7 @@ jobs:
 
   web-style:
     name: Web Style
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     defaults:
       run:
         working-directory: ./web
@@ -129,7 +137,7 @@ jobs:
 
   ts-common-style:
     name: TS Common
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       checks: write
       pull-requests: read
@@ -154,7 +162,13 @@ jobs:
             pnpm-lock.yaml
             pnpm-workspace.yaml
             .nvmrc
+            vite.config.ts
+            lint.config.ts
             eslint.config.mjs
+            oxlint-suppressions.json
+            eslint-suppressions.json
+            .vscode/**
+            .github/workflows/autofix.yml
             .github/workflows/style.yml
             .github/actions/setup-web/**
 
@@ -162,34 +176,13 @@ jobs:
         if: steps.changed-files.outputs.any_changed == 'true'
         uses: ./.github/actions/setup-web
 
-      - name: Restore ESLint cache
+      - name: Static check
         if: steps.changed-files.outputs.any_changed == 'true'
-        id: eslint-cache-restore
-        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: .eslintcache
-          key: ${{ runner.os }}-eslint-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'web/eslint.config.mjs', 'web/eslint.constants.mjs', 'web/plugins/eslint/**') }}-${{ github.sha }}
-          restore-keys: |
-            ${{ runner.os }}-eslint-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'web/eslint.config.mjs', 'web/eslint.constants.mjs', 'web/plugins/eslint/**') }}-
-
-      - name: Style check
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: vp run lint:ci
-
-      - name: Type check
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: vp run type-check
-
-      - name: Save ESLint cache
-        if: steps.changed-files.outputs.any_changed == 'true' && success() && steps.eslint-cache-restore.outputs.cache-hit != 'true'
-        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: .eslintcache
-          key: ${{ steps.eslint-cache-restore.outputs.cache-primary-key }}
+        run: pnpm -w check
 
   superlinter:
     name: SuperLinter
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     steps:
       - name: Checkout code

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

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

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

@@ -35,7 +35,7 @@ concurrency:
 jobs:
   translate:
     if: github.repository == 'langgenius/dify'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     timeout-minutes: 120
 
     steps:
@@ -158,7 +158,7 @@ jobs:
 
       - name: Run Claude Code for Translation Sync
         if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@558b1d6cab4085c7753fe402c10bef0fbb92ac7a # v1.0.165
+        uses: anthropics/claude-code-action@af0559ee4f514d1ef21826982bed13f7edc3c35e # v1.0.178
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -223,7 +223,7 @@ jobs:
                - Match the existing terminology and register used by each locale.
                - Prefer one Edit per file when stable, but prioritize correctness over batching.
             6. Verify only the edited files.
-               - Run `vp run dify-web#lint:fix --quiet -- <relative edited i18n file paths under web/>`
+               - Run `vp fmt <repo-relative edited paths such as web/i18n/...>`
                - Run `vp run dify-web#i18n:check ${{ steps.context.outputs.FILE_ARGS }} ${{ steps.context.outputs.LANG_ARGS }}`
                - If verification fails, fix the remaining problems before continuing.
             7. Stop after the scoped locale files are updated and verification passes.
@@ -322,7 +322,7 @@ jobs:
             '## Verification',
             '',
             `- \`vp run dify-web#i18n:check --file ${process.env.FILES_IN_SCOPE} --lang ${process.env.TARGET_LANGS}\``,
-            `- \`vp run dify-web#lint:fix --quiet -- <edited i18n files under web/>\``,
+            `- \`vp fmt <repo-relative edited paths such as web/i18n/...>\``,
             '',
             '## Notes',
             '',

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

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

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

@@ -16,7 +16,7 @@ jobs:
   test:
     name: Full VDB Tests
     if: github.repository == 'langgenius/dify'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     strategy:
       matrix:
         python-version:
@@ -36,7 +36,7 @@ jobs:
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/vdb-tests.yml

@@ -13,7 +13,7 @@ concurrency:
 jobs:
   test:
     name: VDB Smoke Tests
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     strategy:
       matrix:
         python-version:
@@ -33,7 +33,7 @@ jobs:
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/web-e2e.yml

@@ -19,6 +19,7 @@ jobs:
   test:
     name: Web Full-Stack E2E
     runs-on: depot-ubuntu-24.04-4
+    timeout-minutes: 120
     defaults:
       run:
         shell: bash
@@ -33,7 +34,7 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
           python-version: "3.12"
@@ -44,6 +45,10 @@ jobs:
       - name: Install API dependencies
         run: uv sync --project api --dev
 
+      - name: Run E2E support unit tests
+        working-directory: ./e2e
+        run: vp run test:unit
+
       - name: Install Playwright browser
         working-directory: ./e2e
         run: vp run e2e:install
@@ -58,7 +63,52 @@ jobs:
           E2E_INIT_PASSWORD: E2eInit12345
         run: vp run e2e:full
 
-      - name: Run external runtime E2E tests
+      - name: Preserve Chromium E2E report and logs
+        if: ${{ !cancelled() }}
+        run: |
+          if [[ -d e2e/cucumber-report ]]; then
+            mv e2e/cucumber-report e2e/cucumber-report-non-external
+          fi
+          if [[ -d e2e/.logs ]]; then
+            mv e2e/.logs e2e/.logs-non-external
+          fi
+
+      - name: Run WebKit keyboard and browser smoke tests
+        working-directory: ./e2e
+        env:
+          E2E_ADMIN_EMAIL: e2e-admin@example.com
+          E2E_ADMIN_NAME: E2E Admin
+          E2E_ADMIN_PASSWORD: E2eAdmin12345
+          E2E_BROWSER: webkit
+          E2E_INIT_PASSWORD: E2eInit12345
+        run: |
+          teardown_webkit_smoke() {
+            local run_status=$?
+            trap - EXIT
+            if ! vp run e2e:middleware:down; then
+              echo "::error title=E2E teardown failed::WebKit smoke middleware did not shut down cleanly."
+              if [[ "$run_status" -eq 0 ]]; then
+                run_status=1
+              fi
+            fi
+            exit "$run_status"
+          }
+
+          trap teardown_webkit_smoke EXIT
+          vp run e2e:middleware:up
+          vp run e2e -- --tags '@browser-smoke'
+
+      - name: Preserve WebKit E2E report and logs
+        if: ${{ !cancelled() }}
+        run: |
+          if [[ -d e2e/cucumber-report ]]; then
+            mv e2e/cucumber-report e2e/cucumber-report-webkit
+          fi
+          if [[ -d e2e/.logs ]]; then
+            mv e2e/.logs e2e/.logs-webkit
+          fi
+
+      - name: Run prepared and external runtime E2E tests
         if: ${{ inputs.run-external-runtime }}
         working-directory: ./e2e
         env:
@@ -68,14 +118,13 @@ jobs:
           E2E_AGENT_DECISION_MODEL_NAME: ${{ vars.E2E_AGENT_DECISION_MODEL_NAME || 'gpt-5.5' }}
           E2E_AGENT_DECISION_MODEL_PROVIDER: ${{ vars.E2E_AGENT_DECISION_MODEL_PROVIDER || 'openai' }}
           E2E_AGENT_DECISION_MODEL_TYPE: ${{ vars.E2E_AGENT_DECISION_MODEL_TYPE || 'llm' }}
-          E2E_EXTERNAL_RUNTIME_SEED_SPECS: ${{ vars.E2E_EXTERNAL_RUNTIME_SEED_SPECS }}
-          E2E_EXTERNAL_RUNTIME_TAGS: ${{ vars.E2E_EXTERNAL_RUNTIME_TAGS }}
           E2E_FORCE_WEB_BUILD: "1"
           E2E_INIT_PASSWORD: E2eInit12345
           E2E_MARKETPLACE_API_URL: ${{ vars.E2E_MARKETPLACE_API_URL }}
           E2E_MARKETPLACE_PLUGIN_IDS: ${{ vars.E2E_MARKETPLACE_PLUGIN_IDS }}
-          E2E_MARKETPLACE_PLUGIN_UNIQUE_IDENTIFIERS: ${{ vars.E2E_MARKETPLACE_PLUGIN_UNIQUE_IDENTIFIERS }}
           E2E_MODEL_PROVIDER_CREDENTIALS_JSON: ${{ secrets.E2E_MODEL_PROVIDER_CREDENTIALS_JSON }}
+          E2E_SPEECH_TO_TEXT_MODEL_NAME: ${{ vars.E2E_SPEECH_TO_TEXT_MODEL_NAME || 'gpt-4o-mini-transcribe' }}
+          E2E_SPEECH_TO_TEXT_MODEL_PROVIDER: ${{ vars.E2E_SPEECH_TO_TEXT_MODEL_PROVIDER || 'openai' }}
           E2E_START_AGENT_BACKEND: ${{ vars.E2E_START_AGENT_BACKEND || '1' }}
           E2E_STABLE_MODEL_NAME: ${{ vars.E2E_STABLE_MODEL_NAME || 'gpt-5-nano' }}
           E2E_STABLE_MODEL_PROVIDER: ${{ vars.E2E_STABLE_MODEL_PROVIDER || 'openai' }}
@@ -91,10 +140,27 @@ jobs:
             mv cucumber-report cucumber-report-non-external
           fi
 
-          trap 'vp run e2e:middleware:down' EXIT
+          if [[ -d .logs ]]; then
+            rm -rf .logs-non-external
+            mv .logs .logs-non-external
+          fi
+
+          teardown_external_runtime() {
+            local run_status=$?
+            trap - EXIT
+            if ! vp run e2e:middleware:down; then
+              echo "::error title=E2E teardown failed::External runtime middleware did not shut down cleanly."
+              if [[ "$run_status" -eq 0 ]]; then
+                run_status=1
+              fi
+            fi
+            exit "$run_status"
+          }
+
+          trap teardown_external_runtime EXIT
           vp run e2e:middleware:up
-          vp run e2e:external:prepare
-          vp run e2e:external
+          vp run e2e:post-merge:prepare
+          vp run e2e:post-merge
 
       - name: Upload Cucumber report
         if: ${{ !cancelled() }}
@@ -104,6 +170,7 @@ jobs:
           path: |
             e2e/cucumber-report
             e2e/cucumber-report-non-external
+            e2e/cucumber-report-webkit
           retention-days: 7
 
       - name: Upload E2E logs
@@ -111,5 +178,18 @@ jobs:
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: e2e-logs
-          path: e2e/.logs
+          path: |
+            e2e/.logs/*.log
+            e2e/.logs-non-external/*.log
+            e2e/.logs-webkit/*.log
+          include-hidden-files: true
+          retention-days: 7
+
+      - name: Upload E2E seed report
+        if: ${{ !cancelled() && inputs.run-external-runtime }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-seed-report
+          path: e2e/seed-report
+          if-no-files-found: ignore
           retention-days: 7

.gitignore

@@ -30,6 +30,11 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+# KnowledgeFS is an independently rooted TypeScript workspace. Its admin `lib`
+# directory contains source files rather than Python build output.
+!/knowledge-fs/apps/admin/lib/
+!/knowledge-fs/apps/admin/lib/**
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
@@ -214,6 +219,7 @@ sdks/python-client/dify_client.egg-info
 api/.vscode
 # vscode Code History Extension
 .history
+.eslintcache
 
 .idea/
 
@@ -258,7 +264,9 @@ scripts/stress-test/reports/
 # Code Agent Folder
 .qoder/*
 .context/
-.eslintcache
-
 # Vitest local reports
 web/.vitest-reports/
+
+# dify-agent-runtime
+dify-agent-runtime/bin/
+dify-agent-runtime/.integration-state

.vscode/launch.json.template

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

.vscode/settings.example.json

@@ -1,54 +1,37 @@
 {
-  "cucumber.features": [
-    "e2e/features/**/*.feature",
-  ],
-  "cucumber.glue": [
-    "e2e/features/**/*.ts",
-  ],
+  "cucumber.features": ["e2e/features/**/*.feature"],
+  "cucumber.glue": ["e2e/features/**/*.ts"],
 
   "tailwindCSS.experimental.configFile": "web/app/styles/globals.css",
 
-  // Auto fix
+  // Format
+  "[javascript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[javascriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[typescript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[typescriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[json]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[jsonc]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[markdown]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[mdx]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[yaml]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[toml]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[css]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[scss]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[less]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[html]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[vue]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[svelte]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[graphql]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[handlebars]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+  "oxc.fmt.configPath": "./vite.config.ts",
+
+  // Lint fix
+  "eslint.useFlatConfig": true,
+  "eslint.validate": ["json", "jsonc", "markdown", "yaml", "toml"],
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit",
-  },
-
-  // Silent the stylistic rules in your IDE, but still auto fix them
-  "eslint.rules.customizations": [
-    { "rule": "style/*", "severity": "off", "fixable": true },
-    { "rule": "format/*", "severity": "off", "fixable": true },
-    { "rule": "*-indent", "severity": "off", "fixable": true },
-    { "rule": "*-spacing", "severity": "off", "fixable": true },
-    { "rule": "*-spaces", "severity": "off", "fixable": true },
-    { "rule": "*-order", "severity": "off", "fixable": true },
-    { "rule": "*-dangle", "severity": "off", "fixable": true },
-    { "rule": "*-newline", "severity": "off", "fixable": true },
-    { "rule": "*quotes", "severity": "off", "fixable": true },
-    { "rule": "*semi", "severity": "off", "fixable": true }
-  ],
-
-  // Enable eslint for all supported languages
-  "eslint.validate": [
-    "javascript",
-    "javascriptreact",
-    "typescript",
-    "typescriptreact",
-    "vue",
-    "html",
-    "markdown",
-    "json",
-    "jsonc",
-    "yaml",
-    "toml",
-    "xml",
-    "gql",
-    "graphql",
-    "astro",
-    "svelte",
-    "css",
-    "less",
-    "scss",
-    "pcss",
-    "postcss"
-  ]
+    "source.fixAll.oxc": "explicit",
+    "source.fixAll.eslint": "explicit"
+  }
 }

AGENTS.md

@@ -31,7 +31,7 @@ The codebase is split into:
 ## Language Style
 
 - **Python**: Keep type hints on functions and attributes, and implement relevant special methods (e.g., `__repr__`, `__str__`). Prefer `TypedDict` over `dict` or `Mapping` for type safety and better code documentation.
-- **TypeScript**: Use the strict config, rely on ESLint (`pnpm lint:fix` preferred) plus `pnpm type-check`, and avoid `any` types.
+- **TypeScript**: Use the strict config, run `pnpm check` for formatting, Oxlint, ESLint non-code checks, and type checking, and avoid `any` types.
 
 ## General Practices
 

CONTRIBUTING.md

@@ -66,7 +66,7 @@ How we prioritize:
 1. Fork the repository
 1. Before you draft a PR, please create an issue to discuss the changes you want to make
 1. Create a new branch for your changes
-1. Please add tests for your changes accordingly
+1. Add or update tests when the change affects observable behavior or carries meaningful regression risk
 1. Ensure your code passes the existing tests
 1. Please link the issue in the PR description, `fixes #<issue_number>`
 1. Get merged!
@@ -77,7 +77,7 @@ How we prioritize:
 
 For setting up the frontend service, please refer to our comprehensive [guide](https://github.com/langgenius/dify/blob/main/web/README.md) in the `web/README.md` file. This document provides detailed instructions to help you set up the frontend environment properly.
 
-**Testing**: All React components must have comprehensive test coverage. See [web/docs/test.md](https://github.com/langgenius/dify/blob/main/web/docs/test.md) for the canonical frontend testing guidelines and follow every requirement described there.
+**Testing**: Add focused tests when a change affects observable behavior or carries meaningful regression risk. See [web/docs/test.md](https://github.com/langgenius/dify/blob/main/web/docs/test.md) for the canonical frontend testing guidelines.
 
 #### Backend
 

Makefile

@@ -2,6 +2,7 @@
 DOCKER_REGISTRY=langgenius
 WEB_IMAGE=$(DOCKER_REGISTRY)/dify-web
 API_IMAGE=$(DOCKER_REGISTRY)/dify-api
+SANDBOX_RUNTIME_IMAGE=$(DOCKER_REGISTRY)/dify-agent-local-sandbox
 VERSION=latest
 DOCKER_DIR=docker
 DOCKER_MIDDLEWARE_ENV=$(DOCKER_DIR)/middleware.env
@@ -160,6 +161,13 @@ build-api:
 	docker build -t $(API_IMAGE):$(VERSION) -f api/Dockerfile .
 	@echo "API Docker image built successfully: $(API_IMAGE):$(VERSION)"
 
+build-sandbox-runtime:
+	@echo "Building sandbox runtime Docker image: $(SANDBOX_RUNTIME_IMAGE):$(VERSION)..."
+	docker build -t $(SANDBOX_RUNTIME_IMAGE):$(VERSION) \
+		-f dify-agent-runtime/docker/Dockerfile \
+		dify-agent-runtime
+	@echo "Sandbox runtime Docker image built successfully: $(SANDBOX_RUNTIME_IMAGE):$(VERSION)"
+
 # Push Docker images
 push-web:
 	@echo "Pushing web Docker image: $(WEB_IMAGE):$(VERSION)..."
@@ -171,14 +179,20 @@ push-api:
 	docker push $(API_IMAGE):$(VERSION)
 	@echo "API Docker image pushed successfully: $(API_IMAGE):$(VERSION)"
 
+push-sandbox-runtime:
+	@echo "Pushing sandbox runtime Docker image: $(SANDBOX_RUNTIME_IMAGE):$(VERSION)..."
+	docker push $(SANDBOX_RUNTIME_IMAGE):$(VERSION)
+	@echo "Sandbox runtime Docker image pushed successfully: $(SANDBOX_RUNTIME_IMAGE):$(VERSION)"
+
 # Build all images
-build-all: build-web build-api
+build-all: build-web build-api build-sandbox-runtime
 
 # Push all images
-push-all: push-web push-api
+push-all: push-web push-api push-sandbox-runtime
 
 build-push-api: build-api push-api
 build-push-web: build-web push-web
+build-push-sandbox-runtime: build-sandbox-runtime push-sandbox-runtime
 
 # Build and push all images
 build-push-all: build-all push-all
@@ -206,9 +220,10 @@ help:
 	@echo "Docker Build Targets:"
 	@echo "  make build-web      - Build web Docker image"
 	@echo "  make build-api      - Build API Docker image"
+	@echo "  make build-sandbox-runtime - Build sandbox runtime Docker image"
 	@echo "  make build-all      - Build all Docker images"
 	@echo "  make push-all       - Push all Docker images"
 	@echo "  make build-push-all - Build and push all Docker images"
 
 # Phony targets
-.PHONY: build-web build-api push-web push-api build-all push-all build-push-all dev-setup prepare-docker prepare-web prepare-api dev-clean help format check lint api-contract-lint type-check test test-all
+.PHONY: build-web build-api build-sandbox-runtime push-web push-api push-sandbox-runtime build-all push-all build-push-all build-push-sandbox-runtime dev-setup prepare-docker prepare-web prepare-api dev-clean help format check lint api-contract-lint type-check test test-all

README.md

@@ -15,7 +15,7 @@
     <a href="https://discord.gg/FngNHpbcY7" target="_blank">
         <img src="https://img.shields.io/discord/1082486657678311454?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb"
             alt="chat on Discord"></a>
-    <a href="https://reddit.com/r/difyai" target="_blank">  
+    <a href="https://reddit.com/r/difyai" target="_blank">
         <img src="https://img.shields.io/reddit/subreddit-subscribers/difyai?style=plastic&logo=reddit&label=r%2Fdifyai&labelColor=white"
             alt="join Reddit"></a>
     <a href="https://twitter.com/intent/follow?screen_name=dify_ai" target="_blank">
@@ -125,8 +125,6 @@ All of Dify's offerings come with corresponding APIs, so you could effortlessly
 - **Dify for enterprise / organizations<br/>**
   We provide additional enterprise-centric features. [Send us an email](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) to discuss your enterprise needs. <br/>
 
-  > For startups and small businesses using AWS, check out [Dify Premium on AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-t22mebxzwjhu6) and deploy it to your own AWS VPC with one click. It's an affordable AMI offering with the option to create apps with custom logo and branding.
-
 ## Staying ahead
 
 Star Dify on GitHub and be instantly notified of new releases.
@@ -209,9 +207,16 @@ At the same time, please consider supporting Dify by sharing it on social media
   <img src="https://contrib.rocks/image?repo=langgenius/dify" />
 </a>
 
-## Star history
+## Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=langgenius/dify&type=Date)](https://star-history.com/#langgenius/dify&Date)
+<!-- GitHub token name: star-history -->
+<a href="https://www.star-history.com/?repos=langgenius%2Fdify&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=langgenius/dify&type=date&theme=dark&legend=top-left&sealed_token=p-SWD-UXZEDc5a2d0EMfgMmyCwVyRlSof0Qox68v7k4PvQPKRlCx0jDIlNztw7mbA6DEn96R50DojO9pCi5LQUlDBAoIhRswt8-GuC8K3rZQ3naJUXbuHqR_oItIW2F0NNM-7npevzw5SXp7L5mwixgqJncAvAGzuGq5zmhQfiDRSW_Jd6y8TQCZMJbt" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=langgenius/dify&type=date&legend=top-left&sealed_token=p-SWD-UXZEDc5a2d0EMfgMmyCwVyRlSof0Qox68v7k4PvQPKRlCx0jDIlNztw7mbA6DEn96R50DojO9pCi5LQUlDBAoIhRswt8-GuC8K3rZQ3naJUXbuHqR_oItIW2F0NNM-7npevzw5SXp7L5mwixgqJncAvAGzuGq5zmhQfiDRSW_Jd6y8TQCZMJbt" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=langgenius/dify&type=date&legend=top-left&sealed_token=p-SWD-UXZEDc5a2d0EMfgMmyCwVyRlSof0Qox68v7k4PvQPKRlCx0jDIlNztw7mbA6DEn96R50DojO9pCi5LQUlDBAoIhRswt8-GuC8K3rZQ3naJUXbuHqR_oItIW2F0NNM-7npevzw5SXp7L5mwixgqJncAvAGzuGq5zmhQfiDRSW_Jd6y8TQCZMJbt" />
+ </picture>
+</a>
 
 ## Security disclosure
 

api/.env.example

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

api/AGENTS.md

@@ -109,6 +109,18 @@ class Example:
 - Reuse existing helpers in `core/`, `services/`, and `libs/` before creating new abstractions.
 - Optimise for observability: deterministic control flow, clear logging, actionable errors.
 
+### Owner-Bound Resource References
+
+- Resolve and validate the outer owner before binding a nested resource ID.
+- For stable single-parent chains, use immutable nested `NamedTuple` refs.
+- Root refs carry tenant plus root ID; child refs carry the parent ref.
+- In production, construct refs through the domain ref service.
+- Python allowing direct construction does not grant authorization.
+- Scope every consuming query with complete owner predicates; refs are not security tokens.
+- Keep polymorphic owners flat until explicit nominal owner types exist.
+- Do not add generic ref bases or compatibility fields only for uniformity.
+- Reconstruct internal refs from validated database state after payload or async boundaries.
+
 ### Logging & Errors
 
 - Never use `print`; use a module-level logger:

api/app.py

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

api/app_factory.py

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

api/clients/agent_backend/client.py

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

api/clients/agent_backend/errors.py

@@ -54,8 +54,21 @@ class AgentBackendRunFailedError(AgentBackendError):
 
     run_id: str
     detail: Any
+    reason: str | None
+    source_event_id: str | None
 
-    def __init__(self, run_id: str, detail: Any) -> None:
+    def __init__(
+        self,
+        run_id: str,
+        detail: Any,
+        *,
+        message: str | None = None,
+        reason: str | None = None,
+        source_event_id: str | None = None,
+    ) -> None:
         self.run_id = run_id
         self.detail = detail
-        super().__init__(f"Agent backend run failed: {run_id}")
+        self.reason = reason
+        self.source_event_id = source_event_id
+        display_message = message or f"Agent backend run failed: {run_id}"
+        super().__init__(f"{display_message} (agent_run_id={run_id})")

api/clients/agent_backend/factory.py

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

api/clients/agent_backend/fake_client.py

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

api/commands/__init__.py

@@ -10,6 +10,7 @@ from .data_migration import (
     import_migration_data,
     migration_data_wizard,
 )
+from .knowledge_fs import knowledge_fs_control_space
 from .plugin import (
     backfill_plugin_auto_upgrade,
     extract_plugins,
@@ -26,6 +27,7 @@ from .rbac import migrate_dataset_permissions_to_rbac, migrate_member_roles_to_r
 from .retention import (
     archive_workflow_runs,
     archive_workflow_runs_plan,
+    backfill_workflow_run_archive_bundles,
     clean_expired_messages,
     clean_workflow_runs,
     cleanup_orphaned_draft_variables,
@@ -54,6 +56,7 @@ __all__ = [
     "archive_workflow_runs",
     "archive_workflow_runs_plan",
     "backfill_plugin_auto_upgrade",
+    "backfill_workflow_run_archive_bundles",
     "clean_expired_messages",
     "clean_workflow_runs",
     "cleanup_orphaned_draft_variables",
@@ -73,6 +76,7 @@ __all__ = [
     "import_migration_data",
     "install_plugins",
     "install_rag_pipeline_plugins",
+    "knowledge_fs_control_space",
     "legacy_model_types",
     "migrate_annotation_vector_database",
     "migrate_data_for_plugin",

api/commands/knowledge_fs.py

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

api/commands/plugin.py

@@ -9,6 +9,7 @@ from sqlalchemy import delete, func, select
 from sqlalchemy.engine import CursorResult
 
 from configs import dify_config
+from core.db.session_factory import session_factory
 from core.helper import encrypter
 from core.plugin.entities.plugin_daemon import CredentialType
 from core.plugin.impl.plugin import PluginInstaller
@@ -578,9 +579,6 @@ def install_rag_pipeline_plugins(input_file, output_file, workers):
     """
     click.echo(click.style("Installing rag pipeline plugins", fg="yellow"))
     plugin_migration = PluginMigration()
-    plugin_migration.install_rag_pipeline_plugins(
-        input_file,
-        output_file,
-        workers,
-    )
+    with session_factory.create_session() as session:
+        plugin_migration.install_rag_pipeline_plugins(input_file, output_file, workers, session=session)
     click.echo(click.style("Installing rag pipeline plugins successfully", fg="green"))

api/commands/rbac.py

@@ -212,9 +212,7 @@ def migrate_member_roles_to_rbac(
                 account_id=owner_account_id,
                 member_account_ids=[account_id for account_id, _ in batch],
             )
-            current_roles_by_account_id = {
-                item.account_id: {str(role.id) for role in item.roles} for item in current_roles
-            }
+            current_roles_by_account_id = {item.account_id: {role.id for role in item.roles} for item in current_roles}
 
         replace_jobs: list[tuple[str, str]] = []
         for member_account_id, legacy_role in batch:
@@ -468,7 +466,9 @@ def migrate_dataset_permissions_to_rbac(
                                         "account_id": operator_account_id,
                                         "dataset_id": current_dataset_id,
                                         "target_account_id": member_account_id,
-                                        "payload": replace_user_access_policies_payload.model_dump(mode="json"),
+                                        "payload": replace_user_access_policies_payload.model_dump(
+                                            mode="json", exclude_unset=True
+                                        ),
                                     },
                                 },
                             }

api/commands/retention.py

@@ -1,10 +1,14 @@
 import datetime
 import logging
+import re
 import time
+import uuid
+from collections.abc import Callable
 from typing import TypedDict
 
 import click
 import sqlalchemy as sa
+from sqlalchemy.orm import Session, sessionmaker
 
 from extensions.ext_database import db
 from libs.datetime_utils import naive_utc_now
@@ -12,12 +16,14 @@ 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.db_retry import run_with_db_retry
 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")
+_TARGET_MONTH_PATTERN = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$")
 
 
 class WorkflowRunArchivePlanRow(TypedDict):
@@ -35,6 +41,12 @@ class WorkflowRunArchiveTenantPlan(TypedDict):
     unpaid_tenant_ids: list[str]
 
 
+class WorkflowRunArchivePrefixStats(TypedDict):
+    tenant_ids: list[str]
+    workflow_runs: int
+    workflow_node_executions: int
+
+
 def _normalize_utc_datetime(value: datetime.datetime) -> datetime.datetime:
     if value.tzinfo is None:
         return value.replace(tzinfo=datetime.UTC)
@@ -56,7 +68,39 @@ def _parse_tenant_prefixes(prefixes: str | None) -> list[str]:
     return sorted(set(parsed))
 
 
+def _parse_comma_separated_ids(raw_ids: str | None, *, param_name: str) -> list[str] | None:
+    """Keep an omitted scope unset while rejecting an explicitly empty scope."""
+    if raw_ids is None:
+        return None
+    parsed = sorted({raw_id.strip() for raw_id in raw_ids.split(",") if raw_id.strip()})
+    if not parsed:
+        raise click.BadParameter(f"{param_name} must not be empty")
+    return parsed
+
+
+def _parse_archive_target_month(target_month: str) -> tuple[int, int]:
+    """Validate the V2 catalog month selector and return its numeric components."""
+    if not _TARGET_MONTH_PATTERN.fullmatch(target_month):
+        raise click.BadParameter("target-month must use YYYY-MM format", param_hint="--target-month")
+    year_text, month_text = target_month.split("-", maxsplit=1)
+    return int(year_text), int(month_text)
+
+
+def _parse_archive_catalog_cursor(after_catalog_id: str | None) -> str | None:
+    """Normalize the exclusive V2 catalog keyset cursor when one is provided."""
+    if after_catalog_id is None:
+        return None
+    try:
+        return str(uuid.UUID(after_catalog_id))
+    except ValueError as exc:
+        raise click.BadParameter(
+            "after-catalog-id must be a UUID returned by the same V2 operation and scope",
+            param_hint="--after-catalog-id",
+        ) from exc
+
+
 def _get_archive_candidate_tenant_ids_by_prefix(
+    session: Session,
     prefix: str,
     *,
     start_from: datetime.datetime | None,
@@ -75,7 +119,7 @@ def _get_archive_candidate_tenant_ids_by_prefix(
     if start_from is not None:
         conditions.append(WorkflowRun.created_at >= start_from)
 
-    tenant_ids = db.session.scalars(
+    tenant_ids = session.scalars(
         sa.select(WorkflowRun.tenant_id).where(*conditions).distinct().order_by(WorkflowRun.tenant_id)
     ).all()
     return list(tenant_ids)
@@ -102,8 +146,80 @@ def _filter_paid_workflow_archive_tenant_ids(tenant_ids: list[str]) -> tuple[lis
     return paid_tenant_ids, unpaid_tenant_ids
 
 
+def _run_archive_command_db_retry[T](operation_name: str, operation: Callable[[], T]) -> T:
+    return run_with_db_retry(operation_name, operation, logger=logger)
+
+
+def _get_archive_candidate_tenant_ids_with_retry(
+    session_maker: sessionmaker[Session],
+    prefix: str,
+    *,
+    start_from: datetime.datetime | None,
+    end_before: datetime.datetime,
+) -> list[str]:
+    def fetch_tenant_ids() -> list[str]:
+        with session_maker() as session:
+            return _get_archive_candidate_tenant_ids_by_prefix(
+                session,
+                prefix,
+                start_from=start_from,
+                end_before=end_before,
+            )
+
+    return _run_archive_command_db_retry(f"workflow archive tenant resolve for prefix {prefix}", fetch_tenant_ids)
+
+
+def _get_archive_plan_prefix_stats(
+    session_maker: sessionmaker[Session],
+    prefix: str,
+    *,
+    start_from: datetime.datetime | None,
+    end_before: datetime.datetime,
+) -> WorkflowRunArchivePrefixStats:
+    from graphon.enums import WorkflowExecutionStatus
+    from models.workflow import WorkflowNodeExecutionModel, WorkflowRun
+    from services.retention.workflow_run.archive_paid_plan_workflow_run import WorkflowRunArchiver
+
+    def fetch_prefix_stats() -> WorkflowRunArchivePrefixStats:
+        with session_maker() as session:
+            tenant_ids = _get_archive_candidate_tenant_ids_by_prefix(
+                session,
+                prefix,
+                start_from=start_from,
+                end_before=end_before,
+            )
+            run_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:
+                run_conditions.append(WorkflowRun.created_at >= start_from)
+            workflow_runs = (
+                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 = (
+                session.scalar(
+                    sa.select(sa.func.count())
+                    .select_from(WorkflowNodeExecutionModel)
+                    .join(candidate_runs, WorkflowNodeExecutionModel.workflow_run_id == candidate_runs.c.id)
+                )
+                or 0
+            )
+            return WorkflowRunArchivePrefixStats(
+                tenant_ids=tenant_ids,
+                workflow_runs=workflow_runs,
+                workflow_node_executions=workflow_node_executions,
+            )
+
+    return _run_archive_command_db_retry(f"workflow archive plan for prefix {prefix}", fetch_prefix_stats)
+
+
 def _resolve_archive_tenant_ids_from_plan(
     *,
+    session_maker: sessionmaker[Session],
     tenant_ids: str | None,
     tenant_prefixes: list[str],
     start_from: datetime.datetime | None,
@@ -122,7 +238,8 @@ def _resolve_archive_tenant_ids_from_plan(
         requested_tenant_ids = []
         for prefix in tenant_prefixes:
             requested_tenant_ids.extend(
-                _get_archive_candidate_tenant_ids_by_prefix(
+                _get_archive_candidate_tenant_ids_with_retry(
+                    session_maker,
                     prefix,
                     start_from=start_from,
                     end_before=end_before,
@@ -143,6 +260,21 @@ def _resolve_archive_tenant_ids_from_plan(
     )
 
 
+def _safe_remove_scoped_session(context: str) -> None:
+    try:
+        db.session.remove()
+    except Exception:
+        logger.warning("Ignoring DB scoped-session cleanup error after %s", context, exc_info=True)
+        try:
+            db.session.registry.clear()
+        except Exception:
+            logger.warning("Ignoring DB scoped-session registry cleanup error after %s", context, exc_info=True)
+        try:
+            db.engine.dispose()
+        except Exception:
+            logger.warning("Ignoring DB engine dispose error after %s", context, exc_info=True)
+
+
 def _resolve_archive_time_range(
     *,
     before_days: int,
@@ -349,10 +481,6 @@ def archive_workflow_runs_plan(
     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,
@@ -364,37 +492,25 @@ def archive_workflow_runs_plan(
     if include_archived:
         click.echo(click.style("--include-archived is a no-op for V2 bundle archive plans.", fg="yellow"))
 
+    session_maker = sessionmaker(bind=db.engine, expire_on_commit=False)
     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,
-        )
+        try:
+            prefix_stats = _get_archive_plan_prefix_stats(
+                session_maker,
+                prefix,
+                start_from=start_from,
+                end_before=plan_end_before,
+            )
+        except Exception as exc:
+            logger.exception("Failed to build workflow archive plan for prefix %s", prefix)
+            raise click.ClickException(f"Failed to build workflow archive plan for prefix {prefix}.") from exc
+        tenant_ids = prefix_stats["tenant_ids"]
+        workflow_runs = prefix_stats["workflow_runs"]
+        workflow_node_executions = prefix_stats["workflow_node_executions"]
         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,
@@ -574,17 +690,18 @@ def archive_workflow_runs(
             )
         )
 
+    session_maker = sessionmaker(bind=db.engine, expire_on_commit=False)
     try:
         tenant_plan = _resolve_archive_tenant_ids_from_plan(
+            session_maker=session_maker,
             tenant_ids=tenant_ids,
             tenant_prefixes=parsed_tenant_prefixes,
             start_from=start_from,
             end_before=plan_end_before,
         )
-    except Exception:
+    except Exception as exc:
         logger.exception("Failed to resolve workflow archive tenant plan")
-        click.echo(click.style("Failed to resolve workflow archive tenant plan.", fg="red"))
-        return
+        raise click.ClickException("Failed to resolve workflow archive tenant plan.") from exc
 
     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
@@ -616,7 +733,10 @@ def archive_workflow_runs(
         dry_run=dry_run,
         delete_after_archive=delete_after_archive,
     )
-    summary = archiver.run()
+    try:
+        summary = archiver.run()
+    finally:
+        _safe_remove_scoped_session("archive workflow run command")
     click.echo(
         click.style(
             f"Summary: processed={summary.total_runs_processed}, archived={summary.runs_archived}, "
@@ -639,9 +759,87 @@ def archive_workflow_runs(
     )
 
 
-def _echo_bundle_archive_operation_summary(summary) -> None:
+@click.command(
+    "backfill-workflow-run-archive-bundles",
+    help="Backfill workflow-run archive bundle DB index from object-storage manifests.",
+)
+@click.option("--tenant-ids", default=None, help="Optional comma-separated tenant IDs.")
+@click.option(
+    "--tenant-prefixes",
+    default=None,
+    help="Optional comma-separated tenant ID first hex digits, e.g. 0,1,a,f.",
+)
+@click.option("--year", default=None, type=click.IntRange(min=1, max=9999), help="Optional archive year filter.")
+@click.option("--month", default=None, type=click.IntRange(min=1, max=12), help="Optional archive month filter.")
+@click.option("--limit", default=None, type=click.IntRange(min=1), help="Maximum number of manifests to process.")
+@click.option("--dry-run", is_flag=True, help="Preview without writing workflow_run_archive_bundles.")
+def backfill_workflow_run_archive_bundles(
+    tenant_ids: str | None,
+    tenant_prefixes: str | None,
+    year: int | None,
+    month: int | None,
+    limit: int | None,
+    dry_run: bool,
+) -> None:
+    """
+    Reconcile `workflow_run_archive_bundles` from V2 archive manifests.
+
+    This command is meant for bootstrapping the listing/download index after deploy or repairing index drift. The R2
+    manifests remain the source of truth; this command only mirrors their query metadata into the database.
+    """
+    from services.retention.workflow_run.archive_bundle_index import WorkflowRunArchiveBundleIndexBackfill
+
+    if tenant_ids and tenant_prefixes:
+        raise click.UsageError("Choose either --tenant-ids or --tenant-prefixes, not both.")
+    if month is not None and year is None:
+        raise click.UsageError("--month must be used with --year.")
+
+    parsed_tenant_ids = _parse_comma_separated_ids(tenant_ids, param_name="tenant-ids")
+    parsed_tenant_prefixes = _parse_tenant_prefixes(tenant_prefixes)
+    if not parsed_tenant_ids and not parsed_tenant_prefixes:
+        click.echo(
+            click.style(
+                "No tenant scope supplied; scanning the full workflow-runs/v2/ archive prefix.",
+                fg="yellow",
+            )
+        )
+
+    started_at = datetime.datetime.now(datetime.UTC)
+    click.echo(click.style(f"Starting archive bundle index backfill at {started_at.isoformat()}.", fg="white"))
+
+    backfill = WorkflowRunArchiveBundleIndexBackfill()
+    summary = backfill.run(
+        tenant_ids=parsed_tenant_ids,
+        tenant_prefixes=parsed_tenant_prefixes or None,
+        year=year,
+        month=month,
+        limit=limit,
+        dry_run=dry_run,
+    )
+    status = "completed with failures" if summary.bundles_failed else "completed successfully"
+    fg = "red" if summary.bundles_failed else "green"
+    action = "would_upsert" if dry_run else "upserted"
+    action_count = summary.bundles_processed if dry_run else summary.bundles_upserted
+    click.echo(
+        click.style(
+            f"Backfill {status}. manifests_found={summary.manifests_found} "
+            f"bundles_processed={summary.bundles_processed} {action}={action_count} "
+            f"bundles_failed={summary.bundles_failed} runs={summary.workflow_run_count} rows={summary.row_count} "
+            f"archive_bytes={summary.archive_bytes} duration={summary.elapsed_time:.2f}s",
+            fg=fg,
+        )
+    )
+    for error in summary.errors[:10]:
+        click.echo(click.style(f"  failed {error}", fg="red"))
+    if len(summary.errors) > 10:
+        click.echo(click.style(f"  ... and {len(summary.errors) - 10} more failures", fg="red"))
+
+
+def _echo_bundle_archive_operation_summary(summary, *, dry_run: bool) -> None:
     status = "completed successfully" if summary.bundles_failed == 0 else "completed with failures"
     fg = "green" if summary.bundles_failed == 0 else "red"
+    cursor_label = "preview_next_catalog_id" if dry_run else "next_catalog_id"
+    cursor_value = summary.preview_next_catalog_id if dry_run else summary.next_catalog_id
     click.echo(
         click.style(
             f"{summary.operation} {status}. "
@@ -650,10 +848,12 @@ def _echo_bundle_archive_operation_summary(summary) -> None:
             f"archive_bytes={summary.archive_bytes} duration={summary.elapsed_time:.2f}s "
             f"validation_time={summary.validation_time:.2f}s "
             f"runs_per_second={summary.runs_per_second:.2f} rows_per_second={summary.rows_per_second:.2f} "
-            f"bytes_per_second={summary.bytes_per_second:.2f}",
+            f"bytes_per_second={summary.bytes_per_second:.2f} {cursor_label}={cursor_value or 'none'}",
             fg=fg,
         )
     )
+    if dry_run:
+        click.echo(click.style("Dry-run cursor is preview-only; do not persist it for a destructive run.", fg="yellow"))
     click.echo(click.style("table,row_count", fg="white"))
     for table_name in [
         "workflow_runs",
@@ -671,7 +871,8 @@ def _echo_bundle_archive_operation_summary(summary) -> None:
                 click.style(
                     f"  bundle={result.bundle_id} tenant={result.tenant_id} runs={result.run_count} "
                     f"rows={result.row_count} archive_bytes={result.archive_bytes} "
-                    f"time={result.elapsed_time:.2f}s validation={result.validation_time:.2f}s",
+                    f"catalog_id={result.catalog_id} time={result.elapsed_time:.2f}s "
+                    f"validation={result.validation_time:.2f}s",
                     fg="white",
                 )
             )
@@ -679,7 +880,7 @@ def _echo_bundle_archive_operation_summary(summary) -> None:
             click.echo(
                 click.style(
                     f"  failed bundle={result.bundle_id} tenant={result.tenant_id} "
-                    f"object_prefix={result.object_prefix} error={result.error}",
+                    f"catalog_id={result.catalog_id} object_prefix={result.object_prefix} error={result.error}",
                     fg="red",
                 )
             )
@@ -696,25 +897,24 @@ def _echo_bundle_archive_operation_summary(summary) -> None:
 )
 @click.option("--run-id", required=False, help="Workflow run ID to restore.")
 @click.option(
-    "--start-from",
-    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    "--target-month",
+    metavar="YYYY-MM",
     default=None,
-    help="Optional lower bound (inclusive) for created_at; must be paired with --end-before.",
+    help="V2 catalog month to restore; required unless --run-id is used.",
 )
 @click.option(
-    "--end-before",
-    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    "--after-catalog-id",
     default=None,
-    help="Optional upper bound (exclusive) for created_at; must be paired with --start-from.",
+    help="Exclusive V2 cursor from the same restore month and tenant scope.",
 )
 @click.option("--workers", default=1, show_default=True, type=int, help="V1 --run-id compatibility only.")
-@click.option("--limit", type=int, default=100, show_default=True, help="Maximum number of V2 bundles to restore.")
+@click.option("--limit", type=click.IntRange(min=1), default=100, show_default=True, help="Maximum V2 catalog rows.")
 @click.option("--dry-run", is_flag=True, help="Preview without restoring.")
 def restore_workflow_runs(
     tenant_ids: str | None,
     run_id: str | None,
-    start_from: datetime.datetime | None,
-    end_before: datetime.datetime | None,
+    target_month: str | None,
+    after_catalog_id: str | None,
     workers: int,
     limit: int,
     dry_run: bool,
@@ -734,23 +934,20 @@ def restore_workflow_runs(
     from services.retention.workflow_run.bundle_archive_maintenance import WorkflowRunBundleArchiveMaintenance
     from services.retention.workflow_run.restore_archived_workflow_run import WorkflowRunRestore
 
-    parsed_tenant_ids = None
-    if tenant_ids:
-        parsed_tenant_ids = [tid.strip() for tid in tenant_ids.split(",") if tid.strip()]
-        if not parsed_tenant_ids:
-            raise click.BadParameter("tenant-ids must not be empty")
+    parsed_tenant_ids = _parse_comma_separated_ids(tenant_ids, param_name="tenant-ids")
 
-    if (start_from is None) ^ (end_before is None):
-        raise click.UsageError("--start-from and --end-before must be provided together.")
-    if run_id is None and (start_from is None or end_before is None):
-        raise click.UsageError("--start-from and --end-before are required for batch restore.")
     if workers < 1:
         raise click.BadParameter("workers must be at least 1")
+    if run_id is not None and (target_month is not None or after_catalog_id is not None):
+        raise click.UsageError("--target-month and --after-catalog-id are only valid for V2 batch restore.")
+    if run_id is None and target_month is None:
+        raise click.UsageError("--target-month is required for V2 batch restore.")
 
     start_time = datetime.datetime.now(datetime.UTC)
+    target_desc = f"workflow run {run_id}" if run_id else f"workflow archive catalog month {target_month}"
     click.echo(
         click.style(
-            f"Starting restore of workflow run {run_id} at {start_time.isoformat()}.",
+            f"Starting restore of {target_desc} at {start_time.isoformat()}.",
             fg="white",
         )
     )
@@ -784,17 +981,20 @@ def restore_workflow_runs(
         click.echo(
             click.style("--workers is ignored for V2 bundle restore; bundles are processed serially.", fg="yellow")
         )
-    assert start_from is not None
-    assert end_before is not None
+    assert target_month is not None
+    target_year, target_month_number = _parse_archive_target_month(target_month)
+    catalog_cursor = _parse_archive_catalog_cursor(after_catalog_id)
     bundle_restorer = WorkflowRunBundleArchiveMaintenance(dry_run=dry_run, strict_content_validation=True)
     summary = bundle_restorer.restore_batch(
         tenant_ids=parsed_tenant_ids,
-        start_date=start_from,
-        end_date=end_before,
+        target_year=target_year,
+        target_month=target_month_number,
+        after_catalog_id=catalog_cursor,
         limit=limit,
     )
-    _echo_bundle_archive_operation_summary(summary)
-    return
+    _echo_bundle_archive_operation_summary(summary, dry_run=dry_run)
+    if summary.bundles_failed:
+        raise click.exceptions.Exit(1)
 
 
 @click.command(
@@ -808,23 +1008,41 @@ def restore_workflow_runs(
 )
 @click.option("--run-id", required=False, help="Workflow run ID to delete.")
 @click.option(
-    "--start-from",
-    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    "--target-month",
+    metavar="YYYY-MM",
     default=None,
-    help="Optional lower bound (inclusive) for created_at; must be paired with --end-before.",
+    help="V2 catalog month to delete; required unless --run-id is used.",
 )
 @click.option(
-    "--end-before",
-    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    "--after-catalog-id",
     default=None,
-    help="Optional upper bound (exclusive) for created_at; must be paired with --start-from.",
+    help="Exclusive V2 cursor from the same delete month and tenant scope.",
+)
+@click.option(
+    "--run-shard-index",
+    default=None,
+    type=click.IntRange(min=0),
+    help="Zero-based archive shard index. Must be paired with --run-shard-total.",
+)
+@click.option(
+    "--run-shard-total",
+    default=None,
+    type=click.IntRange(min=1, max=16),
+    help="Total archive shard count. Must be paired with --run-shard-index.",
+)
+@click.option("--all-pages", is_flag=True, help="Process catalog pages until an empty page is reached.")
+@click.option(
+    "--limit",
+    type=click.IntRange(min=1),
+    default=100,
+    show_default=True,
+    help="Maximum V2 catalog rows per page.",
 )
-@click.option("--limit", type=int, default=100, show_default=True, help="Maximum number of V2 bundles to delete.")
 @click.option("--dry-run", is_flag=True, help="Preview without deleting.")
 @click.option(
     "--skip-bad-archives",
     is_flag=True,
-    help="Continue batch deletion when one archive object fails validation.",
+    help="V1 --run-id only: continue when one archive object fails validation.",
 )
 @click.option(
     "--restore-sample-interval",
@@ -836,8 +1054,11 @@ def restore_workflow_runs(
 def delete_archived_workflow_runs(
     tenant_ids: str | None,
     run_id: str | None,
-    start_from: datetime.datetime | None,
-    end_before: datetime.datetime | None,
+    target_month: str | None,
+    after_catalog_id: str | None,
+    run_shard_index: int | None,
+    run_shard_total: int | None,
+    all_pages: bool,
     limit: int,
     dry_run: bool,
     skip_bad_archives: bool,
@@ -847,26 +1068,38 @@ def delete_archived_workflow_runs(
     Delete archived workflow runs from the database.
 
     Batch delete uses V2 bundle metadata and validates object existence, manifest schema, object size, checksum, row
-    counts, and source/archive content checksums before deleting source rows. `--run-id` keeps the V1 per-run path.
+    counts, and source/archive content checksums before deleting source rows. Parallel workers may select one exact
+    archive shard; all-pages mode keeps only the current bounded page in memory. `--run-id` keeps the V1 per-run path.
     """
     from services.retention.workflow_run.bundle_archive_maintenance import WorkflowRunBundleArchiveMaintenance
     from services.retention.workflow_run.delete_archived_workflow_run import ArchivedWorkflowRunDeletion
 
-    parsed_tenant_ids = None
-    if tenant_ids:
-        parsed_tenant_ids = [tid.strip() for tid in tenant_ids.split(",") if tid.strip()]
-        if not parsed_tenant_ids:
-            raise click.BadParameter("tenant-ids must not be empty")
+    parsed_tenant_ids = _parse_comma_separated_ids(tenant_ids, param_name="tenant-ids")
 
-    if (start_from is None) ^ (end_before is None):
-        raise click.UsageError("--start-from and --end-before must be provided together.")
-    if run_id is None and (start_from is None or end_before is None):
-        raise click.UsageError("--start-from and --end-before are required for batch delete.")
     if restore_sample_interval < 0:
         raise click.BadParameter("restore-sample-interval must be >= 0")
+    if run_id is not None and (
+        target_month is not None
+        or after_catalog_id is not None
+        or run_shard_index is not None
+        or run_shard_total is not None
+        or all_pages
+    ):
+        raise click.UsageError(
+            "--target-month, --after-catalog-id, --run-shard-index, --run-shard-total, and --all-pages "
+            "are only valid for V2 batch delete."
+        )
+    if run_id is None and target_month is None:
+        raise click.UsageError("--target-month is required for V2 batch delete.")
+    if run_id is None and skip_bad_archives:
+        raise click.UsageError("--skip-bad-archives is not supported for V2 catalog batches; they fail fast.")
+    if (run_shard_index is None) ^ (run_shard_total is None):
+        raise click.UsageError("--run-shard-index and --run-shard-total must be provided together.")
+    if run_shard_index is not None and run_shard_total is not None and run_shard_index >= run_shard_total:
+        raise click.UsageError("--run-shard-index must be less than --run-shard-total.")
 
     start_time = datetime.datetime.now(datetime.UTC)
-    target_desc = f"workflow run {run_id}" if run_id else "workflow runs"
+    target_desc = f"workflow run {run_id}" if run_id else f"workflow archive catalog month {target_month}"
     click.echo(
         click.style(
             f"Starting delete of {target_desc} at {start_time.isoformat()}.",
@@ -939,20 +1172,104 @@ def delete_archived_workflow_runs(
 
     if restore_sample_interval:
         click.echo(click.style("--restore-sample-interval is ignored for V2 bundle delete.", fg="yellow"))
-    assert start_from is not None
-    assert end_before is not None
-    bundle_deleter = WorkflowRunBundleArchiveMaintenance(
-        dry_run=dry_run,
-        strict_content_validation=True,
-        stop_on_error=not skip_bad_archives,
+    assert target_month is not None
+    target_year, target_month_number = _parse_archive_target_month(target_month)
+    catalog_cursor = _parse_archive_catalog_cursor(after_catalog_id)
+    shard = (
+        f"{run_shard_index:02d}-of-{run_shard_total:02d}"
+        if run_shard_index is not None and run_shard_total is not None
+        else None
     )
-    summary = bundle_deleter.delete_batch(
-        tenant_ids=parsed_tenant_ids,
-        start_date=start_from,
-        end_date=end_before,
-        limit=limit,
-    )
-    _echo_bundle_archive_operation_summary(summary)
+    bundle_deleter = WorkflowRunBundleArchiveMaintenance(dry_run=dry_run, strict_content_validation=True)
+    if run_shard_total is not None:
+        try:
+            bundle_deleter.validate_catalog_shards(
+                target_year=target_year,
+                target_month=target_month_number,
+                shard_total=run_shard_total,
+                tenant_ids=parsed_tenant_ids,
+            )
+        except ValueError as exc:
+            logger.exception(
+                "Archive catalog shard preflight failed: target_month=%s shard=%s",
+                target_month,
+                shard,
+            )
+            raise click.ClickException(
+                f"Archive catalog shard preflight failed for target_month={target_month} shard={shard}: {exc}"
+            ) from exc
+
+    initial_catalog_cursor = catalog_cursor
+    pages_processed = 0
+    bundles_succeeded = 0
+    runs_processed = 0
+    rows_processed = 0
+    archive_bytes = 0
+    while True:
+        summary = bundle_deleter.delete_batch(
+            tenant_ids=parsed_tenant_ids,
+            target_year=target_year,
+            target_month=target_month_number,
+            after_catalog_id=catalog_cursor,
+            limit=limit,
+            shard=shard,
+        )
+        _echo_bundle_archive_operation_summary(summary, dry_run=dry_run)
+        if summary.bundles_failed:
+            failed_result = next((result for result in summary.results if not result.success), None)
+            failed_catalog_id = failed_result.catalog_id if failed_result is not None else "unknown"
+            page_resume_cursor = summary.preview_next_catalog_id if dry_run else summary.next_catalog_id
+            resume_cursor = page_resume_cursor or catalog_cursor
+            if dry_run:
+                cursor_details = (
+                    f"preview_after_catalog_id={resume_cursor or 'none'} "
+                    f"destructive_retry_after_catalog_id={initial_catalog_cursor or 'none'}"
+                )
+            else:
+                cursor_details = f"resume_after_catalog_id={resume_cursor or 'none'}"
+            click.echo(
+                click.style(
+                    f"Delete stopped: target_month={target_month} shard={shard or 'all'} "
+                    f"failed_catalog_id={failed_catalog_id} "
+                    f"{cursor_details}",
+                    fg="red",
+                )
+            )
+            raise click.exceptions.Exit(1)
+
+        if not all_pages:
+            break
+        if summary.bundles_processed == 0:
+            break
+
+        pages_processed += 1
+        bundles_succeeded += summary.bundles_succeeded
+        runs_processed += summary.runs_processed
+        rows_processed += summary.rows_processed
+        archive_bytes += summary.archive_bytes
+        next_catalog_id = summary.preview_next_catalog_id if dry_run else summary.next_catalog_id
+        if next_catalog_id is None or (catalog_cursor is not None and next_catalog_id <= catalog_cursor):
+            click.echo(
+                click.style(
+                    f"Delete cursor did not advance: target_month={target_month} shard={shard or 'all'} "
+                    f"after_catalog_id={catalog_cursor or 'none'} next_catalog_id={next_catalog_id or 'none'}",
+                    fg="red",
+                )
+            )
+            raise click.exceptions.Exit(1)
+        catalog_cursor = next_catalog_id
+
+    if all_pages:
+        final_cursor_label = "preview_final_catalog_id" if dry_run else "final_catalog_id"
+        click.echo(
+            click.style(
+                f"Delete all-pages completed successfully. target_month={target_month} shard={shard or 'all'} "
+                f"pages={pages_processed} bundles_success={bundles_succeeded} runs={runs_processed} "
+                f"rows={rows_processed} archive_bytes={archive_bytes} "
+                f"{final_cursor_label}={catalog_cursor or 'none'}",
+                fg="green",
+            )
+        )
 
 
 def _find_orphaned_draft_variables(batch_size: int = 1000) -> list[str]:

api/commands/system.py

@@ -188,23 +188,26 @@ where sites.id is null limit 1000"""
                 if app_id in failed_app_ids:
                     continue
 
+                session = db.session()
                 try:
-                    app = db.session.scalar(select(App).where(App.id == app_id))
+                    app = session.scalar(select(App).where(App.id == app_id))
                     if not app:
                         logger.info("App %s not found", app_id)
                         continue
 
-                    tenant = app.tenant
+                    tenant = session.get(Tenant, app.tenant_id)
                     if tenant:
-                        accounts = tenant.get_accounts()
+                        accounts = tenant.get_accounts(session=session)
                         if not accounts:
                             logger.info("Fix failed for app %s", app.id)
                             continue
 
                         account = accounts[0]
                         logger.info("Fixing missing site for app %s", app.id)
-                        app_was_created.send(app, account=account)
+                        app_was_created.send(app, account=account, session=session)
+                        session.commit()
                 except Exception:
+                    session.rollback()
                     failed_app_ids.append(app_id)
                     click.echo(click.style(f"Failed to fix missing site for app {app_id}", fg="red"))
                     logger.exception("Failed to fix app related site missing issue, app_id: %s", app_id)

api/commands/vector.py

@@ -1,10 +1,11 @@
 import json
+from typing import cast
 
 import click
 from flask import current_app
 from sqlalchemy import select
 from sqlalchemy.exc import SQLAlchemyError
-from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import Session, sessionmaker
 
 from configs import dify_config
 from core.rag.datasource.vdb.vector_factory import Vector
@@ -101,7 +102,8 @@ def migrate_annotation_vector_database():
                         )
                         documents.append(document)
 
-                vector = Vector(dataset, attributes=["doc_id", "annotation_id", "app_id"])
+                with Session(db.engine) as session:
+                    vector = Vector(dataset, attributes=["doc_id", "annotation_id", "app_id"], session=session)
                 click.echo(f"Migrating annotations for app: {app.id}.")
 
                 try:
@@ -176,6 +178,7 @@ def migrate_knowledge_vector_database():
         VectorType.OCEANBASE,
     }
     page = 1
+    db_session = db.session()
     while True:
         try:
             stmt = (
@@ -184,7 +187,7 @@ def migrate_knowledge_vector_database():
                 .order_by(Dataset.created_at.desc())
             )
 
-            datasets = paginate_query(stmt, page=page, per_page=50, max_per_page=50)
+            datasets = paginate_query(stmt, page=page, per_page=50, max_per_page=50, session=db_session)
             if not datasets.items:
                 break
         except SQLAlchemyError:
@@ -227,7 +230,8 @@ def migrate_knowledge_vector_database():
 
                 index_struct_dict = {"type": vector_type, "vector_store": {"class_prefix": collection_name}}
                 dataset.index_struct = json.dumps(index_struct_dict)
-                vector = Vector(dataset)
+                with Session(db.engine) as session:
+                    vector = Vector(dataset, session=session)
                 click.echo(f"Migrating dataset {dataset.id}.")
 
                 try:
@@ -274,7 +278,7 @@ def migrate_knowledge_vector_database():
                             },
                         )
                         if dataset_document.doc_form == IndexStructureType.PARENT_CHILD_INDEX:
-                            child_chunks = segment.get_child_chunks()
+                            child_chunks = segment.get_child_chunks(session=db_session)
                             if child_chunks:
                                 child_documents = []
                                 for child_chunk in child_chunks:
@@ -410,7 +414,9 @@ def old_metadata_migration():
                 .where(DatasetDocument.doc_metadata.is_not(None))
                 .order_by(DatasetDocument.created_at.desc())
             )
-            documents = paginate_query(stmt, page=page, per_page=50, max_per_page=50)
+            documents = paginate_query(
+                stmt, page=page, per_page=50, max_per_page=50, session=cast(Session, db.session())
+            )
         except SQLAlchemyError:
             raise
         if not documents:

api/configs/extra/__init__.py

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

api/configs/extra/agent_backend_config.py

@@ -1,4 +1,4 @@
-from pydantic import Field, NonNegativeFloat
+from pydantic import Field, NonNegativeFloat, NonNegativeInt, PositiveFloat
 from pydantic_settings import BaseSettings
 
 
@@ -22,14 +22,28 @@ class AgentBackendConfig(BaseSettings):
         default="success",
     )
 
+    AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS: PositiveFloat = Field(
+        description="Read timeout for one Agent backend SSE connection.",
+        default=30,
+    )
+
+    AGENT_BACKEND_STREAM_MAX_RECONNECTS: NonNegativeInt = Field(
+        description="Maximum Agent backend SSE reconnects before failing the run.",
+        default=3,
+    )
+
+    AGENT_BACKEND_RUN_TIMEOUT_SECONDS: PositiveFloat = Field(
+        description="Total deadline for one Agent backend run event stream.",
+        default=1200,
+    )
+
     AGENT_SHELL_ENABLED: bool = Field(
         description=(
             "Inject the dify.shell layer (sandboxed bash workspace) into Agent runs. "
-            "Requires the agent backend to be wired with a shellctl entrypoint; keep it "
-            "off until shellctl is deployed, otherwise every agent run that includes the "
-            "shell layer will fail."
+            "Requires the agent backend to be wired with a shellctl entrypoint before "
+            "shell-using Agent runs are executed."
         ),
-        default=False,
+        default=True,
     )
 
     AGENT_APP_TEXT_DELTA_DEBOUNCE_SECONDS: NonNegativeFloat = Field(

api/configs/extra/knowledge_fs_config.py

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

api/configs/feature/__init__.py

@@ -275,6 +275,42 @@ class PluginConfig(BaseSettings):
         default=50 * 1024 * 1024,
     )
 
+    NEW_USER_DEFAULT_PLUGIN_IDS: str = Field(
+        description="Comma-separated marketplace plugin IDs whose latest versions are installed for new users",
+        default="",
+    )
+
+    @property
+    def NEW_USER_DEFAULT_PLUGIN_ID_LIST(self) -> list[str]:
+        return [item.strip() for item in self.NEW_USER_DEFAULT_PLUGIN_IDS.split(",") if item.strip()]
+
+    NEW_USER_DEFAULT_MODELS: str = Field(
+        description=("Comma-separated default models for new users in 'model_type:provider:model' format"),
+        default="",
+    )
+
+    @property
+    def NEW_USER_DEFAULT_MODEL_LIST(self) -> list[tuple[str, str, str]]:
+        default_models: list[tuple[str, str, str]] = []
+        configured_model_types: set[str] = set()
+
+        for item in self.NEW_USER_DEFAULT_MODELS.split(","):
+            if not item.strip():
+                continue
+
+            parts = tuple(part.strip() for part in item.split(":", 2))
+            if len(parts) != 3 or not all(parts):
+                raise ValueError("NEW_USER_DEFAULT_MODELS entries must use 'model_type:provider:model' format")
+
+            model_type, provider, model = parts
+            if model_type in configured_model_types:
+                raise ValueError(f"NEW_USER_DEFAULT_MODELS contains duplicate model type: {model_type}")
+
+            configured_model_types.add(model_type)
+            default_models.append((model_type, provider, model))
+
+        return default_models
+
 
 class MarketplaceConfig(BaseSettings):
     """
@@ -363,7 +399,10 @@ class FileAccessConfig(BaseSettings):
     INTERNAL_FILES_URL: str = Field(
         description="Internal base URL for file access within Docker network,"
         " used for plugin daemon and internal service communication."
-        " Falls back to FILES_URL if not specified.",
+        " Explicit INTERNAL_FILES_URL takes precedence; otherwise SERVER_CONSOLE_API_URL is used,"
+        " then FILES_URL.",
+        validation_alias=AliasChoices("INTERNAL_FILES_URL", "SERVER_CONSOLE_API_URL"),
+        alias_priority=1,
         default="",
     )
 
@@ -781,6 +820,11 @@ class WorkflowConfig(BaseSettings):
         default=500,
     )
 
+    WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS: PositiveInt = Field(
+        description="Maximum concurrent node-builder LLM calls per workflow generation request",
+        default=6,
+    )
+
     WORKFLOW_MAX_EXECUTION_TIME: PositiveInt = Field(
         description="Maximum execution time in seconds for a single workflow",
         default=1200,

api/configs/middleware/cache/redis_config.py

@@ -153,6 +153,11 @@ class RedisConfig(BaseSettings):
         default=30,
     )
 
+    REDIS_KEEPALIVE: bool = Field(default=False, description="Keepalive for Redis connections")
+    REDIS_KEEPALIVE_IDLE: PositiveInt = Field(default=30, description="redis keepalive idle timeout")
+    REDIS_KEEPALIVE_INTERVAL: PositiveInt = Field(default=10, description="redis keepalive interval")
+    REDIS_KEEPALIVE_COUNT: PositiveInt = Field(default=10, description="redis keepalive count")
+
     @field_validator("REDIS_MAX_CONNECTIONS", mode="before")
     @classmethod
     def _empty_string_to_none_for_max_conns(cls, v):

api/constants/dsl_version.py

@@ -1 +1 @@
-CURRENT_APP_DSL_VERSION = "0.6.0"
+CURRENT_APP_DSL_VERSION = "0.7.0"

api/controllers/common/agent_app_parameters.py

@@ -1,27 +1,29 @@
 from typing import Any
 
 from sqlalchemy import select
+from sqlalchemy.orm import Session
 
 from core.app.apps.agent_app.app_feature_projection import merge_agent_app_features
 from core.app.apps.agent_app.app_variable_projection import agent_app_variables_to_user_input_form
 from core.app.apps.agent_app.errors import AgentAppGeneratorError, AgentAppNotPublishedError
-from extensions.ext_database import db
 from models.agent import Agent, AgentConfigSnapshot, AgentStatus
 from models.agent_config_entities import AgentSoulConfig
-from models.model import App
+from models.model import App, load_annotation_reply_config
 
 
 def get_published_agent_app_feature_dict_and_user_input_form(
     app_model: App,
+    *,
+    session: Session,
 ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
     """Return public Agent App parameters backed by the published Agent Soul."""
-    app_model_config = app_model.app_model_config
+    app_model_config = app_model.app_model_config_with_session(session=session)
 
     agent_id = app_model.bound_agent_id
     if not agent_id:
         raise AgentAppGeneratorError("Agent App has no bound Agent")
 
-    agent = db.session.scalar(
+    agent = session.scalar(
         select(Agent)
         .where(
             Agent.tenant_id == app_model.tenant_id,
@@ -37,7 +39,7 @@ def get_published_agent_app_feature_dict_and_user_input_form(
     if not agent.active_config_snapshot_id:
         raise AgentAppNotPublishedError("Agent has not been published")
 
-    snapshot = db.session.scalar(
+    snapshot = session.scalar(
         select(AgentConfigSnapshot)
         .where(
             AgentConfigSnapshot.tenant_id == app_model.tenant_id,
@@ -50,5 +52,10 @@ def get_published_agent_app_feature_dict_and_user_input_form(
         raise AgentAppGeneratorError("Agent published version not found")
 
     agent_soul = AgentSoulConfig.model_validate(snapshot.config_snapshot_dict)
-    features_dict = merge_agent_app_features(agent_soul=agent_soul, app_model_config=app_model_config)
+    annotation_reply = load_annotation_reply_config(session, app_model.id) if app_model_config else None
+    features_dict = merge_agent_app_features(
+        agent_soul=agent_soul,
+        app_model_config=app_model_config,
+        annotation_reply=annotation_reply,
+    )
     return features_dict, agent_app_variables_to_user_input_form(agent_soul.app_variables)

api/controllers/common/app_access.py

@@ -4,7 +4,8 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from extensions.ext_database import db
+from sqlalchemy.orm import Session
+
 from services.enterprise import rbac_service as enterprise_rbac_service
 
 if TYPE_CHECKING:
@@ -68,6 +69,7 @@ def resolve_app_access_filter(
     tenant_id: str,
     account_id: str,
     *,
+    session: Session,
     permissions: MyPermissionsResponse | None = None,
 ) -> AppAccessFilter:
     """Compute the RBAC app-access filter for ``account_id`` in ``tenant_id``.
@@ -77,7 +79,7 @@ def resolve_app_access_filter(
     inner-API round trip; otherwise it is fetched here.
     """
     if permissions is None:
-        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(tenant_id, account_id, session=db.session())
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(tenant_id, account_id, session=session)
     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

api/controllers/common/session.py

@@ -2,8 +2,10 @@
 
 `with_session` is an HTTP controller helper: it opens one SQLAlchemy session
 for a Resource handler and injects it as the first argument after `self`.
-Handlers use a transaction by default so migrated write paths keep
-commit/rollback handling; pure read handlers may opt out with `write=False`.
+Write handlers commit on success and roll back on failure. They use a regular
+Session context so existing services may commit an intermediate unit and keep
+using the same Session through SQLAlchemy's autobegin behavior. Pure read
+handlers may opt out with `write=False`.
 """
 
 from collections.abc import Callable
@@ -38,14 +40,20 @@ def with_session[T, **P, R](
 ) -> (
     Callable[Concatenate[T, P], R] | Callable[[Callable[Concatenate[T, Session, P], R]], Callable[Concatenate[T, P], R]]
 ):
-    """Inject a request-scoped session, using a transaction only for write handlers."""
+    """Inject a request-scoped session and finalize write handlers."""
 
     def decorator(view: Callable[Concatenate[T, Session, P], R]) -> Callable[Concatenate[T, P], R]:
         @wraps(view)
         def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
             if write:
-                with session_factory.get_session_maker().begin() as session:
-                    return view(self, session, *args, **kwargs)
+                with session_factory.create_session() as session:
+                    try:
+                        result = view(self, session, *args, **kwargs)
+                        session.commit()
+                        return result
+                    except Exception:
+                        session.rollback()  # noqa: no-new-controller-sqlalchemy decorator owns transaction rollback
+                        raise
 
             with session_factory.create_session() as session:
                 return view(self, session, *args, **kwargs)

api/controllers/console/__init__.py

@@ -43,6 +43,7 @@ from . import (
     setup,
     spec,
     version,
+    workflow_run_archive,
 )
 from .agent import composer as agent_composer
 from .agent import roster as agent_roster
@@ -124,6 +125,7 @@ from .explore import (
     saved_message,
     trial,
 )
+from .knowledge_fs import resources as knowledge_fs_resources
 from .snippets import snippet_workflow, snippet_workflow_draft_variable
 from .socketio import workflow as socketio_workflow
 
@@ -194,6 +196,7 @@ __all__ = [
     "human_input_form",
     "init_validate",
     "installed_app",
+    "knowledge_fs_resources",
     "load_balancing_config",
     "login",
     "mcp_server",
@@ -238,6 +241,7 @@ __all__ = [
     "workflow_draft_variable",
     "workflow_node_output_inspector",
     "workflow_run",
+    "workflow_run_archive",
     "workflow_statistic",
     "workflow_trigger",
     "workspace",

api/controllers/console/agent/app_helpers.py

@@ -1,20 +1,21 @@
 from uuid import UUID
 
-from extensions.ext_database import db
+from sqlalchemy.orm import Session
+
 from models.model import App
 from services.agent.roster_service import AgentRosterService
 
 
-def resolve_agent_app_model(*, tenant_id: str, agent_id: UUID) -> App:
+def resolve_agent_app_model(*, session: Session, tenant_id: str, agent_id: UUID) -> App:
     """Resolve a roster Agent's public Agent App."""
-    return AgentRosterService(db.session).get_agent_app_model(tenant_id=tenant_id, agent_id=str(agent_id))
+    return AgentRosterService(session).get_agent_app_model(tenant_id=tenant_id, agent_id=str(agent_id))
 
 
-def resolve_agent_runtime_app_model(*, tenant_id: str, agent_id: UUID) -> App:
+def resolve_agent_runtime_app_model(*, session: Session, tenant_id: str, agent_id: UUID) -> App:
     """Resolve the App that backs an Agent runtime surface.
 
     This accepts both roster Agent Apps and workflow-only inline Agents with a
     hidden backing App.
     """
 
-    return AgentRosterService(db.session).get_agent_runtime_app_model(tenant_id=tenant_id, agent_id=str(agent_id))
+    return AgentRosterService(session).get_agent_runtime_app_model(tenant_id=tenant_id, agent_id=str(agent_id))

api/controllers/console/agent/composer.py

@@ -2,8 +2,11 @@ from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
+from sqlalchemy.orm import Session
+from werkzeug.exceptions import NotFound
 
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -16,7 +19,6 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user_id,
 )
-from extensions.ext_database import db
 from fields.agent_fields import (
     AgentAppComposerResponse,
     AgentComposerCandidatesResponse,
@@ -34,6 +36,7 @@ from services.entities.agent_entities import (
     WorkflowAgentComposerQuery,
     WorkflowComposerCopyFromRosterPayload,
 )
+from services.snippet_service import SnippetService
 
 register_schema_models(
     console_ns, ComposerSavePayload, WorkflowAgentComposerQuery, WorkflowComposerCopyFromRosterPayload
@@ -57,20 +60,21 @@ class WorkflowAgentComposerApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     @with_current_user_id
     @with_current_tenant_id
-    def get(self, tenant_id: str, account_id: str, app_model: App, node_id: str):
+    @with_session
+    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    def get(self, session: Session, tenant_id: str, account_id: str, app_model: App, node_id: str):
         query = WorkflowAgentComposerQuery.model_validate(request.args.to_dict(flat=True))
         return dump_response(
             WorkflowAgentComposerResponse,
             AgentComposerService.load_workflow_composer(
+                session=session,
                 tenant_id=tenant_id,
                 app_id=app_model.id,
                 node_id=node_id,
                 account_id=account_id,
                 snapshot_id=query.snapshot_id,
-                session=db.session(),
             ),
         )
 
@@ -83,20 +87,21 @@ class WorkflowAgentComposerApi(Resource):
     @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 put(self, tenant_id: str, account_id: str, app_model: App, node_id: str):
+    @with_session
+    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    def put(self, session: Session, tenant_id: str, account_id: str, app_model: App, node_id: str):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         return dump_response(
             WorkflowAgentComposerResponse,
             AgentComposerService.save_workflow_composer(
+                session=session,
                 tenant_id=tenant_id,
                 app_id=app_model.id,
                 node_id=node_id,
                 account_id=account_id,
                 payload=payload,
-                session=db.session(),
             ),
         )
 
@@ -114,14 +119,16 @@ class WorkflowAgentComposerCopyFromRosterApi(Resource):
     @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):
+    @with_session
+    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    def post(self, session: Session, 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(
+                session=session,
                 tenant_id=tenant_id,
                 app_id=app_model.id,
                 node_id=node_id,
@@ -129,7 +136,6 @@ class WorkflowAgentComposerCopyFromRosterApi(Resource):
                 source_agent_id=payload.source_agent_id,
                 source_snapshot_id=payload.source_snapshot_id,
                 idempotency_key=payload.idempotency_key,
-                session=db.session(),
             ),
         )
 
@@ -143,19 +149,22 @@ class WorkflowAgentComposerValidateApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     @with_current_tenant_id
-    def post(self, tenant_id: str, app_model: App, node_id: str):
+    @with_session(write=False)
+    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    def post(self, session: Session, tenant_id: str, app_model: App, node_id: str):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_publish_payload(payload)
-        AgentComposerService.validate_knowledge_datasets(tenant_id=tenant_id, agent_soul=payload.agent_soul)
+        AgentComposerService.validate_knowledge_datasets(
+            session=session, tenant_id=tenant_id, agent_soul=payload.agent_soul
+        )
         findings = AgentComposerService.collect_validation_findings(
+            session=session,
             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, session=db.session()
+                session=session, tenant_id=tenant_id, app_id=app_model.id, node_id=node_id
             ),
-            session=db.session(),
         )
         return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": [], **findings})
 
@@ -168,18 +177,19 @@ class WorkflowAgentComposerCandidatesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     @with_current_user_id
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user_id: str, app_model: App, node_id: str):
+    @with_session(write=False)
+    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    def get(self, session: Session, tenant_id: str, current_user_id: str, app_model: App, node_id: str):
         return dump_response(
             AgentComposerCandidatesResponse,
             AgentComposerService.get_workflow_candidates(
+                session=session,
                 tenant_id=tenant_id,
                 app_id=app_model.id,
                 node_id=node_id,
                 user_id=current_user_id,
-                session=db.session(),
             ),
         )
 
@@ -191,9 +201,10 @@ class WorkflowAgentComposerImpactApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     @with_current_tenant_id
-    def post(self, tenant_id: str, app_model: App, node_id: str):
+    @with_session(write=False)
+    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    def post(self, session: Session, tenant_id: str, app_model: App, node_id: str):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         current_snapshot_id = payload.binding.current_snapshot_id if payload.binding else None
         if not current_snapshot_id:
@@ -203,7 +214,7 @@ class WorkflowAgentComposerImpactApi(Resource):
         return dump_response(
             AgentComposerImpactResponse,
             AgentComposerService.calculate_impact(
-                tenant_id=tenant_id, current_snapshot_id=current_snapshot_id, session=db.session()
+                session=session, tenant_id=tenant_id, current_snapshot_id=current_snapshot_id
             ),
         )
 
@@ -219,20 +230,229 @@ class WorkflowAgentComposerSaveToRosterApi(Resource):
     @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):
+    @with_session
+    @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    def post(self, session: Session, tenant_id: str, account_id: str, app_model: App, node_id: str):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         return dump_response(
             WorkflowAgentComposerResponse,
             AgentComposerService.save_workflow_composer(
+                session=session,
                 tenant_id=tenant_id,
                 app_id=app_model.id,
                 node_id=node_id,
                 account_id=account_id,
                 payload=payload,
-                session=db.session(),
+            ),
+        )
+
+
+def _require_snippet_app_id(*, session: Session, tenant_id: str, snippet_id: UUID) -> str:
+    snippet = SnippetService(session=session).get_snippet_by_id(
+        snippet_id=str(snippet_id),
+        tenant_id=tenant_id,
+    )
+    if snippet is None:
+        raise NotFound("Snippet not found")
+    return snippet.id
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/agent-composer")
+class SnippetAgentComposerApi(Resource):
+    @console_ns.response(200, "Snippet agent composer state", console_ns.models[WorkflowAgentComposerResponse.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowAgentComposerQuery))
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user_id
+    @with_current_tenant_id
+    @with_session
+    def get(self, session: Session, tenant_id: str, account_id: str, snippet_id: UUID, node_id: str):
+        query = WorkflowAgentComposerQuery.model_validate(request.args.to_dict(flat=True))
+        return dump_response(
+            WorkflowAgentComposerResponse,
+            AgentComposerService.load_workflow_composer(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=_require_snippet_app_id(session=session, tenant_id=tenant_id, snippet_id=snippet_id),
+                node_id=node_id,
+                account_id=account_id,
+                snapshot_id=query.snapshot_id,
+            ),
+        )
+
+    @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(200, "Snippet agent composer saved", console_ns.models[WorkflowAgentComposerResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @rbac_permission_required(
+        RBACResourceScope.WORKSPACE, RBACPermission.SNIPPETS_CREATE_AND_MODIFY, resource_required=False
+    )
+    @with_current_user_id
+    @with_current_tenant_id
+    @with_session
+    def put(self, session: Session, tenant_id: str, account_id: str, snippet_id: UUID, node_id: str):
+        payload = ComposerSavePayload.model_validate(console_ns.payload or {})
+        return dump_response(
+            WorkflowAgentComposerResponse,
+            AgentComposerService.save_workflow_composer(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=_require_snippet_app_id(session=session, tenant_id=tenant_id, snippet_id=snippet_id),
+                node_id=node_id,
+                account_id=account_id,
+                payload=payload,
+            ),
+        )
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/agent-composer/copy-from-roster")
+class SnippetAgentComposerCopyFromRosterApi(Resource):
+    @console_ns.expect(console_ns.models[WorkflowComposerCopyFromRosterPayload.__name__])
+    @console_ns.response(
+        200, "Roster agent copied into snippet", console_ns.models[WorkflowAgentComposerResponse.__name__]
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @rbac_permission_required(
+        RBACResourceScope.WORKSPACE, RBACPermission.SNIPPETS_CREATE_AND_MODIFY, resource_required=False
+    )
+    @with_current_user_id
+    @with_current_tenant_id
+    @with_session
+    def post(self, session: Session, tenant_id: str, account_id: str, snippet_id: UUID, node_id: str):
+        payload = WorkflowComposerCopyFromRosterPayload.model_validate(console_ns.payload or {})
+        return dump_response(
+            WorkflowAgentComposerResponse,
+            AgentComposerService.copy_workflow_composer_from_roster(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=_require_snippet_app_id(session=session, tenant_id=tenant_id, snippet_id=snippet_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("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/agent-composer/validate")
+class SnippetAgentComposerValidateApi(Resource):
+    @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(
+        200, "Snippet agent composer validation", console_ns.models[AgentComposerValidateResponse.__name__]
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    @with_session(write=False)
+    def post(self, session: Session, tenant_id: str, snippet_id: UUID, node_id: str):
+        app_id = _require_snippet_app_id(session=session, tenant_id=tenant_id, snippet_id=snippet_id)
+        payload = ComposerSavePayload.model_validate(console_ns.payload or {})
+        ComposerConfigValidator.validate_publish_payload(payload)
+        AgentComposerService.validate_knowledge_datasets(
+            session=session, tenant_id=tenant_id, agent_soul=payload.agent_soul
+        )
+        findings = AgentComposerService.collect_validation_findings(
+            session=session,
+            tenant_id=tenant_id,
+            payload=payload,
+            agent_id=AgentComposerService.resolve_workflow_node_agent_id(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=app_id,
+                node_id=node_id,
+            ),
+        )
+        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": [], **findings})
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/agent-composer/candidates")
+class SnippetAgentComposerCandidatesApi(Resource):
+    @console_ns.response(
+        200, "Snippet agent composer candidates", console_ns.models[AgentComposerCandidatesResponse.__name__]
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user_id
+    @with_current_tenant_id
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, current_user_id: str, snippet_id: UUID, node_id: str):
+        return dump_response(
+            AgentComposerCandidatesResponse,
+            AgentComposerService.get_workflow_candidates(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=_require_snippet_app_id(session=session, tenant_id=tenant_id, snippet_id=snippet_id),
+                node_id=node_id,
+                user_id=current_user_id,
+            ),
+        )
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/agent-composer/impact")
+class SnippetAgentComposerImpactApi(Resource):
+    @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(200, "Snippet agent composer impact", console_ns.models[AgentComposerImpactResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    @with_session(write=False)
+    def post(self, session: Session, tenant_id: str, snippet_id: UUID, node_id: str):
+        _require_snippet_app_id(session=session, tenant_id=tenant_id, snippet_id=snippet_id)
+        payload = ComposerSavePayload.model_validate(console_ns.payload or {})
+        current_snapshot_id = payload.binding.current_snapshot_id if payload.binding else None
+        if not current_snapshot_id:
+            return dump_response(
+                AgentComposerImpactResponse, {"current_snapshot_id": None, "workflow_node_count": 0, "bindings": []}
+            )
+        return dump_response(
+            AgentComposerImpactResponse,
+            AgentComposerService.calculate_impact(
+                session=session,
+                tenant_id=tenant_id,
+                current_snapshot_id=current_snapshot_id,
+            ),
+        )
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/agent-composer/save-to-roster")
+class SnippetAgentComposerSaveToRosterApi(Resource):
+    @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(
+        200, "Snippet agent saved to roster", console_ns.models[WorkflowAgentComposerResponse.__name__]
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @rbac_permission_required(
+        RBACResourceScope.WORKSPACE, RBACPermission.SNIPPETS_CREATE_AND_MODIFY, resource_required=False
+    )
+    @with_current_user_id
+    @with_current_tenant_id
+    @with_session
+    def post(self, session: Session, tenant_id: str, account_id: str, snippet_id: UUID, node_id: str):
+        payload = ComposerSavePayload.model_validate(console_ns.payload or {})
+        return dump_response(
+            WorkflowAgentComposerResponse,
+            AgentComposerService.save_workflow_composer(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=_require_snippet_app_id(session=session, tenant_id=tenant_id, snippet_id=snippet_id),
+                node_id=node_id,
+                account_id=account_id,
+                payload=payload,
             ),
         )
 
@@ -244,10 +464,11 @@ class AgentComposerApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
+    @with_session
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
         return dump_response(
             AgentAppComposerResponse,
-            AgentComposerService.load_agent_composer(tenant_id=tenant_id, agent_id=str(agent_id), session=db.session()),
+            AgentComposerService.load_agent_composer(session=session, tenant_id=tenant_id, agent_id=str(agent_id)),
         )
 
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
@@ -259,16 +480,17 @@ class AgentComposerApi(Resource):
     @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, agent_id: UUID):
+    @with_session
+    def put(self, session: Session, tenant_id: str, account_id: str, agent_id: UUID):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         return dump_response(
             AgentAppComposerResponse,
             AgentComposerService.save_agent_composer(
+                session=session,
                 tenant_id=tenant_id,
                 agent_id=str(agent_id),
                 account_id=account_id,
                 payload=payload,
-                session=db.session(),
             ),
         )
 
@@ -283,16 +505,19 @@ class AgentComposerValidateApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def post(self, tenant_id: str, agent_id: UUID):
-        AgentComposerService.load_agent_composer(tenant_id=tenant_id, agent_id=str(agent_id), session=db.session())
+    @with_session
+    def post(self, session: Session, tenant_id: str, agent_id: UUID):
+        AgentComposerService.load_agent_composer(session=session, tenant_id=tenant_id, agent_id=str(agent_id))
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_publish_payload(payload)
-        AgentComposerService.validate_knowledge_datasets(tenant_id=tenant_id, agent_soul=payload.agent_soul)
+        AgentComposerService.validate_knowledge_datasets(
+            session=session, tenant_id=tenant_id, agent_soul=payload.agent_soul
+        )
         findings = AgentComposerService.collect_validation_findings(
+            session=session,
             tenant_id=tenant_id,
             payload=payload,
             agent_id=str(agent_id),
-            session=db.session(),
         )
         return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": [], **findings})
 
@@ -307,13 +532,14 @@ class AgentComposerCandidatesApi(Resource):
     @account_initialization_required
     @with_current_user_id
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user_id: str, agent_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, current_user_id: str, agent_id: UUID):
         return dump_response(
             AgentComposerCandidatesResponse,
             AgentComposerService.get_agent_app_candidates(
+                session=session,
                 tenant_id=tenant_id,
                 agent_id=str(agent_id),
                 user_id=current_user_id,
-                session=db.session(),
             ),
         )

api/controllers/console/agent/roster.py

@@ -4,6 +4,7 @@ from flask import abort, request
 from flask_restx import Resource
 from pydantic import AliasChoices, BaseModel, Field, field_validator
 from sqlalchemy import func, select
+from sqlalchemy.orm import Session
 
 from controllers.common.schema import (
     query_params_from_model,
@@ -11,8 +12,8 @@ from controllers.common.schema import (
     register_response_schema_models,
     register_schema_models,
 )
+from controllers.common.session import with_session
 from controllers.console import console_ns
-from controllers.console.agent.app_helpers import resolve_agent_app_model, resolve_agent_runtime_app_model
 from controllers.console.apikey import ApiKeyItem, ApiKeyList, BaseApiKeyListResource, BaseApiKeyResource
 from controllers.console.app.app import (
     APP_LIST_QUERY_ARRAY_FIELDS,
@@ -42,7 +43,6 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
-from extensions.ext_database import db
 from fields.agent_fields import (
     AgentConfigDraftSummaryResponse,
     AgentConfigSnapshotDetailResponse,
@@ -177,7 +177,7 @@ class AgentLogsQuery(BaseModel):
         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>"
+            "or workflow:<app_id>. Exact workflow:<app_id>:<workflow_id>:<version>:<node_id> IDs remain supported."
         ),
     )
     sort_by: str = Field(default="updated_at", description="Sort by created_at or updated_at")
@@ -221,7 +221,10 @@ class AgentLogsQuery(BaseModel):
 class AgentStatisticsQuery(BaseModel):
     source: str | None = Field(
         default=None,
-        description="Filter by all, console/explore, api/service-api, web-app, debugger, openapi, or trigger",
+        description=(
+            "Filter by a structured webapp:<app_id> or workflow:<app_id> source ID. "
+            "Legacy invoke sources and exact workflow version/node source IDs remain supported."
+        ),
     )
     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)")
@@ -241,6 +244,7 @@ class AgentAppPartial(GenericAppPartial):
     debug_conversation_id: str | None = None
     role: str | None = None
     active_config_is_published: bool = False
+    reference_count: int | None = None
     published_reference_count: int = 0
     published_references: list[AgentAppPublishedReferenceResponse] = Field(default_factory=list)
 
@@ -339,11 +343,13 @@ register_response_schema_models(
 )
 
 
-def _agent_roster_service() -> AgentRosterService:
-    return AgentRosterService(db.session)
+def _agent_roster_service(session: Session) -> AgentRosterService:
+    return AgentRosterService(session)
 
 
-def _serialize_agent_app_detail(app_model, *, current_user: Account, agent_id: str | None = None) -> dict:
+def _serialize_agent_app_detail(
+    session: Session, app_model, *, current_user: Account, agent_id: str | None = None
+) -> dict:
     """Serialize an Agent App detail using roster-only DTOs.
 
     `/agent` responses are roster-shaped rather than raw app-shaped: `id`
@@ -353,15 +359,19 @@ def _serialize_agent_app_detail(app_model, *, current_user: Account, agent_id: s
     roster persona fields without widening the shared /apps detail schema.
     """
 
-    app_model = AppService().get_app(app_model)
+    app_model = AppService().get_app(app_model, session=session)
     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")
+    roster_service = _agent_roster_service(session)
+    payload = AgentAppDetailWithSite.model_validate(
+        app_model,
+        from_attributes=True,
+        context={"session": session},
+    ).model_dump(mode="json")
     agent = (
-        db.session.scalar(
+        session.scalar(
             select(Agent).where(
                 Agent.tenant_id == app_model.tenant_id,
                 Agent.id == agent_id,
@@ -382,6 +392,7 @@ def _serialize_agent_app_detail(app_model, *, current_user: Account, agent_id: s
         tenant_id=app_model.tenant_id,
         agent_id=agent.id,
         account_id=current_user.id,
+        commit=False,
     )
     message_count = roster_service.count_agent_app_debug_conversation_messages(
         conversation_id=debug_conversation_id,
@@ -397,7 +408,7 @@ def _serialize_agent_app_detail(app_model, *, current_user: Account, agent_id: s
     return payload
 
 
-def _serialize_agent_app_pagination(app_pagination, *, tenant_id: str, current_user: Account) -> dict:
+def _serialize_agent_app_pagination(session: Session, 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
@@ -407,7 +418,7 @@ def _serialize_agent_app_pagination(app_pagination, *, tenant_id: str, current_u
     """
 
     app_ids = [str(app.id) for app in app_pagination.items]
-    roster_service = _agent_roster_service()
+    roster_service = _agent_roster_service(session)
     agents_by_app_id = roster_service.load_app_backing_agents_by_app_id(
         tenant_id=tenant_id,
         app_ids=app_ids,
@@ -420,12 +431,20 @@ def _serialize_agent_app_pagination(app_pagination, *, tenant_id: str, current_u
         tenant_id=tenant_id,
         agent_ids=[agent.id for agent in agents_by_app_id.values()],
     )
+    reference_counts_by_agent_id = roster_service.load_reference_counts_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")
+    payload = AgentAppPagination.model_validate(
+        app_pagination,
+        from_attributes=True,
+        context={"session": session},
+    ).model_dump(mode="json")
     for item in payload["data"]:
         app_id = item["id"]
         item.pop("bound_agent_id", None)
@@ -438,6 +457,7 @@ def _serialize_agent_app_pagination(app_pagination, *, tenant_id: str, current_u
             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)
+            item["reference_count"] = reference_counts_by_agent_id.get(agent.id, 0)
             published_references = published_references_by_agent_id.get(agent.id, [])
             item["published_reference_count"] = len(published_references)
             item["published_references"] = [
@@ -456,13 +476,17 @@ def _serialize_agent_app_pagination(app_pagination, *, tenant_id: str, current_u
     )
 
 
-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 _resolve_agent_app_model(session: Session, *, tenant_id: str, agent_id: UUID) -> App:
+    return _agent_roster_service(session).get_agent_app_model(tenant_id=tenant_id, agent_id=str(agent_id))
 
 
-def _agent_api_key_count(app_id: str) -> int:
+def _resolve_agent_runtime_app_model(session: Session, *, tenant_id: str, agent_id: UUID) -> App:
+    return _agent_roster_service(session).get_agent_runtime_app_model(tenant_id=tenant_id, agent_id=str(agent_id))
+
+
+def _agent_api_key_count(session: Session, app_id: str) -> int:
     return (
-        db.session.scalar(
+        session.scalar(
             select(func.count(ApiToken.id)).where(
                 ApiToken.type == ApiTokenType.APP,
                 ApiToken.app_id == app_id,
@@ -472,7 +496,7 @@ def _agent_api_key_count(app_id: str) -> int:
     )
 
 
-def _serialize_agent_api_access(app_model: App) -> dict:
+def _serialize_agent_api_access(session: Session, app_model: App) -> dict:
     base_url = app_model.api_base_url
     response = AgentApiAccessResponse(
         enabled=bool(app_model.enable_api),
@@ -487,13 +511,13 @@ def _serialize_agent_api_access(app_model: App) -> dict:
         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)),
+        api_key_count=_agent_api_key_count(session, str(app_model.id)),
     )
     return response.model_dump(mode="json")
 
 
-def _agent_observability_service() -> AgentObservabilityService:
-    return AgentObservabilityService(db.session)
+def _agent_observability_service(session: Session) -> AgentObservabilityService:
+    return AgentObservabilityService(session)
 
 
 def _parse_observability_time_range(start: str | None, end: str | None, account: Account):
@@ -520,7 +544,8 @@ class AgentAppListApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, current_tenant_id: str, current_user: Account):
+    @with_session
+    def get(self, session: Session, current_tenant_id: str, current_user: Account):
         args = query_params_from_request(AppListQuery, list_fields=APP_LIST_QUERY_ARRAY_FIELDS)
         params = AppListParams(
             page=args.page,
@@ -534,12 +559,13 @@ class AgentAppListApi(Resource):
             status="normal",
         )
 
-        app_pagination = AppService().get_paginate_apps(current_user.id, current_tenant_id, params, db.session())
+        app_pagination = AppService().get_paginate_apps(current_user.id, current_tenant_id, params, 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(
+            session,
             app_pagination,
             tenant_id=current_tenant_id,
             current_user=current_user,
@@ -555,7 +581,8 @@ class AgentAppListApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def post(self, current_tenant_id: str, current_user: Account):
+    @with_session
+    def post(self, session: Session, current_tenant_id: str, current_user: Account):
         args = AgentAppCreatePayload.model_validate(console_ns.payload)
         params = CreateAppParams(
             name=args.name,
@@ -567,8 +594,8 @@ class AgentAppListApi(Resource):
             icon_background=args.icon_background,
         )
 
-        app = AppService().create_app(current_tenant_id, params, current_user, session=db.session())
-        return _serialize_agent_app_detail(app, current_user=current_user), 201
+        app = AppService().create_app(current_tenant_id, params, current_user, session=session)
+        return _serialize_agent_app_detail(session, app, current_user=current_user), 201
 
 
 @console_ns.route("/agent/<uuid:agent_id>")
@@ -580,9 +607,10 @@ class AgentAppApi(Resource):
     @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_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
-        return _serialize_agent_app_detail(app_model, current_user=current_user, agent_id=str(agent_id))
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_runtime_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
+        return _serialize_agent_app_detail(session, app_model, current_user=current_user, agent_id=str(agent_id))
 
     @console_ns.expect(console_ns.models[AgentAppUpdatePayload.__name__])
     @console_ns.response(200, "Agent app updated successfully", console_ns.models[AgentAppDetailWithSite.__name__])
@@ -594,8 +622,9 @@ class AgentAppApi(Resource):
     @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)
+    @with_session
+    def put(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
         args = AgentAppUpdatePayload.model_validate(console_ns.payload)
         args_dict: AppService.ArgsDict = {
             "name": args.name,
@@ -607,8 +636,8 @@ class AgentAppApi(Resource):
             "max_active_requests": args.max_active_requests or 0,
             "role": args.role,
         }
-        updated = AppService().update_app(app_model, args_dict, session=db.session())
-        return _serialize_agent_app_detail(updated, current_user=current_user)
+        updated = AppService().update_app(app_model, args_dict, session=session)
+        return _serialize_agent_app_detail(session, updated, current_user=current_user)
 
     @console_ns.response(204, "Agent app deleted successfully")
     @console_ns.response(403, "Insufficient permissions")
@@ -617,9 +646,10 @@ class AgentAppApi(Resource):
     @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, session=db.session())
+    @with_session
+    def delete(self, session: Session, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
+        AppService().delete_app(app_model, session=session)
         return "", 204
 
 
@@ -637,8 +667,9 @@ class AgentDebugConversationRefreshApi(Resource):
     @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(
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        debug_conversation_id = _agent_roster_service(session).refresh_agent_app_debug_conversation_id(
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account_id=current_user.id,
@@ -661,14 +692,15 @@ class AgentPublishApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         args = AgentPublishPayload.model_validate(console_ns.payload or {})
         return AgentComposerService.publish_agent_app_draft(
+            session=session,
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account_id=current_user.id,
             version_note=args.version_note,
-            session=db.session(),
         )
 
 
@@ -682,14 +714,15 @@ class AgentBuildDraftCheckoutApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         args = AgentBuildDraftCheckoutPayload.model_validate(console_ns.payload or {})
         return AgentComposerService.checkout_agent_app_build_draft(
+            session=session,
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account_id=current_user.id,
             force=args.force,
-            session=db.session(),
         )
 
 
@@ -702,12 +735,13 @@ class AgentBuildDraftApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return AgentComposerService.load_agent_app_build_draft(
+            session=session,
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account_id=current_user.id,
-            session=db.session(),
         )
 
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
@@ -718,14 +752,15 @@ class AgentBuildDraftApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def put(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def put(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         return AgentComposerService.save_agent_app_build_draft(
+            session=session,
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account_id=current_user.id,
             payload=payload,
-            session=db.session(),
         )
 
     @console_ns.response(200, "Agent build draft discarded", console_ns.models[AgentSimpleResultResponse.__name__])
@@ -735,12 +770,13 @@ class AgentBuildDraftApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def delete(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def delete(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return AgentComposerService.discard_agent_app_build_draft(
+            session=session,
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account_id=current_user.id,
-            session=db.session(),
         )
 
 
@@ -753,12 +789,13 @@ class AgentBuildDraftApplyApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return AgentComposerService.apply_agent_app_build_draft(
+            session=session,
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account_id=current_user.id,
-            session=db.session(),
         )
 
 
@@ -774,9 +811,10 @@ class AgentAppCopyApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def post(self, session: Session, 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(
+        copied_app = _agent_roster_service(session).duplicate_agent_app(
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account=current_user,
@@ -787,7 +825,7 @@ class AgentAppCopyApi(Resource):
             icon=args.icon,
             icon_background=args.icon_background,
         )
-        return _serialize_agent_app_detail(copied_app, current_user=current_user), 201
+        return _serialize_agent_app_detail(session, copied_app, current_user=current_user), 201
 
 
 @console_ns.route("/agent/<uuid:agent_id>/api-access")
@@ -797,9 +835,10 @@ class AgentApiAccessApi(Resource):
     @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)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
+        return _serialize_agent_api_access(session, app_model)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/api-enable")
@@ -813,11 +852,12 @@ class AgentApiStatusApi(Resource):
     @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)
+    @with_session
+    def post(self, session: Session, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(session, 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, session=db.session())
-        return _serialize_agent_api_access(app_model)
+        app_model = AppService().update_app_api_status(app_model, args.enable_api, session=session)
+        return _serialize_agent_api_access(session, app_model)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/api-keys")
@@ -829,18 +869,23 @@ class AgentApiKeyListApi(BaseApiKeyListResource):
 
     @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))
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID) -> dict[str, object]:
+        app_model = _resolve_agent_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
+        return dump_response(ApiKeyList, self._get_api_key_list(str(app_model.id), tenant_id, session=session))
 
     @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
+    @with_session
+    def post(self, session: Session, tenant_id: str, agent_id: UUID) -> tuple[dict[str, object], int]:
+        app_model = _resolve_agent_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
+        return dump_response(
+            ApiKeyItem,
+            self._create_api_key(str(app_model.id), tenant_id, session=session),
+        ), 201
 
 
 @console_ns.route("/agent/<uuid:agent_id>/api-keys/<uuid:api_key_id>")
@@ -853,9 +898,17 @@ class AgentApiKeyApi(BaseApiKeyResource):
     @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)
+    @with_session
+    def delete(
+        self,
+        session: Session,
+        tenant_id: str,
+        current_user: Account,
+        agent_id: UUID,
+        api_key_id: UUID,
+    ) -> tuple[str, int]:
+        app_model = _resolve_agent_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
+        self._delete_api_key(str(app_model.id), str(api_key_id), tenant_id, current_user, session=session)
         return "", 204
 
 
@@ -867,11 +920,12 @@ class AgentInviteOptionsApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str):
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str):
         query = AgentInviteOptionsQuery.model_validate(request.args.to_dict(flat=True))
         return dump_response(
             AgentInviteOptionsResponse,
-            _agent_roster_service().list_invite_options(
+            _agent_roster_service(session).list_invite_options(
                 tenant_id=tenant_id,
                 page=query.page,
                 limit=query.limit,
@@ -890,15 +944,16 @@ class AgentLogsApi(Resource):
     @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_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_runtime_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
         query_data: dict[str, object] = dict(request.args.to_dict(flat=True))
         query_data["sources"] = _query_values("sources", "source")
         query_data["statuses"] = _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(
+            payload = _agent_observability_service(session).list_logs(
                 app=app_model,
                 agent_id=str(agent_id),
                 params=AgentLogQueryParams(
@@ -927,15 +982,16 @@ class AgentLogMessagesApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, conversation_id: UUID):
-        app_model = resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, conversation_id: UUID):
+        app_model = _resolve_agent_runtime_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
         query_data: dict[str, object] = dict(request.args.to_dict(flat=True))
         query_data["sources"] = _query_values("sources", "source")
         query_data["statuses"] = _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(
+            payload = _agent_observability_service(session).list_log_messages(
                 app=app_model,
                 agent_id=str(agent_id),
                 conversation_id=str(conversation_id),
@@ -964,9 +1020,10 @@ class AgentLogSourcesApi(Resource):
     @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_runtime_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))
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_runtime_app_model(session, tenant_id=tenant_id, agent_id=agent_id)
+        payload = _agent_observability_service(session).list_log_sources(app=app_model, agent_id=str(agent_id))
         return dump_response(AgentLogSourceListResponse, payload)
 
 
@@ -983,13 +1040,14 @@ class AgentStatisticsSummaryApi(Resource):
     @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_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_runtime_app_model(session, 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(
+            payload = _agent_observability_service(session).get_statistics_summary(
                 app=app_model,
                 agent_id=str(agent_id),
                 params=AgentStatisticsQueryParams(source=query.source, start=start, end=end, timezone=timezone),
@@ -1006,10 +1064,11 @@ class AgentRosterVersionsApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
         return dump_response(
             AgentConfigSnapshotListResponse,
-            {"data": _agent_roster_service().list_agent_versions(tenant_id=tenant_id, agent_id=str(agent_id))},
+            {"data": _agent_roster_service(session).list_agent_versions(tenant_id=tenant_id, agent_id=str(agent_id))},
         )
 
 
@@ -1020,10 +1079,11 @@ class AgentRosterVersionDetailApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID, version_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID, version_id: UUID):
         return dump_response(
             AgentConfigSnapshotDetailResponse,
-            _agent_roster_service().get_agent_version_detail(
+            _agent_roster_service(session).get_agent_version_detail(
                 tenant_id=tenant_id,
                 agent_id=str(agent_id),
                 version_id=str(version_id),
@@ -1040,10 +1100,11 @@ class AgentRosterVersionRestoreApi(Resource):
     @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):
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, version_id: UUID):
         return dump_response(
             AgentConfigSnapshotRestoreResponse,
-            _agent_roster_service().restore_agent_version(
+            _agent_roster_service(session).restore_agent_version(
                 tenant_id=tenant_id,
                 agent_id=str(agent_id),
                 version_id=str(version_id),

api/controllers/console/apikey.py

@@ -6,12 +6,12 @@ from flask_restx import Resource
 from flask_restx._http import HTTPStatus
 from pydantic import field_validator
 from sqlalchemy import delete, func, select
-from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import Session
 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 controllers.common.session import with_session
 from fields.base import ResponseModel
 from libs.helper import dump_response, to_timestamp
 from libs.login import login_required
@@ -54,11 +54,10 @@ class ApiKeyList(ResponseModel):
 register_response_schema_models(console_ns, ApiKeyItem, ApiKeyList)
 
 
-def _get_resource(resource_id, tenant_id, resource_model):
-    with sessionmaker(db.engine).begin() as session:
-        resource = session.execute(
-            select(resource_model).filter_by(id=resource_id, tenant_id=tenant_id)
-        ).scalar_one_or_none()
+def _get_resource(resource_id, tenant_id, resource_model, *, session: Session):
+    resource = session.execute(
+        select(resource_model).filter_by(id=resource_id, tenant_id=tenant_id)
+    ).scalar_one_or_none()
 
     if resource is None:
         flask_restx.abort(HTTPStatus.NOT_FOUND, message=f"{resource_model.__name__} not found.")
@@ -75,14 +74,18 @@ class BaseApiKeyListResource(Resource):
     token_prefix: str | None = None
     max_keys = 10
 
-    def get(self, resource_id: str, current_tenant_id: str) -> dict[str, object]:
-        return dump_response(ApiKeyList, self._get_api_key_list(resource_id, current_tenant_id))
+    @with_session(write=False)
+    def get(self, session: Session, resource_id: str, current_tenant_id: str) -> dict[str, object]:
+        return dump_response(
+            ApiKeyList,
+            self._get_api_key_list(resource_id, current_tenant_id, session=session),
+        )
 
-    def _get_api_key_list(self, resource_id: str, current_tenant_id: str) -> ApiKeyList:
+    def _get_api_key_list(self, resource_id: str, current_tenant_id: str, *, session: Session) -> ApiKeyList:
         assert self.resource_id_field is not None, "resource_id_field must be set"
 
-        _get_resource(resource_id, current_tenant_id, self.resource_model)
-        keys = db.session.scalars(
+        _get_resource(resource_id, current_tenant_id, self.resource_model, session=session)
+        keys = session.scalars(
             select(ApiToken).where(
                 ApiToken.type == self.resource_type, getattr(ApiToken, self.resource_id_field) == resource_id
             )
@@ -90,14 +93,18 @@ class BaseApiKeyListResource(Resource):
         return ApiKeyList.model_validate({"data": keys}, from_attributes=True)
 
     @edit_permission_required
-    def post(self, resource_id: str, current_tenant_id: str) -> tuple[dict[str, object], int]:
-        return dump_response(ApiKeyItem, self._create_api_key(resource_id, current_tenant_id)), 201
+    @with_session
+    def post(self, session: Session, resource_id: str, current_tenant_id: str) -> tuple[dict[str, object], int]:
+        return dump_response(
+            ApiKeyItem,
+            self._create_api_key(resource_id, current_tenant_id, session=session),
+        ), 201
 
-    def _create_api_key(self, resource_id: str, current_tenant_id: str) -> ApiToken:
+    def _create_api_key(self, resource_id: str, current_tenant_id: str, *, session: Session) -> ApiToken:
         assert self.resource_id_field is not None, "resource_id_field must be set"
-        _get_resource(resource_id, current_tenant_id, self.resource_model)
+        _get_resource(resource_id, current_tenant_id, self.resource_model, session=session)
         current_key_count: int = (
-            db.session.scalar(
+            session.scalar(
                 select(func.count(ApiToken.id)).where(
                     ApiToken.type == self.resource_type, getattr(ApiToken, self.resource_id_field) == resource_id
                 )
@@ -112,15 +119,15 @@ class BaseApiKeyListResource(Resource):
                 custom="max_keys_exceeded",
             )
 
-        key = ApiToken.generate_api_key(self.token_prefix or "", 24)
+        key = ApiToken.generate_api_key(self.token_prefix or "", 24, session=session)
         assert self.resource_type is not None, "resource_type must be set"
         api_token = ApiToken()
         setattr(api_token, self.resource_id_field, resource_id)
         api_token.tenant_id = current_tenant_id
         api_token.token = key
         api_token.type = self.resource_type
-        db.session.add(api_token)
-        db.session.commit()
+        session.add(api_token)
+        session.commit()
         return api_token
 
 
@@ -131,10 +138,16 @@ class BaseApiKeyResource(Resource):
     resource_model: type | None = None
     resource_id_field: str | None = None
 
+    @with_session
     def delete(
-        self, resource_id: str, api_key_id: str, current_tenant_id: str, current_user: Account
+        self,
+        session: Session,
+        resource_id: str,
+        api_key_id: str,
+        current_tenant_id: str,
+        current_user: Account,
     ) -> tuple[str, int]:
-        self._delete_api_key(resource_id, api_key_id, current_tenant_id, current_user)
+        self._delete_api_key(resource_id, api_key_id, current_tenant_id, current_user, session=session)
         return "", 204
 
     def _delete_api_key(
@@ -143,14 +156,16 @@ class BaseApiKeyResource(Resource):
         api_key_id: str,
         current_tenant_id: str,
         current_user: Account,
+        *,
+        session: Session,
     ) -> None:
         assert self.resource_id_field is not None, "resource_id_field must be set"
-        _get_resource(resource_id, current_tenant_id, self.resource_model)
+        _get_resource(resource_id, current_tenant_id, self.resource_model, session=session)
 
         if not dify_config.RBAC_ENABLED and not current_user.is_admin_or_owner:
             raise Forbidden()
 
-        key = db.session.scalar(
+        key = session.scalar(
             select(ApiToken)
             .where(
                 getattr(ApiToken, self.resource_id_field) == resource_id,
@@ -168,8 +183,8 @@ class BaseApiKeyResource(Resource):
         assert key is not None  # nosec - for type checker only
         ApiTokenCache.delete(key.token, key.type)
 
-        db.session.execute(delete(ApiToken).where(ApiToken.id == api_key_id))
-        db.session.commit()
+        session.execute(delete(ApiToken).where(ApiToken.id == api_key_id))
+        session.commit()
 
 
 @console_ns.route("/apps/<uuid:resource_id>/api-keys")
@@ -179,9 +194,13 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc(params={"resource_id": "App ID"})
     @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
     @with_current_tenant_id
-    def get(self, current_tenant_id: str, resource_id: UUID) -> dict[str, object]:
+    @with_session(write=False)
+    def get(self, session: Session, current_tenant_id: str, resource_id: UUID) -> dict[str, object]:
         """Get all API keys for an app"""
-        return dump_response(ApiKeyList, self._get_api_key_list(str(resource_id), current_tenant_id))
+        return dump_response(
+            ApiKeyList,
+            self._get_api_key_list(str(resource_id), current_tenant_id, session=session),
+        )
 
     @console_ns.doc("create_app_api_key")
     @console_ns.doc(description="Create a new API key for an app")
@@ -191,9 +210,13 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @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]:
+    @with_session
+    def post(self, session: Session, current_tenant_id: str, resource_id: UUID) -> tuple[dict[str, object], int]:
         """Create a new API key for an app"""
-        return dump_response(ApiKeyItem, self._create_api_key(str(resource_id), current_tenant_id)), 201
+        return dump_response(
+            ApiKeyItem,
+            self._create_api_key(str(resource_id), current_tenant_id, session=session),
+        ), 201
 
     resource_type = ApiTokenType.APP
     resource_model = App
@@ -210,11 +233,23 @@ class AppApiKeyResource(BaseApiKeyResource):
     @with_current_user
     @with_current_tenant_id
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    @with_session
     def delete(
-        self, current_tenant_id: str, current_user: Account, resource_id: UUID, api_key_id: UUID
+        self,
+        session: Session,
+        current_tenant_id: str,
+        current_user: Account,
+        resource_id: UUID,
+        api_key_id: UUID,
     ) -> tuple[str, int]:
         """Delete an API key for an app"""
-        self._delete_api_key(str(resource_id), str(api_key_id), current_tenant_id, current_user)
+        self._delete_api_key(
+            str(resource_id),
+            str(api_key_id),
+            current_tenant_id,
+            current_user,
+            session=session,
+        )
         return "", 204
 
     resource_type = ApiTokenType.APP
@@ -229,9 +264,13 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc(params={"resource_id": "Dataset ID"})
     @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
     @with_current_tenant_id
-    def get(self, current_tenant_id: str, resource_id: UUID) -> dict[str, object]:
+    @with_session(write=False)
+    def get(self, session: Session, current_tenant_id: str, resource_id: UUID) -> dict[str, object]:
         """Get all API keys for a dataset"""
-        return dump_response(ApiKeyList, self._get_api_key_list(str(resource_id), current_tenant_id))
+        return dump_response(
+            ApiKeyList,
+            self._get_api_key_list(str(resource_id), current_tenant_id, session=session),
+        )
 
     @console_ns.doc("create_dataset_api_key")
     @console_ns.doc(description="Create a new API key for a dataset")
@@ -241,9 +280,13 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @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]:
+    @with_session
+    def post(self, session: Session, current_tenant_id: str, resource_id: UUID) -> tuple[dict[str, object], int]:
         """Create a new API key for a dataset"""
-        return dump_response(ApiKeyItem, self._create_api_key(str(resource_id), current_tenant_id)), 201
+        return dump_response(
+            ApiKeyItem,
+            self._create_api_key(str(resource_id), current_tenant_id, session=session),
+        ), 201
 
     resource_type = ApiTokenType.DATASET
     resource_model = Dataset
@@ -260,11 +303,23 @@ class DatasetApiKeyResource(BaseApiKeyResource):
     @with_current_user
     @with_current_tenant_id
     @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_API_KEY_MANAGE)
+    @with_session
     def delete(
-        self, current_tenant_id: str, current_user: Account, resource_id: UUID, api_key_id: UUID
+        self,
+        session: Session,
+        current_tenant_id: str,
+        current_user: Account,
+        resource_id: UUID,
+        api_key_id: UUID,
     ) -> tuple[str, int]:
         """Delete an API key for a dataset"""
-        self._delete_api_key(str(resource_id), str(api_key_id), current_tenant_id, current_user)
+        self._delete_api_key(
+            str(resource_id),
+            str(api_key_id),
+            current_tenant_id,
+            current_user,
+            session=session,
+        )
         return "", 204
 
     resource_type = ApiTokenType.DATASET

api/controllers/console/app/agent.py

@@ -5,6 +5,7 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
+from sqlalchemy.orm import Session
 
 from controllers.common.schema import (
     query_params_from_model,
@@ -12,6 +13,7 @@ from controllers.common.schema import (
     register_response_schema_models,
     register_schema_models,
 )
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
 from controllers.console.app.wraps import get_app_model
@@ -24,7 +26,6 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
-from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.helper import uuid_value
 from libs.login import login_required
@@ -169,23 +170,23 @@ register_response_schema_models(
 )
 
 
-def _resolve_agent_id(app_model: App, node_id: str | None) -> str | None:
+def _resolve_agent_id(session: Session, 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, session=db.session()
+            session=session, tenant_id=app_model.tenant_id, app_id=app_model.id, node_id=node_id
         )
-    return app_model.bound_agent_id
+    return app_model.bound_agent_id_with_session(session=session)
 
 
 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):
+def _upload_skill_for_app(*, session: Session, 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)
+    agent_id = _resolve_agent_id(session, app_model, query.node_id)
     if not agent_id:
         return _agent_not_bound()
     if "file" not in request.files:
@@ -202,22 +203,22 @@ def _upload_skill_for_app(*, current_user: Account, app_model: App):
             tenant_id=app_model.tenant_id,
             user_id=current_user.id,
             agent_id=agent_id,
-            session=db.session(),
+            session=session,
         )
     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):
+def _commit_drive_file_for_app(*, session: Session, 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)
+    agent_id = _resolve_agent_id(session, 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(
+    upload_file = session.scalar(
         select(UploadFile).where(
             UploadFile.id == payload.upload_file_id,
             UploadFile.tenant_id == app_model.tenant_id,
@@ -241,7 +242,7 @@ def _commit_drive_file_for_app(*, current_user: Account, app_model: App, allow_n
                     value_owned_by_drive=True,
                 )
             ],
-            session=db.session(),
+            session=session,
         )
     except AgentDriveError as exc:
         return {"code": exc.code, "message": exc.message}, exc.status_code
@@ -258,10 +259,10 @@ def _commit_drive_file_for_app(*, current_user: Account, app_model: App, allow_n
     }, 201
 
 
-def _delete_drive_file_for_app(*, current_user: Account, app_model: App, allow_node_id: bool = True):
+def _delete_drive_file_for_app(*, session: Session, 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)
+    agent_id = _resolve_agent_id(session, app_model, node_id)
     if not agent_id:
         return _agent_not_bound()
     try:
@@ -275,7 +276,7 @@ def _delete_drive_file_for_app(*, current_user: Account, app_model: App, allow_n
             user_id=current_user.id,
             agent_id=agent_id,
             items=[DriveCommitItem(key=key, file_ref=None)],
-            session=db.session(),
+            session=session,
         )
     except AgentDriveError as exc:
         return {"code": exc.code, "message": exc.message}, exc.status_code
@@ -283,10 +284,12 @@ def _delete_drive_file_for_app(*, current_user: Account, app_model: App, allow_n
     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):
+def _delete_skill_for_app(
+    *, session: Session, 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)
+    agent_id = _resolve_agent_id(session, app_model, node_id)
     if not agent_id:
         return _agent_not_bound()
     if "/" in slug or not slug.strip():
@@ -301,7 +304,7 @@ def _delete_skill_for_app(*, current_user: Account, app_model: App, slug: str, a
                 DriveCommitItem(key=f"{slug}/SKILL.md", file_ref=None),
                 DriveCommitItem(key=f"{slug}/.DIFY-SKILL-FULL.zip", file_ref=None),
             ],
-            session=db.session(),
+            session=session,
         )
     except AgentDriveError as exc:
         return {"code": exc.code, "message": exc.message}, exc.status_code
@@ -309,16 +312,16 @@ def _delete_skill_for_app(*, current_user: Account, app_model: App, slug: str, a
     return {"result": "success", "removed_keys": removed_keys}
 
 
-def _infer_skill_tools_for_app(*, app_model: App, slug: str):
+def _infer_skill_tools_for_app(*, session: Session, app_model: App, slug: str):
     query = query_params_from_request(AgentDriveMutationQuery)
-    agent_id = _resolve_agent_id(app_model, query.node_id)
+    agent_id = _resolve_agent_id(session, 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, session=db.session()
+            tenant_id=app_model.tenant_id, agent_id=agent_id, slug=slug, session=session
         )
     except SkillToolInferenceError as exc:
         return {"code": exc.code, "message": exc.message}, exc.status_code
@@ -336,12 +339,13 @@ class AgentLogApi(Resource):
     @login_required
     @account_initialization_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session(write=False)
     @get_app_model(mode=[AppMode.AGENT_CHAT])
-    def get(self, app_model: App):
+    def get(self, session: Session, 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, db.session())
+        return AgentService.get_agent_logs(app_model, args.conversation_id, args.message_id, session)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/skills/upload")
@@ -356,9 +360,10 @@ class AgentSkillUploadByAgentApi(Resource):
     @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_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
-        return _upload_skill_for_app(current_user=current_user, app_model=app_model)
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
+        return _upload_skill_for_app(session=session, current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/skills/upload")
@@ -378,11 +383,12 @@ class AgentSkillUploadApi(Resource):
     @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):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
+    def post(self, session: Session, 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)
+        return _upload_skill_for_app(session=session, current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/files")
@@ -399,9 +405,12 @@ class AgentDriveFilesByAgentApi(Resource):
     @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_runtime_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)
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
+        return _commit_drive_file_for_app(
+            session=session, 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")
@@ -412,9 +421,12 @@ class AgentDriveFilesByAgentApi(Resource):
     @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_runtime_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)
+    @with_session
+    def delete(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
+        return _delete_drive_file_for_app(
+            session=session, current_user=current_user, app_model=app_model, allow_node_id=False
+        )
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/files")
@@ -429,11 +441,12 @@ class AgentDriveFilesApi(Resource):
     @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):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
+    def post(self, session: Session, 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)
+        return _commit_drive_file_for_app(session=session, 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")
@@ -442,10 +455,11 @@ class AgentDriveFilesApi(Resource):
     @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)
+    @with_session
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
+    def delete(self, session: Session, current_user: Account, app_model: App):
+        return _delete_drive_file_for_app(session=session, current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/skills/<string:slug>")
@@ -459,9 +473,12 @@ class AgentSkillByAgentApi(Resource):
     @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_runtime_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)
+    @with_session
+    def delete(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, slug: str):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
+        return _delete_skill_for_app(
+            session=session, 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>")
@@ -479,10 +496,11 @@ class AgentSkillApi(Resource):
     @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)
+    @with_session
+    @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
+    def delete(self, session: Session, current_user: Account, app_model: App, slug: str):
+        return _delete_skill_for_app(session=session, current_user=current_user, app_model=app_model, slug=slug)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/skills/<string:slug>/infer-tools")
@@ -499,9 +517,10 @@ class AgentSkillInferToolsByAgentApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def post(self, tenant_id: str, agent_id: UUID, slug: str):
-        app_model = resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
-        return _infer_skill_tools_for_app(app_model=app_model, slug=slug)
+    @with_session(write=False)
+    def post(self, session: Session, tenant_id: str, agent_id: UUID, slug: str):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
+        return _infer_skill_tools_for_app(session=session, app_model=app_model, slug=slug)
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/skills/<string:slug>/infer-tools")
@@ -525,7 +544,8 @@ class AgentSkillInferToolsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_session(write=False)
     @get_app_model(mode=_WORKFLOW_AGENT_DRIVE_APP_MODES)
-    def post(self, app_model: App, slug: str):
+    def post(self, session: Session, 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)
+        return _infer_skill_tools_for_app(session=session, app_model=app_model, slug=slug)

api/controllers/console/app/agent_app_access.py

@@ -9,12 +9,13 @@ from uuid import UUID
 
 from flask_restx import Resource
 from pydantic import Field
+from sqlalchemy.orm import Session
 
 from controllers.common.schema import register_response_schema_models
+from controllers.common.session import with_session
 from controllers.console import console_ns
 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 services.agent.roster_service import AgentRosterService
@@ -55,9 +56,10 @@ class AgentAppReferencingWorkflowsResource(Resource):
     @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)
-        workflows = AgentRosterService(db.session).list_workflows_referencing_app_agent(
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
+        workflows = AgentRosterService(session).list_workflows_referencing_app_agent(
             tenant_id=tenant_id, app_id=app_model.id
         )
         return AgentReferencingWorkflowsResponse(

api/controllers/console/app/agent_app_feature.py

@@ -13,9 +13,11 @@ from uuid import UUID
 
 from flask_restx import Resource
 from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
 
 from controllers.common.fields import SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
 from controllers.console.wraps import (
@@ -29,7 +31,6 @@ from controllers.console.wraps import (
     with_current_user,
 )
 from events.app_event import app_model_config_was_updated
-from extensions.ext_database import db
 from libs.login import login_required
 from models import Account
 from models.agent_config_entities import (
@@ -85,17 +86,23 @@ class AgentAppFeatureConfigResource(Resource):
     @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_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(session=session, 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(),
+            session=session,
         )
 
-        app_model_config_was_updated.send(app_model, app_model_config=new_app_model_config)
+        app_model_config_was_updated.send(
+            app_model,
+            app_model_config=new_app_model_config,
+            session=session,
+        )
+        session.commit()
 
         return SimpleResultResponse(result="success").model_dump(mode="json")

api/controllers/console/app/agent_app_sandbox.py

@@ -14,6 +14,7 @@ from dify_agent.client import DifyAgentClientError, DifyAgentHTTPError, DifyAgen
 from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
 
 from controllers.common.schema import (
     query_params_from_model,
@@ -21,6 +22,7 @@ from controllers.common.schema import (
     register_response_schema_models,
     register_schema_models,
 )
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
 from controllers.console.app.wraps import get_app_model
@@ -153,8 +155,9 @@ class AgentAppSandboxInfoResource(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
-        app_model = resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxInfoQuery)
         try:
             result = AgentAppSandboxService().get_info(
@@ -177,8 +180,9 @@ class AgentAppSandboxListResource(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
-        app_model = resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxListQuery)
         try:
             result = AgentAppSandboxService().list_files(
@@ -202,8 +206,9 @@ class AgentAppSandboxReadResource(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
-        app_model = resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxFileQuery)
         try:
             result = AgentAppSandboxService().read_file(
@@ -227,8 +232,9 @@ class AgentAppSandboxUploadResource(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def post(self, tenant_id: str, agent_id: UUID):
-        app_model = resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def post(self, session: Session, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         payload = AgentSandboxUploadPayload.model_validate(request.get_json(silent=True) or {})
         try:
             result = AgentAppSandboxService().upload_file(

api/controllers/console/app/agent_config_inspector.py

@@ -13,6 +13,7 @@ from uuid import UUID
 from flask import Response, request, send_file, url_for
 from flask_restx import Resource
 from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
 
 from controllers.common.schema import (
     query_params_from_model,
@@ -20,6 +21,7 @@ from controllers.common.schema import (
     register_response_schema_models,
     register_schema_models,
 )
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
 from controllers.console.app.wraps import get_app_model
@@ -33,7 +35,6 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
-from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.login import login_required
 from models.account import Account
@@ -99,6 +100,7 @@ class AgentConfigSkillItemResponse(ResponseModel):
     id: str
     name: str
     file_id: str | None = None
+    is_missing: bool = False
     description: str = ""
     size: int | None = None
     mime_type: str | None = None
@@ -109,6 +111,7 @@ class AgentConfigFileItemResponse(ResponseModel):
     id: str
     name: str
     file_id: str | None = None
+    is_missing: bool = False
     size: int | None = None
     mime_type: str | None = None
     hash: str | None = None
@@ -247,15 +250,15 @@ def _service() -> AgentConfigService:
     return AgentConfigService()
 
 
-def _resolve_agent_id(app_model: App, node_id: str | None) -> str | None:
+def _resolve_agent_id(session: Session, app_model: App, node_id: str | None) -> str | None:
     if node_id:
         return AgentComposerService.resolve_workflow_node_agent_id(
+            session=session,
             tenant_id=app_model.tenant_id,
             app_id=app_model.id,
             node_id=node_id,
-            session=db.session(),
         )
-    return app_model.bound_agent_id
+    return app_model.bound_agent_id_with_session(session=session)
 
 
 def _agent_not_bound() -> tuple[dict[str, object], int]:
@@ -275,6 +278,7 @@ def _json_response(data: Mapping[str, Any]) -> Response:
 
 def _resolve_console_version(
     *,
+    session: Session,
     tenant_id: str,
     agent_id: str,
     account_id: str,
@@ -286,26 +290,24 @@ def _resolve_console_version(
     try:
         if draft_type == "debug_build":
             state = AgentComposerService.load_agent_app_build_draft(
+                session=session,
                 tenant_id=tenant_id,
                 agent_id=agent_id,
                 account_id=account_id,
-                session=db.session(),
             )
             draft = state.get("draft") or {}
             draft_id = draft.get("id")
             if isinstance(draft_id, str) and draft_id:
                 return draft_id, AgentConfigVersionKind.BUILD_DRAFT
         else:
-            state = AgentComposerService.load_agent_composer(
-                tenant_id=tenant_id, agent_id=agent_id, session=db.session()
-            )
+            state = AgentComposerService.load_agent_composer(session=session, tenant_id=tenant_id, agent_id=agent_id)
             draft = state.get("draft") or {}
             draft_id = draft.get("id")
             if isinstance(draft_id, str) and draft_id:
                 # load_agent_composer creates the normal draft on first access.
                 # Config asset services use their own SQLAlchemy session, so the
                 # draft must be visible before we hand its id across that boundary.
-                db.session.commit()
+                session.commit()
                 return draft_id, AgentConfigVersionKind.DRAFT
     except AgentVersionNotFoundError as exc:
         raise AgentConfigServiceError(
@@ -322,6 +324,7 @@ def _resolve_console_version(
 
 def _resolve_target(
     *,
+    session: Session,
     tenant_id: str,
     agent_id: str,
     account_id: str,
@@ -329,6 +332,7 @@ def _resolve_target(
     draft_type: str | None,
 ) -> _ResolvedConsoleTarget:
     resolved_version_id, version_kind = _resolve_console_version(
+        session=session,
         tenant_id=tenant_id,
         agent_id=agent_id,
         account_id=account_id,
@@ -346,13 +350,15 @@ def _resolve_target(
 
 def _resolve_agent_route_target(
     *,
+    session: Session,
     tenant_id: str,
     agent_id: UUID,
     current_user: Account,
     query: AgentConfigByAgentQuery,
 ) -> _ResolvedConsoleTarget:
-    resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
     return _resolve_target(
+        session=session,
         tenant_id=tenant_id,
         agent_id=str(agent_id),
         account_id=current_user.id,
@@ -363,14 +369,16 @@ def _resolve_agent_route_target(
 
 def _resolve_app_route_target(
     *,
+    session: Session,
     app_model: App,
     current_user: Account,
     query: AgentConfigQuery,
 ) -> _ResolvedConsoleTarget | tuple[dict[str, object], int]:
-    agent_id = _resolve_agent_id(app_model, query.node_id)
+    agent_id = _resolve_agent_id(session, app_model, query.node_id)
     if not agent_id:
         return _agent_not_bound()
     return _resolve_target(
+        session=session,
         tenant_id=app_model.tenant_id,
         agent_id=agent_id,
         account_id=current_user.id,
@@ -381,6 +389,7 @@ def _resolve_app_route_target(
 
 def _with_agent_route_target(
     *,
+    session: Session,
     tenant_id: str,
     agent_id: UUID,
     current_user: Account,
@@ -389,6 +398,7 @@ def _with_agent_route_target(
     query = query_params_from_request(AgentConfigByAgentQuery)
     try:
         target = _resolve_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -401,13 +411,14 @@ def _with_agent_route_target(
 
 def _with_app_route_target(
     *,
+    session: Session,
     app_model: App,
     current_user: Account,
     action: Callable[[_ResolvedConsoleTarget], Any],
 ) -> Any:
     query = query_params_from_request(AgentConfigQuery)
     try:
-        target = _resolve_app_route_target(app_model=app_model, current_user=current_user, query=query)
+        target = _resolve_app_route_target(session=session, app_model=app_model, current_user=current_user, query=query)
         if isinstance(target, tuple):
             return target
         return action(target)
@@ -649,8 +660,10 @@ class AgentConfigManifestByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -666,10 +679,13 @@ class AgentConfigManifestApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App):
-        return _with_app_route_target(app_model=app_model, current_user=current_user, action=_manifest_response)
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App):
+        return _with_app_route_target(
+            session=session, app_model=app_model, current_user=current_user, action=_manifest_response
+        )
 
 
 @console_ns.route("/agent/<uuid:agent_id>/config/skills/upload")
@@ -689,8 +705,10 @@ class AgentConfigSkillUploadByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -715,10 +733,13 @@ class AgentConfigSkillUploadApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def post(self, current_user: Account, app_model: App):
-        return _with_app_route_target(app_model=app_model, current_user=current_user, action=_skill_upload_response)
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def post(self, session: Session, current_user: Account, app_model: App):
+        return _with_app_route_target(
+            session=session, app_model=app_model, current_user=current_user, action=_skill_upload_response
+        )
 
 
 @console_ns.route("/agent/<uuid:agent_id>/config/skills")
@@ -731,8 +752,10 @@ class AgentConfigSkillsByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -748,10 +771,13 @@ class AgentConfigSkillsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App):
-        return _with_app_route_target(app_model=app_model, current_user=current_user, action=_skill_list_response)
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App):
+        return _with_app_route_target(
+            session=session, app_model=app_model, current_user=current_user, action=_skill_list_response
+        )
 
 
 @console_ns.route("/agent/<uuid:agent_id>/config/files")
@@ -764,8 +790,10 @@ class AgentConfigFilesByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -781,9 +809,11 @@ class AgentConfigFilesByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+    @with_session
+    def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         payload = AgentConfigFileUploadPayload.model_validate(console_ns.payload or {})
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -799,10 +829,13 @@ class AgentConfigFilesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App):
-        return _with_app_route_target(app_model=app_model, current_user=current_user, action=_file_list_response)
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App):
+        return _with_app_route_target(
+            session=session, app_model=app_model, current_user=current_user, action=_file_list_response
+        )
 
     @console_ns.doc("upload_agent_config_file")
     @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentConfigQuery)})
@@ -813,11 +846,13 @@ class AgentConfigFilesApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def post(self, current_user: Account, app_model: App):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def post(self, session: Session, current_user: Account, app_model: App):
         payload = AgentConfigFileUploadPayload.model_validate(console_ns.payload or {})
         return _with_app_route_target(
+            session=session,
             app_model=app_model,
             current_user=current_user,
             action=lambda target: _file_upload_response(target, payload),
@@ -836,8 +871,10 @@ class AgentConfigSkillInspectByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -855,10 +892,12 @@ class AgentConfigSkillInspectApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App, name: str):
         return _with_app_route_target(
+            session=session,
             app_model=app_model,
             current_user=current_user,
             action=lambda target: _skill_inspect_response(target, name),
@@ -883,10 +922,12 @@ class AgentConfigSkillFilePreviewByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         query = query_params_from_request(AgentConfigSkillFileByAgentQuery)
         try:
             target = _resolve_agent_route_target(
+                session=session,
                 tenant_id=tenant_id,
                 agent_id=agent_id,
                 current_user=current_user,
@@ -913,12 +954,15 @@ class AgentConfigSkillFilePreviewApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App, name: str):
         query = query_params_from_request(AgentConfigSkillFileQuery)
         try:
-            target = _resolve_app_route_target(app_model=app_model, current_user=current_user, query=query)
+            target = _resolve_app_route_target(
+                session=session, app_model=app_model, current_user=current_user, query=query
+            )
             if isinstance(target, tuple):
                 return target
             return _skill_file_preview_response(target, name, query.path)
@@ -938,8 +982,10 @@ class AgentConfigSkillDownloadByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -957,10 +1003,12 @@ class AgentConfigSkillDownloadApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App, name: str):
         return _with_app_route_target(
+            session=session,
             app_model=app_model,
             current_user=current_user,
             action=lambda target: _skill_download_response(target, name),
@@ -983,10 +1031,12 @@ class AgentConfigSkillFileDownloadByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         query = query_params_from_request(AgentConfigSkillFileByAgentQuery)
         try:
             target = _resolve_agent_route_target(
+                session=session,
                 tenant_id=tenant_id,
                 agent_id=agent_id,
                 current_user=current_user,
@@ -1017,12 +1067,15 @@ class AgentConfigSkillFileDownloadApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App, name: str):
         query = query_params_from_request(AgentConfigSkillFileQuery)
         try:
-            target = _resolve_app_route_target(app_model=app_model, current_user=current_user, query=query)
+            target = _resolve_app_route_target(
+                session=session, app_model=app_model, current_user=current_user, query=query
+            )
             if isinstance(target, tuple):
                 return target
             return _skill_file_download_response(
@@ -1047,10 +1100,12 @@ class AgentConfigSkillFileDownloadContentByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         query = query_params_from_request(AgentConfigSkillFileByAgentQuery)
         try:
             target = _resolve_agent_route_target(
+                session=session,
                 tenant_id=tenant_id,
                 agent_id=agent_id,
                 current_user=current_user,
@@ -1069,12 +1124,15 @@ class AgentConfigSkillFileDownloadContentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App, name: str):
         query = query_params_from_request(AgentConfigSkillFileQuery)
         try:
-            target = _resolve_app_route_target(app_model=app_model, current_user=current_user, query=query)
+            target = _resolve_app_route_target(
+                session=session, app_model=app_model, current_user=current_user, query=query
+            )
             if isinstance(target, tuple):
                 return target
             return _skill_file_raw_download_response(target, name, query.path)
@@ -1094,8 +1152,10 @@ class AgentConfigSkillByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def delete(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def delete(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -1115,10 +1175,12 @@ class AgentConfigSkillApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def delete(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def delete(self, session: Session, current_user: Account, app_model: App, name: str):
         return _with_app_route_target(
+            session=session,
             app_model=app_model,
             current_user=current_user,
             action=lambda target: _skill_delete_response(target, name),
@@ -1137,8 +1199,10 @@ class AgentConfigFilePreviewByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -1156,10 +1220,12 @@ class AgentConfigFilePreviewApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App, name: str):
         return _with_app_route_target(
+            session=session,
             app_model=app_model,
             current_user=current_user,
             action=lambda target: _file_preview_response(target, name),
@@ -1178,8 +1244,10 @@ class AgentConfigFileDownloadByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def get(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -1197,10 +1265,12 @@ class AgentConfigFileDownloadApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def get(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def get(self, session: Session, current_user: Account, app_model: App, name: str):
         return _with_app_route_target(
+            session=session,
             app_model=app_model,
             current_user=current_user,
             action=lambda target: _file_download_response(target, name),
@@ -1219,8 +1289,10 @@ class AgentConfigFileByAgentApi(Resource):
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id
-    def delete(self, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
+    @with_session
+    def delete(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, name: str):
         return _with_agent_route_target(
+            session=session,
             tenant_id=tenant_id,
             agent_id=agent_id,
             current_user=current_user,
@@ -1240,10 +1312,12 @@ class AgentConfigFileApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @get_app_model(mode=_WORKFLOW_APP_MODES)
     @with_current_user
-    def delete(self, current_user: Account, app_model: App, name: str):
+    @with_session
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
+    def delete(self, session: Session, current_user: Account, app_model: App, name: str):
         return _with_app_route_target(
+            session=session,
             app_model=app_model,
             current_user=current_user,
             action=lambda target: _file_delete_response(target, name),

api/controllers/console/app/agent_drive_inspector.py

@@ -18,17 +18,18 @@ from uuid import UUID
 from flask import Response
 from flask_restx import Resource
 from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
 
 from controllers.common.schema import (
     query_params_from_model,
     query_params_from_request,
     register_response_schema_models,
 )
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_tenant_id
-from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.login import login_required
 from models.model import App, AppMode
@@ -144,13 +145,13 @@ register_response_schema_models(
 )
 
 
-def _resolve_agent_id(app_model: App, node_id: str | None) -> str | None:
+def _resolve_agent_id(session: Session, 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, session=db.session()
+            session=session, tenant_id=app_model.tenant_id, app_id=app_model.id, node_id=node_id
         )
-    return app_model.bound_agent_id
+    return app_model.bound_agent_id_with_session(session=session)
 
 
 def _agent_not_bound() -> tuple[dict[str, object], int]:
@@ -181,12 +182,13 @@ class AgentDriveListByAgentApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
         query = query_params_from_request(AgentDriveListByAgentQuery)
-        resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         try:
             items = AgentDriveService().manifest(
-                tenant_id=tenant_id, agent_id=str(agent_id), prefix=query.prefix, session=db.session()
+                tenant_id=tenant_id, agent_id=str(agent_id), prefix=query.prefix, session=session
             )
         except AgentDriveError as exc:
             return _handle(exc)
@@ -203,10 +205,11 @@ class AgentDriveSkillListByAgentApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
-        resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
+        resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         try:
-            items = AgentDriveService().list_skills(tenant_id=tenant_id, agent_id=str(agent_id), session=db.session())
+            items = AgentDriveService().list_skills(tenant_id=tenant_id, agent_id=str(agent_id), session=session)
         except AgentDriveError as exc:
             return _handle(exc)
         return {"items": items}
@@ -222,15 +225,16 @@ class AgentDriveSkillInspectByAgentApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID, skill_path: str):
-        resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID, skill_path: str):
+        resolve_agent_runtime_app_model(session=session, 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,
-                    session=db.session(),
+                    session=session,
                 )
             )
         except AgentDriveError as exc:
@@ -247,12 +251,13 @@ class AgentDrivePreviewByAgentApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
         query = query_params_from_request(AgentDriveFileByAgentQuery)
-        resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         try:
             return AgentDriveService().preview(
-                tenant_id=tenant_id, agent_id=str(agent_id), key=query.key, session=db.session()
+                tenant_id=tenant_id, agent_id=str(agent_id), key=query.key, session=session
             )
         except AgentDriveError as exc:
             return _handle(exc)
@@ -268,12 +273,13 @@ class AgentDriveDownloadByAgentApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
         query = query_params_from_request(AgentDriveFileByAgentQuery)
-        resolve_agent_runtime_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        resolve_agent_runtime_app_model(session=session, 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, session=db.session()
+                tenant_id=tenant_id, agent_id=str(agent_id), key=query.key, session=session
             )
         except AgentDriveError as exc:
             return _handle(exc)
@@ -289,15 +295,16 @@ class AgentDriveListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_session(write=False)
     @get_app_model(mode=_WORKFLOW_APP_MODES)
-    def get(self, app_model: App):
+    def get(self, session: Session, app_model: App):
         query = query_params_from_request(AgentDriveListQuery)
-        agent_id = _resolve_agent_id(app_model, query.node_id)
+        agent_id = _resolve_agent_id(session, 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, session=db.session()
+                tenant_id=app_model.tenant_id, agent_id=agent_id, prefix=query.prefix, session=session
             )
         except AgentDriveError as exc:
             return _handle(exc)
@@ -315,16 +322,15 @@ class AgentDriveSkillListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_session(write=False)
     @get_app_model(mode=_WORKFLOW_APP_MODES)
-    def get(self, app_model: App):
+    def get(self, session: Session, app_model: App):
         query = query_params_from_request(AgentDriveListQuery)
-        agent_id = _resolve_agent_id(app_model, query.node_id)
+        agent_id = _resolve_agent_id(session, 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, session=db.session()
-            )
+            items = AgentDriveService().list_skills(tenant_id=app_model.tenant_id, agent_id=agent_id, session=session)
         except AgentDriveError as exc:
             return _handle(exc)
         return {"items": items}
@@ -345,10 +351,11 @@ class AgentDriveSkillInspectApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_session(write=False)
     @get_app_model(mode=_WORKFLOW_APP_MODES)
-    def get(self, app_model: App, skill_path: str):
+    def get(self, session: Session, app_model: App, skill_path: str):
         query = query_params_from_request(AgentDriveSkillInspectQuery)
-        agent_id = _resolve_agent_id(app_model, query.node_id)
+        agent_id = _resolve_agent_id(session, app_model, query.node_id)
         if not agent_id:
             return _agent_not_bound()
         try:
@@ -357,7 +364,7 @@ class AgentDriveSkillInspectApi(Resource):
                     tenant_id=app_model.tenant_id,
                     agent_id=agent_id,
                     skill_path=skill_path,
-                    session=db.session(),
+                    session=session,
                 )
             )
         except AgentDriveError as exc:
@@ -373,15 +380,16 @@ class AgentDrivePreviewApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_session(write=False)
     @get_app_model(mode=_WORKFLOW_APP_MODES)
-    def get(self, app_model: App):
+    def get(self, session: Session, app_model: App):
         query = query_params_from_request(AgentDriveFileQuery)
-        agent_id = _resolve_agent_id(app_model, query.node_id)
+        agent_id = _resolve_agent_id(session, 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, session=db.session()
+                tenant_id=app_model.tenant_id, agent_id=agent_id, key=query.key, session=session
             )
         except AgentDriveError as exc:
             return _handle(exc)
@@ -396,15 +404,16 @@ class AgentDriveDownloadApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_session(write=False)
     @get_app_model(mode=_WORKFLOW_APP_MODES)
-    def get(self, app_model: App):
+    def get(self, session: Session, app_model: App):
         query = query_params_from_request(AgentDriveFileQuery)
-        agent_id = _resolve_agent_id(app_model, query.node_id)
+        agent_id = _resolve_agent_id(session, 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, session=db.session()
+                tenant_id=app_model.tenant_id, agent_id=agent_id, key=query.key, session=session
             )
         except AgentDriveError as exc:
             return _handle(exc)

api/controllers/console/app/annotation.py

@@ -5,10 +5,12 @@ from flask import abort, request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, TypeAdapter, field_validator
 from sqlalchemy import select
+from sqlalchemy.orm import Session
 from werkzeug.exceptions import NotFound
 
 from controllers.common.errors import NoFileUploadedError, TooManyFilesError
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.wraps import (
     RBACPermission,
@@ -21,7 +23,6 @@ from controllers.console.wraps import (
     rbac_permission_required,
     setup_required,
 )
-from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from fields.annotation_fields import (
     Annotation,
@@ -46,9 +47,9 @@ from services.annotation_service import (
 from services.app_ref_service import AppRef, AppRefService
 
 
-def _get_app_ref(app_id: str) -> AppRef:
+def _get_app_ref(session: Session, app_id: str) -> AppRef:
     _, current_tenant_id = current_account_with_tenant()
-    app = db.session.scalar(
+    app = session.scalar(
         select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
     )
     if app is None:
@@ -210,8 +211,9 @@ class AppAnnotationSettingDetailApi(Resource):
     @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), session=db.session())
+    @with_session(write=False)
+    def get(self, session: Session, app_id: UUID):
+        result = AppAnnotationService.get_app_annotation_setting_by_app_id(str(app_id), session)
         return dump_response(AnnotationSettingResponse, result), 200
 
 
@@ -228,14 +230,15 @@ class AppAnnotationSettingUpdateApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    def post(self, app_id: UUID, annotation_setting_id: UUID):
+    @with_session
+    def post(self, session: Session, app_id: UUID, annotation_setting_id: UUID):
         annotation_setting_id_str = str(annotation_setting_id)
 
         args = AnnotationSettingUpdatePayload.model_validate(console_ns.payload)
 
         setting_args: UpdateAnnotationSettingArgs = {"score_threshold": args.score_threshold}
         result = AppAnnotationService.update_app_annotation_setting(
-            str(app_id), annotation_setting_id_str, setting_args, session=db.session()
+            str(app_id), annotation_setting_id_str, setting_args, session
         )
         return dump_response(AnnotationSettingResponse, result), 200
 
@@ -286,14 +289,15 @@ class AnnotationApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
-    def get(self, app_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, app_id: UUID):
         args = AnnotationListQuery.model_validate(request.args.to_dict(flat=True))
         page = args.page
         limit = args.limit
         keyword = args.keyword
 
         annotation_list, total = AppAnnotationService.get_annotation_list_by_app_id(
-            str(app_id), page, limit, keyword, session=db.session()
+            str(app_id), page, limit, keyword, session
         )
         annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
         return AnnotationList(
@@ -312,7 +316,8 @@ class AnnotationApi(Resource):
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    def post(self, app_id: UUID):
+    @with_session
+    def post(self, session: Session, app_id: UUID):
         args = CreateAnnotationPayload.model_validate(console_ns.payload)
         upsert_args: UpsertAnnotationArgs = {}
         if args.answer is not None:
@@ -323,9 +328,7 @@ class AnnotationApi(Resource):
             upsert_args["message_id"] = args.message_id
         if args.question is not None:
             upsert_args["question"] = args.question
-        annotation = AppAnnotationService.up_insert_app_annotation_from_message(
-            upsert_args, str(app_id), session=db.session()
-        )
+        annotation = AppAnnotationService.up_insert_app_annotation_from_message(upsert_args, str(app_id), session)
         return dump_response(Annotation, annotation), 201
 
     @setup_required
@@ -334,7 +337,8 @@ class AnnotationApi(Resource):
     @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):
+    @with_session
+    def delete(self, session: Session, app_id: UUID):
 
         # Use request.args.getlist to get annotation_ids array directly
         annotation_ids = request.args.getlist("annotation_id")
@@ -348,12 +352,12 @@ class AnnotationApi(Resource):
                     "message": "annotation_ids are required if the parameter is provided.",
                 }, 400
 
-            app_ref = _get_app_ref(str(app_id))
-            AppAnnotationService.delete_app_annotations_in_batch(app_ref, annotation_ids, session=db.session())
+            app_ref = _get_app_ref(session, str(app_id))
+            AppAnnotationService.delete_app_annotations_in_batch(app_ref, annotation_ids, session)
             return "", 204
         # If no annotation_ids are provided, handle clearing all annotations
         else:
-            AppAnnotationService.clear_all_annotations(str(app_id), session=db.session())
+            AppAnnotationService.clear_all_annotations(str(app_id), session)
             return "", 204
 
 
@@ -373,8 +377,9 @@ class AnnotationExportApi(Resource):
     @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), session=db.session())
+    @with_session(write=False)
+    def get(self, session: Session, app_id: UUID):
+        annotation_list = AppAnnotationService.export_annotation_list_by_app_id(str(app_id), session)
         annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
         return (
             AnnotationExportList(data=annotation_models).model_dump(mode="json"),
@@ -401,16 +406,17 @@ class AnnotationUpdateDeleteApi(Resource):
     @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):
+    @with_session
+    def post(self, session: Session, app_id: UUID, annotation_id: UUID):
         args = UpdateAnnotationPayload.model_validate(console_ns.payload)
         update_args: UpdateAnnotationArgs = {}
         if args.answer is not None:
             update_args["answer"] = args.answer
         if args.question is not None:
             update_args["question"] = args.question
-        app_ref = _get_app_ref(str(app_id))
+        app_ref = _get_app_ref(session, str(app_id))
         annotation_ref = AppRefService.create_annotation_ref(app_ref, str(annotation_id))
-        annotation = AppAnnotationService.update_app_annotation_directly(update_args, annotation_ref, db.session())
+        annotation = AppAnnotationService.update_app_annotation_directly(update_args, annotation_ref, session)
         return Annotation.model_validate(annotation, from_attributes=True).model_dump(mode="json")
 
     @setup_required
@@ -419,10 +425,11 @@ class AnnotationUpdateDeleteApi(Resource):
     @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):
-        app_ref = _get_app_ref(str(app_id))
+    @with_session
+    def delete(self, session: Session, app_id: UUID, annotation_id: UUID):
+        app_ref = _get_app_ref(session, str(app_id))
         annotation_ref = AppRefService.create_annotation_ref(app_ref, str(annotation_id))
-        AppAnnotationService.delete_app_annotation(annotation_ref, db.session())
+        AppAnnotationService.delete_app_annotation(annotation_ref, session)
         return "", 204
 
 
@@ -446,7 +453,8 @@ class AnnotationBatchImportApi(Resource):
     @annotation_import_concurrency_limit
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    def post(self, app_id: UUID):
+    @with_session
+    def post(self, session: Session, app_id: UUID):
         from configs import dify_config
 
         # check file
@@ -481,7 +489,7 @@ class AnnotationBatchImportApi(Resource):
 
         return dump_response(
             AnnotationBatchImportResponse,
-            AppAnnotationService.batch_import_app_annotations(str(app_id), file, session=db.session()),
+            AppAnnotationService.batch_import_app_annotations(str(app_id), file, session),
         )
 
 
@@ -533,16 +541,17 @@ class AnnotationHitHistoryListApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
-    def get(self, app_id: UUID, annotation_id: UUID):
+    @with_session(write=False)
+    def get(self, session: Session, app_id: UUID, annotation_id: UUID):
         page = request.args.get("page", default=1, type=int)
         limit = request.args.get("limit", default=20, type=int)
-        app_ref = _get_app_ref(str(app_id))
+        app_ref = _get_app_ref(session, str(app_id))
         annotation_ref = AppRefService.create_annotation_ref(app_ref, str(annotation_id))
         annotation_hit_history_list, total = AppAnnotationService.get_annotation_hit_histories(
             annotation_ref,
             page,
             limit,
-            session=db.session(),
+            session,
         )
         history_models = TypeAdapter(list[AnnotationHitHistory]).validate_python(
             annotation_hit_history_list, from_attributes=True

api/controllers/console/app/app.py

@@ -6,7 +6,7 @@ from typing import Any, Literal
 
 from flask import request
 from flask_restx import Resource
-from pydantic import AliasChoices, BaseModel, Field, computed_field, field_validator
+from pydantic import AliasChoices, BaseModel, Field, ValidationInfo, computed_field, field_validator, model_validator
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 from werkzeug.exceptions import BadRequest, NotFound
@@ -42,6 +42,7 @@ from controllers.console.wraps import (
 from core.ops.ops_trace_manager import OpsTraceManager
 from core.rag.entities import PreProcessingRule, Rule, Segmentation
 from core.rag.retrieval.retrieval_methods import RetrievalMethod
+from core.rbac import RBACResourceWhitelistScope
 from core.trigger.constants import TRIGGER_NODE_TYPES
 from extensions.ext_database import db
 from fields.base import ResponseModel
@@ -51,10 +52,17 @@ from libs.login import login_required
 from models import Account, App, DatasetPermissionEnum, Workflow
 from models.model import IconType
 from services.app_dsl_service import AppDslService
-from services.app_service import AppListParams, AppListSortBy, AppService, CreateAppParams, StarredAppListParams
+from services.app_service import (
+    AppListParams,
+    AppListSortBy,
+    AppResponseView,
+    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.dsl_entities import DslImportWarning, ImportMode, ImportStatus
 from services.entities.knowledge_entities.knowledge_entities import (
     DataSource,
     InfoList,
@@ -68,6 +76,7 @@ from services.entities.knowledge_entities.knowledge_entities import (
     WeightVectorSetting,
 )
 from services.feature_service import FeatureService
+from tasks.initialize_created_app_rbac_access_task import initialize_created_app_rbac_access_task
 
 ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "advanced-chat", "workflow", "completion"]
 
@@ -346,7 +355,18 @@ class DeletedTool(ResponseModel):
     provider_id: str
 
 
-class AppPartial(ResponseModel):
+class AppResponseModel(ResponseModel):
+    @model_validator(mode="before")
+    @classmethod
+    def _use_request_session(cls, value: Any, info: ValidationInfo) -> Any:
+        if not isinstance(value, App):
+            return value
+        if info.context is None or "session" not in info.context:
+            raise ValueError("session context is required to serialize an App")
+        return AppResponseView(value, session=info.context["session"])
+
+
+class AppPartial(AppResponseModel):
     id: str
     name: str
     max_active_requests: int | None = None
@@ -390,7 +410,7 @@ class AppPartial(ResponseModel):
         return to_timestamp(value)
 
 
-class AppDetail(ResponseModel):
+class AppDetail(AppResponseModel):
     id: str
     name: str
     description: str | None = None
@@ -459,6 +479,7 @@ class AppImportResponse(ResponseModel):
     current_dsl_version: str
     imported_dsl_version: str = ""
     error: str = ""
+    warnings: list[DslImportWarning] = Field(default_factory=list)
 
 
 def _enrich_app_list_items(session: Session, *, apps: Sequence[App], tenant_id: str) -> None:
@@ -584,12 +605,13 @@ class AppListApi(Resource):
         permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
             str(current_tenant_id),
             current_user_id,
-            session=db.session(),
+            session=session,
         )
         if dify_config.RBAC_ENABLED:
             access_filter = resolve_app_access_filter(
                 str(current_tenant_id),
                 current_user_id,
+                session=session,
                 permissions=permissions,
             )
             access_filter.apply_to_params(params)
@@ -605,7 +627,11 @@ class AppListApi(Resource):
         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)
+        pagination_model = AppPagination.model_validate(
+            app_pagination,
+            from_attributes=True,
+            context={"session": session},
+        )
         if app_pagination.items:
             pagination_model = pagination_model.model_copy(
                 update={
@@ -631,7 +657,8 @@ class AppListApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    def post(self, current_tenant_id: str, current_user: Account):
+    @with_session
+    def post(self, session: Session, current_tenant_id: str, current_user: Account):
         """Create app"""
         args = CreateAppPayload.model_validate(console_ns.payload)
         params = CreateAppParams(
@@ -644,16 +671,26 @@ class AppListApi(Resource):
         )
 
         app_service = AppService()
-        app = app_service.create_app(current_tenant_id, params, current_user, session=db.session())
+        app = app_service.create_app(current_tenant_id, params, current_user, session=session)
+        if dify_config.RBAC_ENABLED:
+            enterprise_rbac_service.RBACService.AppAccess.replace_whitelist(
+                tenant_id=str(current_tenant_id),
+                account_id=current_user.id,
+                app_id=str(app.id),
+                payload=enterprise_rbac_service.ReplaceMemberBindings(scope=RBACResourceWhitelistScope.ALL),
+            )
+            initialize_created_app_rbac_access_task.delay(current_tenant_id, current_user.id, app_id=app.id)
         permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(
             str(current_tenant_id),
             current_user.id,
             [str(app.id)],
-            session=db.session(),
-        )
-        app_detail = AppDetailWithSite.model_validate(app, from_attributes=True).model_copy(
-            update={"permission_keys": permission_keys_map.get(str(app.id), [])}
+            session=session,
         )
+        app_detail = AppDetailWithSite.model_validate(
+            app,
+            from_attributes=True,
+            context={"session": session},
+        ).model_copy(update={"permission_keys": permission_keys_map.get(str(app.id), [])})
         return app_detail.model_dump(mode="json"), 201
 
 
@@ -689,7 +726,14 @@ class StarredAppListApi(Resource):
             return empty.model_dump(mode="json"), 200
 
         _enrich_app_list_items(session, apps=app_pagination.items, tenant_id=current_tenant_id)
-        return AppPagination.model_validate(app_pagination, from_attributes=True).model_dump(mode="json"), 200
+        return (
+            AppPagination.model_validate(
+                app_pagination,
+                from_attributes=True,
+                context={"session": session},
+            ).model_dump(mode="json"),
+            200,
+        )
 
 
 @console_ns.route("/apps/<uuid:app_id>/star")
@@ -740,12 +784,13 @@ class AppApi(Resource):
     @with_current_user
     @with_current_tenant_id
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session(write=False)
     @get_app_model(mode=None)
-    def get(self, current_tenant_id: str, current_user: Account, app_model: App):
+    def get(self, session: Session, current_tenant_id: str, current_user: Account, app_model: App):
         """Get app detail"""
         app_service = AppService()
 
-        app_model = app_service.get_app(app_model)
+        app_model = app_service.get_app(app_model, session=session)
 
         if FeatureService.get_system_features().webapp_auth.enabled:
             app_setting = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_id=str(app_model.id))
@@ -755,13 +800,15 @@ class AppApi(Resource):
             str(current_tenant_id),
             current_user.id,
             app_id=str(app_model.id),
-            session=db.session(),
+            session=session,
         )
         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), [])}
-        )
+        response_model = AppDetailWithSite.model_validate(
+            app_model,
+            from_attributes=True,
+            context={"session": session},
+        ).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")
@@ -776,8 +823,9 @@ class AppApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @with_session
     @get_app_model(mode=None)
-    def put(self, app_model: App):
+    def put(self, session: Session, app_model: App):
         """Update app"""
         args = UpdateAppPayload.model_validate(console_ns.payload)
 
@@ -792,8 +840,12 @@ class AppApi(Resource):
             "use_icon_as_answer_icon": args.use_icon_as_answer_icon or False,
             "max_active_requests": args.max_active_requests or 0,
         }
-        app_model = app_service.update_app(app_model, args_dict, session=db.session())
-        return dump_response(AppDetailWithSite, app_model)
+        app_model = app_service.update_app(app_model, args_dict, session=session)
+        return AppDetailWithSite.model_validate(
+            app_model,
+            from_attributes=True,
+            context={"session": session},
+        ).model_dump(mode="json")
 
     @console_ns.doc("delete_app")
     @console_ns.doc(description="Delete application")
@@ -805,11 +857,12 @@ class AppApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_DELETE)
+    @with_session
     @get_app_model
-    def delete(self, app_model: App):
+    def delete(self, session: Session, app_model: App):
         """Delete app"""
         app_service = AppService()
-        app_service.delete_app(app_model, session=db.session())
+        app_service.delete_app(app_model, session=session)
 
         return "", 204
 
@@ -872,20 +925,21 @@ class AppCopyApi(Resource):
 
             stmt = select(App).where(App.id == result.app_id)
             app = session.scalar(stmt)
+            if not app:
+                raise NotFound("App not found")
 
-        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)],
-            session=db.session(),
-        )
-        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
+            permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(
+                str(current_tenant_id),
+                current_user.id,
+                [str(app.id)],
+                session=session,
+            )
+            response_model = AppDetailWithSite.model_validate(
+                app,
+                from_attributes=True,
+                context={"session": session},
+            ).model_copy(update={"permission_keys": permission_keys_map.get(str(app.id), [])})
+            return response_model.model_dump(mode="json"), 201
 
 
 @console_ns.route("/apps/<uuid:app_id>/export")
@@ -955,13 +1009,18 @@ class AppNameApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @with_session
     @get_app_model(mode=None)
-    def post(self, app_model: App):
+    def post(self, session: Session, app_model: App):
         args = AppNamePayload.model_validate(console_ns.payload)
 
         app_service = AppService()
-        app_model = app_service.update_app_name(app_model, args.name, session=db.session())
-        return dump_response(AppDetail, app_model)
+        app_model = app_service.update_app_name(app_model, args.name, session=session)
+        return AppDetail.model_validate(
+            app_model,
+            from_attributes=True,
+            context={"session": session},
+        ).model_dump(mode="json")
 
 
 @console_ns.route("/apps/<uuid:app_id>/icon")
@@ -977,8 +1036,9 @@ class AppIconApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @with_session
     @get_app_model(mode=None)
-    def post(self, app_model: App):
+    def post(self, session: Session, app_model: App):
         args = AppIconPayload.model_validate(console_ns.payload or {})
 
         app_service = AppService()
@@ -987,9 +1047,13 @@ class AppIconApi(Resource):
             args.icon or "",
             args.icon_background or "",
             args.icon_type,
-            session=db.session(),
+            session=session,
         )
-        return dump_response(AppDetail, app_model)
+        return AppDetail.model_validate(
+            app_model,
+            from_attributes=True,
+            context={"session": session},
+        ).model_dump(mode="json")
 
 
 @console_ns.route("/apps/<uuid:app_id>/site-enable")
@@ -1005,13 +1069,18 @@ class AppSiteStatus(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    @with_session
     @get_app_model(mode=None)
-    def post(self, app_model: App):
+    def post(self, session: Session, app_model: App):
         args = AppSiteStatusPayload.model_validate(console_ns.payload)
 
         app_service = AppService()
-        app_model = app_service.update_app_site_status(app_model, args.enable_site, session=db.session())
-        return dump_response(AppDetail, app_model)
+        app_model = app_service.update_app_site_status(app_model, args.enable_site, session=session)
+        return AppDetail.model_validate(
+            app_model,
+            from_attributes=True,
+            context={"session": session},
+        ).model_dump(mode="json")
 
 
 @console_ns.route("/apps/<uuid:app_id>/api-enable")
@@ -1027,13 +1096,18 @@ class AppApiStatus(Resource):
     @is_admin_or_owner_required
     @account_initialization_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    @with_session
     @get_app_model(mode=None)
-    def post(self, app_model: App):
+    def post(self, session: Session, app_model: App):
         args = AppApiStatusPayload.model_validate(console_ns.payload)
 
         app_service = AppService()
-        app_model = app_service.update_app_api_status(app_model, args.enable_api, session=db.session())
-        return dump_response(AppDetail, app_model)
+        app_model = app_service.update_app_api_status(app_model, args.enable_api, session=session)
+        return AppDetail.model_validate(
+            app_model,
+            from_attributes=True,
+            context={"session": session},
+        ).model_dump(mode="json")
 
 
 @console_ns.route("/apps/<uuid:app_id>/trace")

api/controllers/console/app/audio.py

@@ -1,13 +1,18 @@
 import logging
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel, Field, RootModel
-from werkzeug.exceptions import InternalServerError
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+from sqlalchemy.orm import Session
+from werkzeug.datastructures import FileStorage
+from werkzeug.exceptions import HTTPException, InternalServerError
 
 import services
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
+from controllers.common.wraps import enforce_rbac_access
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
 from controllers.console.app.error import (
     AppUnavailableError,
     AudioTooLargeError,
@@ -17,15 +22,19 @@ from controllers.console.app.error import (
     ProviderNotInitializeError,
     ProviderNotSupportSpeechToTextError,
     ProviderQuotaExceededError,
+    SpeechToTextDisabledError,
     UnsupportedAudioTypeError,
 )
-from controllers.console.app.wraps import get_app_model
+from controllers.console.app.wraps import get_app_model, with_session
 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.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
 from extensions.ext_database import db
@@ -33,13 +42,17 @@ from fields.base import ResponseModel
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs.helper import dump_response
 from libs.login import current_user, login_required
-from models import App, AppMode
+from models import Account, App, AppMode
+from models.agent import AgentConfigDraftType
+from models.agent_config_entities import AgentSoulConfig
+from services.agent.composer_service import AgentComposerService
 from services.app_ref_service import AppRefService
 from services.audio_service import AudioService
 from services.errors.audio import (
     AudioTooLargeServiceError,
     NoAudioUploadedServiceError,
     ProviderNotSupportSpeechToTextServiceError,
+    SpeechToTextDisabledServiceError,
     UnsupportedAudioTypeServiceError,
 )
 
@@ -61,6 +74,12 @@ class AudioTranscriptResponse(ResponseModel):
     text: str = Field(description="Transcribed text from audio")
 
 
+class AgentAudioTranscriptFormPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    draft_type: AgentConfigDraftType = AgentConfigDraftType.DRAFT
+
+
 class TextToSpeechVoiceResponse(ResponseModel):
     # see api/core/plugin/impl/model.py
     name: str = Field(description="Voice display name")
@@ -71,7 +90,7 @@ class TextToSpeechVoiceListResponse(RootModel[list[TextToSpeechVoiceResponse]]):
     root: list[TextToSpeechVoiceResponse] = Field(description="Available voices")
 
 
-register_schema_models(console_ns, TextToSpeechPayload, TextToSpeechVoiceQuery)
+register_schema_models(console_ns, AgentAudioTranscriptFormPayload, TextToSpeechPayload, TextToSpeechVoiceQuery)
 register_response_schema_models(
     console_ns,
     AudioTranscriptResponse,
@@ -79,12 +98,93 @@ register_response_schema_models(
     TextToSpeechVoiceListResponse,
 )
 
+_AUDIO_TRANSCRIPT_FILE_PARAM = {
+    "description": "MP3 audio to transcribe",
+    "in": "formData",
+    "type": "file",
+    "required": True,
+}
+_AGENT_AUDIO_TRANSCRIPT_PARAMS = {
+    "file": _AUDIO_TRANSCRIPT_FILE_PARAM,
+    "draft_type": {
+        "description": "Agent debug config source",
+        "in": "formData",
+        "type": "string",
+        "enum": [draft_type.value for draft_type in AgentConfigDraftType],
+        "default": AgentConfigDraftType.DRAFT.value,
+        "required": False,
+    },
+}
+_CONSOLE_AUDIO_TRANSCRIPT_APP_MODES = [
+    AppMode.CHAT,
+    AppMode.AGENT_CHAT,
+    AppMode.ADVANCED_CHAT,
+    AppMode.AGENT,
+]
+
+
+def _transcribe_audio_to_text(
+    *,
+    app_model: App,
+    file: FileStorage | None,
+    session: Session,
+    agent_soul: AgentSoulConfig | None = None,
+) -> dict[str, str]:
+    try:
+        if agent_soul is None:
+            response = AudioService.transcript_asr(
+                app_model=app_model,
+                file=file,
+                session=session,
+                end_user=None,
+            )
+        else:
+            response = AudioService.transcript_agent_asr(
+                app_model=app_model,
+                agent_soul=agent_soul,
+                file=file,
+                session=session,
+                end_user=None,
+            )
+        return dump_response(AudioTranscriptResponse, response)
+    except services.errors.app_model_config.AppModelConfigBrokenError:
+        logger.exception("App model config broken.")
+        raise AppUnavailableError()
+    except NoAudioUploadedServiceError:
+        raise NoAudioUploadedError()
+    except AudioTooLargeServiceError as e:
+        raise AudioTooLargeError(str(e))
+    except UnsupportedAudioTypeServiceError:
+        raise UnsupportedAudioTypeError()
+    except ProviderNotSupportSpeechToTextServiceError:
+        raise ProviderNotSupportSpeechToTextError()
+    except SpeechToTextDisabledServiceError:
+        raise SpeechToTextDisabledError()
+    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 HTTPException:
+        raise
+    except ValueError:
+        raise
+    except Exception as e:
+        logger.exception("Failed to transcribe audio to text")
+        raise InternalServerError() from e
+
 
 @console_ns.route("/apps/<uuid:app_id>/audio-to-text")
 class ChatMessageAudioApi(Resource):
     @console_ns.doc("chat_message_audio_transcript")
     @console_ns.doc(description="Transcript audio to text for chat messages")
-    @console_ns.doc(params={"app_id": "App ID"})
+    @console_ns.doc(
+        consumes=["multipart/form-data"],
+        params={"app_id": "App ID", "file": _AUDIO_TRANSCRIPT_FILE_PARAM},
+    )
     @console_ns.response(
         200,
         "Audio transcription successful",
@@ -95,42 +195,72 @@ class ChatMessageAudioApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=_CONSOLE_AUDIO_TRANSCRIPT_APP_MODES)
     def post(self, app_model: App):
-        file = request.files["file"]
+        return _transcribe_audio_to_text(
+            app_model=app_model,
+            file=request.files.get("file"),
+            session=db.session(),
+        )
 
-        try:
-            response = AudioService.transcript_asr(
-                app_model=app_model,
-                file=file,
-                end_user=None,
-            )
 
-            return dump_response(AudioTranscriptResponse, response)
-        except services.errors.app_model_config.AppModelConfigBrokenError:
-            logger.exception("App model config broken.")
-            raise AppUnavailableError()
-        except NoAudioUploadedServiceError:
-            raise NoAudioUploadedError()
-        except AudioTooLargeServiceError as e:
-            raise AudioTooLargeError(str(e))
-        except UnsupportedAudioTypeServiceError:
-            raise UnsupportedAudioTypeError()
-        except ProviderNotSupportSpeechToTextServiceError:
-            raise ProviderNotSupportSpeechToTextError()
-        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 ValueError as e:
-            raise e
-        except Exception as e:
-            logger.exception("Failed to handle post request to ChatMessageAudioApi")
-            raise InternalServerError()
+@console_ns.route("/agent/<uuid:agent_id>/audio-to-text")
+class AgentChatMessageAudioApi(Resource):
+    @console_ns.doc("agent_chat_message_audio_transcript")
+    @console_ns.doc(description="Transcribe audio using the current Agent debug configuration")
+    @console_ns.doc(
+        consumes=["multipart/form-data"],
+        params={"agent_id": "Agent ID", **_AGENT_AUDIO_TRANSCRIPT_PARAMS},
+    )
+    @console_ns.response(
+        200,
+        "Audio transcription successful",
+        console_ns.models[AudioTranscriptResponse.__name__],
+    )
+    @console_ns.response(400, "Bad request - Speech to text disabled or unsupported audio")
+    @console_ns.response(404, "Agent or build draft not found")
+    @console_ns.response(413, "Audio file too large")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_user
+    @with_current_tenant_id
+    @with_session
+    def post(
+        self,
+        session: Session,
+        current_tenant_id: str,
+        current_user: Account,
+        agent_id: UUID,
+    ):
+        payload = AgentAudioTranscriptFormPayload.model_validate(request.form.to_dict(flat=True))
+        app_model = resolve_agent_runtime_app_model(
+            session=session,
+            tenant_id=current_tenant_id,
+            agent_id=agent_id,
+        )
+        # Agent routes expose Agent ids, while APP RBAC is keyed by the resolved runtime App id.
+        enforce_rbac_access(
+            tenant_id=current_tenant_id,
+            account_id=current_user.id,
+            resource_type=RBACResourceScope.APP,
+            scene=RBACPermission.APP_TEST_AND_RUN,
+            path_args={"app_id": app_model.id},
+        )
+        agent_soul = AgentComposerService.load_agent_soul_for_debug(
+            tenant_id=current_tenant_id,
+            agent_id=str(agent_id),
+            account_id=current_user.id,
+            draft_type=payload.draft_type,
+            session=session,
+        )
+        return _transcribe_audio_to_text(
+            app_model=app_model,
+            agent_soul=agent_soul,
+            file=request.files.get("file"),
+            session=session,
+        )
 
 
 @console_ns.route("/apps/<uuid:app_id>/text-to-audio")

api/controllers/console/app/completion.py

@@ -44,7 +44,6 @@ 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
@@ -158,8 +157,8 @@ class CompletionMessageApi(Resource):
     @account_initialization_required
     @with_current_user
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
-    @get_app_model(mode=AppMode.COMPLETION)
     @with_session
+    @get_app_model(mode=AppMode.COMPLETION)
     def post(self, session: Session, 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)
@@ -240,8 +239,8 @@ class ChatMessageApi(Resource):
     @with_current_user
     @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])
     @with_session
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.AGENT])
     def post(self, session: Session, current_tenant_id: str, current_user: Account, app_model: App):
         return _create_chat_message(
             session=session, current_tenant_id=current_tenant_id, current_user=current_user, app_model=app_model
@@ -266,7 +265,9 @@ class AgentChatMessageApi(Resource):
     @with_current_tenant_id
     @with_session
     def post(self, session: Session, current_tenant_id: str, current_user: Account, agent_id: UUID):
-        app_model = resolve_agent_runtime_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        app_model = AgentRosterService(session).get_agent_runtime_app_model(
+            tenant_id=current_tenant_id, agent_id=str(agent_id)
+        )
         return _create_chat_message(
             session=session,
             current_tenant_id=current_tenant_id,
@@ -293,7 +294,9 @@ class AgentBuildChatFinalizeApi(Resource):
     @with_current_tenant_id
     @with_session
     def post(self, session: Session, current_tenant_id: str, current_user: Account, agent_id: UUID):
-        app_model = resolve_agent_runtime_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        app_model = AgentRosterService(session).get_agent_runtime_app_model(
+            tenant_id=current_tenant_id, agent_id=str(agent_id)
+        )
         return _create_build_chat_finalization_message(
             session=session,
             current_tenant_id=current_tenant_id,
@@ -329,15 +332,20 @@ class AgentChatMessageStopApi(Resource):
     @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_runtime_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+    @with_session(write=False)
+    def post(self, session: Session, current_tenant_id: str, current_user_id: str, agent_id: UUID, task_id: str):
+        app_model = resolve_agent_runtime_app_model(
+            session=session,
+            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
+    *, session: Session, current_tenant_id: str, current_user: Account, app_model: App, agent_id: str | None
 ) -> str:
-    roster_service = AgentRosterService(db.session)
+    roster_service = AgentRosterService(session)
     if agent_id:
         return roster_service.get_or_create_agent_app_debug_conversation_id(
             tenant_id=current_tenant_id,
@@ -369,6 +377,7 @@ def _create_chat_message(
 
     if AppMode.value_of(app_model.mode) == AppMode.AGENT:
         debug_conversation_id = _resolve_current_user_agent_debug_conversation_id(
+            session=session,
             current_tenant_id=current_tenant_id or app_model.tenant_id,
             current_user=current_user,
             app_model=app_model,
@@ -404,6 +413,7 @@ def _create_build_chat_finalization_message(
     *, session: Session, current_user: Account, app_model: App, current_tenant_id: str, agent_id: str
 ):
     debug_conversation_id = _resolve_current_user_agent_debug_conversation_id(
+        session=session,
         current_tenant_id=current_tenant_id,
         current_user=current_user,
         app_model=app_model,

api/controllers/console/app/conversation.py

@@ -6,10 +6,11 @@ from flask import abort, request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import func, or_
-from sqlalchemy.orm import selectinload
+from sqlalchemy.orm import Session, selectinload
 from werkzeug.exceptions import NotFound
 
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -22,7 +23,6 @@ from controllers.console.wraps import (
     with_current_user,
 )
 from core.app.entities.app_invoke_entities import InvokeFrom
-from extensions.ext_database import db
 from fields.conversation_fields import (
     Conversation as ConversationResponse,
 )
@@ -35,6 +35,7 @@ from fields.conversation_fields import (
 from fields.conversation_fields import (
     ConversationPagination as ConversationPaginationResponse,
 )
+from fields.conversation_fields import ConversationResponseSource
 from fields.conversation_fields import (
     ConversationWithSummaryPagination as ConversationWithSummaryPaginationResponse,
 )
@@ -105,8 +106,9 @@ class CompletionConversationApi(Resource):
     @edit_permission_required
     @with_current_user
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session(write=False)
     @get_app_model(mode=AppMode.COMPLETION)
-    def get(self, current_user: Account, app_model: App):
+    def get(self, session: Session, current_user: Account, app_model: App):
         args = CompletionConversationQuery.model_validate(request.args.to_dict(flat=True))
 
         query = sa.select(Conversation).where(
@@ -157,9 +159,18 @@ class CompletionConversationApi(Resource):
 
         query = query.order_by(Conversation.created_at.desc())
 
-        conversations = paginate_query(query, page=args.page, per_page=args.limit)
+        conversations = paginate_query(query, session=session, page=args.page, per_page=args.limit)
 
-        return dump_response(ConversationPaginationResponse, conversations)
+        return dump_response(
+            ConversationPaginationResponse,
+            {
+                "page": conversations.page,
+                "per_page": conversations.per_page,
+                "total": conversations.total,
+                "has_next": conversations.has_next,
+                "items": [ConversationResponseSource(item, session=session) for item in conversations.items],
+            },
+        )
 
 
 @console_ns.route("/apps/<uuid:app_id>/completion-conversations/<uuid:conversation_id>")
@@ -176,11 +187,15 @@ class CompletionConversationDetailApi(Resource):
     @edit_permission_required
     @with_current_user
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session
     @get_app_model(mode=AppMode.COMPLETION)
-    def get(self, current_user: Account, app_model: App, conversation_id: UUID):
+    def get(self, session: Session, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
         return dump_response(
-            ConversationMessageDetailResponse, _get_conversation(current_user, app_model, conversation_id_str)
+            ConversationMessageDetailResponse,
+            ConversationResponseSource(
+                _get_conversation(session, current_user, app_model, conversation_id_str), session=session
+            ),
         )
 
     @console_ns.doc("delete_completion_conversation")
@@ -195,12 +210,13 @@ class CompletionConversationDetailApi(Resource):
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
+    @with_session
     @get_app_model(mode=AppMode.COMPLETION)
-    def delete(self, current_user: Account, app_model: App, conversation_id: UUID):
+    def delete(self, session: Session, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
 
         try:
-            ConversationService.delete(app_model, conversation_id_str, current_user, session=db.session())
+            ConversationService.delete(app_model, conversation_id_str, current_user, session=session)
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
 
@@ -220,8 +236,9 @@ class ChatConversationApi(Resource):
     @edit_permission_required
     @with_current_user
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session(write=False)
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
-    def get(self, current_user: Account, app_model: App):
+    def get(self, session: Session, current_user: Account, app_model: App):
         args = ChatConversationQuery.model_validate(request.args.to_dict(flat=True))
 
         subquery = (
@@ -311,9 +328,18 @@ class ChatConversationApi(Resource):
             case _:
                 query = query.order_by(Conversation.created_at.desc())
 
-        conversations = paginate_query(query, page=args.page, per_page=args.limit)
+        conversations = paginate_query(query, session=session, page=args.page, per_page=args.limit)
 
-        return dump_response(ConversationWithSummaryPaginationResponse, conversations)
+        return dump_response(
+            ConversationWithSummaryPaginationResponse,
+            {
+                "page": conversations.page,
+                "per_page": conversations.per_page,
+                "total": conversations.total,
+                "has_next": conversations.has_next,
+                "items": [ConversationResponseSource(item, session=session) for item in conversations.items],
+            },
+        )
 
 
 @console_ns.route("/apps/<uuid:app_id>/chat-conversations/<uuid:conversation_id>")
@@ -330,11 +356,15 @@ class ChatConversationDetailApi(Resource):
     @edit_permission_required
     @with_current_user
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session
     @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):
+    def get(self, session: Session, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
         return dump_response(
-            ConversationDetailResponse, _get_conversation(current_user, app_model, conversation_id_str)
+            ConversationDetailResponse,
+            ConversationResponseSource(
+                _get_conversation(session, current_user, app_model, conversation_id_str), session=session
+            ),
         )
 
     @console_ns.doc("delete_chat_conversation")
@@ -349,27 +379,28 @@ class ChatConversationDetailApi(Resource):
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
+    @with_session
     @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):
+    def delete(self, session: Session, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
 
         try:
-            ConversationService.delete(app_model, conversation_id_str, current_user, session=db.session())
+            ConversationService.delete(app_model, conversation_id_str, current_user, session=session)
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
 
         return "", 204
 
 
-def _get_conversation(current_user: Account, app_model, conversation_id):
-    conversation = db.session.scalar(
+def _get_conversation(session: Session, current_user: Account, app_model, conversation_id):
+    conversation = session.scalar(
         sa.select(Conversation).where(Conversation.id == conversation_id, Conversation.app_id == app_model.id).limit(1)
     )
 
     if not conversation:
         raise NotFound("Conversation Not Exists.")
 
-    db.session.execute(
+    session.execute(
         sa.update(Conversation)
         .where(Conversation.id == conversation_id, Conversation.read_at.is_(None))
         # Keep updated_at unchanged when only marking a conversation as read.
@@ -379,7 +410,7 @@ def _get_conversation(current_user: Account, app_model, conversation_id):
             updated_at=Conversation.updated_at,
         )
     )
-    db.session.commit()
-    db.session.refresh(conversation)
+    session.flush()
+    session.refresh(conversation)
 
     return conversation

api/controllers/console/app/error.py

@@ -79,6 +79,12 @@ class ProviderNotSupportSpeechToTextError(BaseHTTPException):
     code = 400
 
 
+class SpeechToTextDisabledError(BaseHTTPException):
+    error_code = "speech_to_text_disabled"
+    description = "Speech to text is disabled."
+    code = 400
+
+
 class DraftWorkflowNotExist(BaseHTTPException):
     error_code = "draft_workflow_not_exist"
     description = "Draft workflow need to be initialized."

api/controllers/console/app/generator.py

@@ -3,7 +3,7 @@ from collections.abc import Generator, Sequence
 from typing import Any, Literal
 
 from flask_restx import Resource
-from pydantic import BaseModel, Field, RootModel
+from pydantic import BaseModel, ConfigDict, Field, RootModel
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
@@ -26,9 +26,10 @@ from core.helper.code_executor.python3.python3_code_provider import Python3CodeP
 from core.llm_generator.entities import RuleCodeGeneratePayload, RuleGeneratePayload, RuleStructuredOutputPayload
 from core.llm_generator.llm_generator import LLMGenerator
 from core.workflow.generator.types import WorkflowGenerateErrorCode
+from fields.base import ResponseModel
 from graphon.model_runtime.entities.llm_entities import LLMMode
 from graphon.model_runtime.errors.invoke import InvokeError
-from libs.helper import compact_generate_response
+from libs.helper import compact_generate_response, dump_response
 from libs.login import login_required
 from models import App
 from services.workflow_generator_service import WorkflowGeneratorService
@@ -60,6 +61,48 @@ class InstructionTemplatePayload(BaseModel):
 _MAX_INSTRUCTION_LENGTH = 10_000
 
 
+class WorkflowGraphPosition(BaseModel):
+    x: float
+    y: float
+
+
+class WorkflowGraphViewport(WorkflowGraphPosition):
+    zoom: float
+
+
+class WorkflowGraphNode(BaseModel):
+    """React Flow node shape accepted and returned by the generator.
+
+    Node-specific configuration lives under ``data`` and wrapper metadata
+    differs for container children, so unknown wrapper fields must survive
+    request validation and response serialization.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    id: str
+    type: str
+    position: WorkflowGraphPosition
+    data: dict[str, Any]
+
+
+class WorkflowGraphEdge(BaseModel):
+    """React Flow edge shape with extensible renderer metadata."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    id: str
+    source: str
+    target: str
+    type: str
+
+
+class WorkflowGraph(BaseModel):
+    nodes: list[WorkflowGraphNode]
+    edges: list[WorkflowGraphEdge]
+    viewport: WorkflowGraphViewport
+
+
 class WorkflowGeneratePayload(BaseModel):
     """Payload for the cmd+k `/create` and `/refine` workflow generator endpoint.
 
@@ -79,7 +122,7 @@ class WorkflowGeneratePayload(BaseModel):
         alias="model_config",
         description="Model configuration",
     )
-    current_graph: dict | None = Field(
+    current_graph: WorkflowGraph | None = Field(
         default=None,
         description="Existing draft graph to refine (cmd+k `/refine`); omit for create-from-scratch",
     )
@@ -98,6 +141,59 @@ class WorkflowInstructionSuggestionsPayload(BaseModel):
     count: int = Field(default=4, ge=1, le=6, description="Number of suggestions to return (1-6)")
 
 
+class WorkflowGenerateErrorResponse(ResponseModel):
+    code: WorkflowGenerateErrorCode
+    detail: str
+    node_id: str | None = None
+
+
+class WorkflowGenerateResponse(ResponseModel):
+    graph: WorkflowGraph
+    message: str = ""
+    app_name: str = ""
+    icon: str = ""
+    error: str = ""
+    errors: list[WorkflowGenerateErrorResponse] = Field(default_factory=list)
+    mode: Literal["workflow", "advanced-chat"] | None = None
+
+
+class WorkflowPlanNodeResponse(ResponseModel):
+    label: str
+    node_type: str
+    purpose: str = ""
+
+
+class WorkflowPlanStartInputResponse(ResponseModel):
+    variable: str
+    label: str = ""
+    type: str = ""
+
+
+class WorkflowGeneratePlanEventResponse(ResponseModel):
+    event: Literal["plan"] = "plan"
+    title: str = ""
+    description: str = ""
+    app_name: str = ""
+    icon: str = ""
+    mode: Literal["workflow", "advanced-chat"]
+    nodes: list[WorkflowPlanNodeResponse]
+    start_inputs: list[WorkflowPlanStartInputResponse] = Field(default_factory=list)
+
+
+class WorkflowGenerateResultEventResponse(WorkflowGenerateResponse):
+    event: Literal["result"] = "result"
+
+
+class WorkflowGenerateStreamEventResponse(
+    RootModel[WorkflowGeneratePlanEventResponse | WorkflowGenerateResultEventResponse]
+):
+    """Schema for each JSON object carried by an SSE ``data:`` frame."""
+
+
+class WorkflowInstructionSuggestionsResponse(ResponseModel):
+    suggestions: list[str]
+
+
 class GeneratorResponse(RootModel[Any]):
     root: Any
 
@@ -114,7 +210,16 @@ register_schema_models(
     WorkflowInstructionSuggestionsPayload,
     ModelConfig,
 )
-register_response_schema_models(console_ns, GeneratorResponse, SimpleDataResponse)
+register_response_schema_models(
+    console_ns,
+    GeneratorResponse,
+    SimpleDataResponse,
+    WorkflowGenerateResponse,
+    WorkflowGeneratePlanEventResponse,
+    WorkflowGenerateResultEventResponse,
+    WorkflowGenerateStreamEventResponse,
+    WorkflowInstructionSuggestionsResponse,
+)
 
 
 @console_ns.route("/rule-generate")
@@ -376,7 +481,11 @@ 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.models[GeneratorResponse.__name__])
+    @console_ns.response(
+        200,
+        "Workflow graph generated successfully",
+        console_ns.models[WorkflowGenerateResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -399,7 +508,9 @@ class WorkflowGenerateApi(Resource):
                 instruction=args.instruction,
                 model_config=args.model_config_data,
                 ideal_output=args.ideal_output,
-                current_graph=args.current_graph,
+                current_graph=args.current_graph.model_dump(by_alias=True, exclude_none=True)
+                if args.current_graph
+                else None,
             )
         except ProviderTokenNotInitError as ex:
             raise ProviderNotInitializeError(ex.description)
@@ -410,7 +521,7 @@ class WorkflowGenerateApi(Resource):
         except InvokeError as e:
             raise CompletionRequestError(e.description)
 
-        return result
+        return dump_response(WorkflowGenerateResponse, result)
 
 
 @console_ns.route("/workflow-generate/suggestions")
@@ -426,7 +537,11 @@ class WorkflowInstructionSuggestionsApi(Resource):
     @console_ns.doc("generate_workflow_instruction_suggestions")
     @console_ns.doc(description="Suggest example workflow-generator instructions for the tenant")
     @console_ns.expect(console_ns.models[WorkflowInstructionSuggestionsPayload.__name__])
-    @console_ns.response(200, "Suggestions generated successfully", console_ns.models[GeneratorResponse.__name__])
+    @console_ns.response(
+        200,
+        "Suggestions generated successfully",
+        console_ns.models[WorkflowInstructionSuggestionsResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
@@ -440,7 +555,7 @@ class WorkflowInstructionSuggestionsApi(Resource):
             language=args.language,
             count=args.count,
         )
-        return {"suggestions": suggestions}
+        return dump_response(WorkflowInstructionSuggestionsResponse, {"suggestions": suggestions})
 
 
 @console_ns.route("/workflow-generate/stream")
@@ -458,7 +573,11 @@ class WorkflowGenerateStreamApi(Resource):
     @console_ns.doc("generate_workflow_graph_stream")
     @console_ns.doc(description="Stream a Dify workflow graph (plan then result) via SSE")
     @console_ns.expect(console_ns.models[WorkflowGeneratePayload.__name__])
-    @console_ns.response(200, "Server-Sent Events stream of plan/result events")
+    @console_ns.response(
+        200,
+        "Server-Sent Events stream; each data frame matches this plan/result event schema",
+        console_ns.models[WorkflowGenerateStreamEventResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
@@ -481,10 +600,17 @@ class WorkflowGenerateStreamApi(Resource):
                     instruction=args.instruction,
                     model_config=args.model_config_data,
                     ideal_output=args.ideal_output,
-                    current_graph=args.current_graph,
+                    current_graph=(
+                        args.current_graph.model_dump(by_alias=True, exclude_none=True) if args.current_graph else None
+                    ),
                 ):
                     body = {"event": event_name, **payload}
-                    yield f"data: {json.dumps(body)}\n\n"
+                    if event_name == "plan":
+                        plan_event = WorkflowGeneratePlanEventResponse.model_validate(body)
+                        yield f"data: {json.dumps(plan_event.model_dump(mode='json'))}\n\n"
+                    else:
+                        result_event = WorkflowGenerateResultEventResponse.model_validate(body)
+                        yield f"data: {json.dumps(result_event.model_dump(mode='json'))}\n\n"
             except (ProviderTokenNotInitError, QuotaExceededError, ModelCurrentlyNotSupportError, InvokeError) as e:
                 # The model instance is resolved inside the service (lazily, on
                 # first iteration), so a provider / init error surfaces here.
@@ -498,6 +624,7 @@ class WorkflowGenerateStreamApi(Resource):
                     "error": detail,
                     "errors": [{"code": WorkflowGenerateErrorCode.MODEL_ERROR, "detail": detail}],
                 }
-                yield f"data: {json.dumps(error_body)}\n\n"
+                error_event = WorkflowGenerateResultEventResponse.model_validate(error_body)
+                yield f"data: {json.dumps(error_event.model_dump(mode='json'))}\n\n"
 
         return compact_generate_response(generate())

api/controllers/console/app/mcp_server.py

@@ -153,8 +153,8 @@ class AppMCPServerController(Resource):
             select(AppMCPServer)
             .where(
                 AppMCPServer.id == server_ref.server_id,
-                AppMCPServer.tenant_id == server_ref.tenant_id,
-                AppMCPServer.app_id == server_ref.app_id,
+                AppMCPServer.tenant_id == server_ref.app.tenant_id,
+                AppMCPServer.app_id == server_ref.app.app_id,
             )
             .limit(1)
         )

api/controllers/console/app/message.py

@@ -6,11 +6,13 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import exists, func, select
+from sqlalchemy.orm import Session
 from werkzeug.exceptions import InternalServerError, NotFound
 
 from controllers.common.controller_schemas import MessageFeedbackPayload as _MessageFeedbackPayloadBase
 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.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
 from controllers.console.app.error import (
@@ -39,6 +41,7 @@ from fields.base import ResponseModel
 from fields.conversation_fields import (
     MessageDetail as BaseMessageDetailResponse,
 )
+from fields.conversation_fields import MessageResponseSource
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs.helper import dump_response, uuid_value
 from libs.infinite_scroll_pagination import InfiniteScrollPagination
@@ -152,9 +155,10 @@ class ChatMessageListApi(Resource):
     @edit_permission_required
     @with_current_user
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session(write=False)
     @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)
+    def get(self, session: Session, current_user: Account, app_model: App):
+        return _list_chat_messages(session=session, app_model=app_model, current_user=current_user)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/chat-messages")
@@ -172,9 +176,14 @@ class AgentChatMessageListApi(Resource):
     @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_runtime_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
-        return _list_chat_messages(app_model=app_model, current_user=current_user)
+    @with_session(write=False)
+    def get(self, session: Session, current_tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(
+            session=session,
+            tenant_id=current_tenant_id,
+            agent_id=agent_id,
+        )
+        return _list_chat_messages(session=session, app_model=app_model, current_user=current_user)
 
 
 @console_ns.route("/apps/<uuid:app_id>/feedbacks")
@@ -190,9 +199,10 @@ class MessageFeedbackApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_user
+    @with_session
     @get_app_model
-    def post(self, current_user: Account, app_model: App):
-        return _update_message_feedback(current_user=current_user, app_model=app_model)
+    def post(self, session: Session, current_user: Account, app_model: App):
+        return _update_message_feedback(session=session, current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/feedbacks")
@@ -208,9 +218,14 @@ class AgentMessageFeedbackApi(Resource):
     @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_runtime_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
-        return _update_message_feedback(current_user=current_user, app_model=app_model)
+    @with_session
+    def post(self, session: Session, current_tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_runtime_app_model(
+            session=session,
+            tenant_id=current_tenant_id,
+            agent_id=agent_id,
+        )
+        return _update_message_feedback(session=session, current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotations/count")
@@ -252,9 +267,12 @@ class MessageSuggestedQuestionApi(Resource):
     @account_initialization_required
     @with_current_user
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session(write=False)
     @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):
-        return _get_message_suggested_questions(current_user=current_user, app_model=app_model, message_id=message_id)
+    def get(self, session: Session, current_user: Account, app_model: App, message_id: UUID):
+        return _get_message_suggested_questions(
+            session=session, current_user=current_user, app_model=app_model, message_id=message_id
+        )
 
 
 @console_ns.route("/agent/<uuid:agent_id>/chat-messages/<uuid:message_id>/suggested-questions")
@@ -273,9 +291,16 @@ class AgentMessageSuggestedQuestionApi(Resource):
     @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_runtime_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)
+    @with_session(write=False)
+    def get(self, session: Session, current_tenant_id: str, current_user: Account, agent_id: UUID, message_id: UUID):
+        app_model = resolve_agent_runtime_app_model(
+            session=session,
+            tenant_id=current_tenant_id,
+            agent_id=agent_id,
+        )
+        return _get_message_suggested_questions(
+            session=session, current_user=current_user, app_model=app_model, message_id=message_id
+        )
 
 
 @console_ns.route("/apps/<uuid:app_id>/feedbacks/export")
@@ -333,9 +358,10 @@ class MessageApi(Resource):
     @login_required
     @account_initialization_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_session(write=False)
     @get_app_model
-    def get(self, app_model: App, message_id: UUID):
-        return _get_message_detail(app_model=app_model, message_id=message_id)
+    def get(self, session: Session, app_model: App, message_id: UUID):
+        return _get_message_detail(session=session, app_model=app_model, message_id=message_id)
 
 
 @console_ns.route("/agent/<uuid:agent_id>/messages/<uuid:message_id>")
@@ -349,12 +375,17 @@ class AgentMessageApi(Resource):
     @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_runtime_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
-        return _get_message_detail(app_model=app_model, message_id=message_id)
+    @with_session(write=False)
+    def get(self, session: Session, current_tenant_id: str, agent_id: UUID, message_id: UUID):
+        app_model = resolve_agent_runtime_app_model(
+            session=session,
+            tenant_id=current_tenant_id,
+            agent_id=agent_id,
+        )
+        return _get_message_detail(session=session, app_model=app_model, message_id=message_id)
 
 
-def _list_chat_messages(*, app_model: App, current_user: Account | None = None):
+def _list_chat_messages(*, session: Session, 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:
@@ -363,12 +394,12 @@ def _list_chat_messages(*, app_model: App, current_user: Account | None = None):
                 app_model=app_model,
                 conversation_id=args.conversation_id,
                 user=current_user,
-                session=db.session(),
+                session=session,
             )
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
     else:
-        conversation = db.session.scalar(
+        conversation = session.scalar(
             select(Conversation)
             .where(Conversation.id == args.conversation_id, Conversation.app_id == app_model.id)
             .limit(1)
@@ -378,14 +409,14 @@ def _list_chat_messages(*, app_model: App, current_user: Account | None = None):
         raise NotFound("Conversation Not Exists.")
 
     if args.first_id:
-        first_message = db.session.scalar(
+        first_message = 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(
+        history_messages = session.scalars(
             select(Message)
             .where(
                 Message.conversation_id == conversation.id,
@@ -396,7 +427,7 @@ def _list_chat_messages(*, app_model: App, current_user: Account | None = None):
             .limit(args.limit)
         ).all()
     else:
-        history_messages = db.session.scalars(
+        history_messages = session.scalars(
             select(Message)
             .where(Message.conversation_id == conversation.id)
             .order_by(Message.created_at.desc())
@@ -407,7 +438,7 @@ def _list_chat_messages(*, app_model: App, current_user: Account | None = None):
     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(
+        has_more = session.scalar(
             select(
                 exists().where(
                     Message.conversation_id == conversation.id,
@@ -425,26 +456,28 @@ def _list_chat_messages(*, app_model: App, current_user: Account | None = None):
 
     return dump_response(
         MessageInfiniteScrollPaginationResponse,
-        InfiniteScrollPagination(data=history_messages, limit=args.limit, has_more=has_more),
+        InfiniteScrollPagination(
+            data=[MessageResponseSource(message, session=session) for message in history_messages],
+            limit=args.limit,
+            has_more=has_more,
+        ),
     )
 
 
-def _update_message_feedback(*, current_user: Account, app_model: App):
+def _update_message_feedback(*, session: Session, current_user: Account, app_model: App):
     args = MessageFeedbackPayload.model_validate(console_ns.payload)
 
     message_id = args.message_id
 
-    message = db.session.scalar(
-        select(Message).where(Message.id == message_id, Message.app_id == app_model.id).limit(1)
-    )
+    message = 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
+    feedback = message.admin_feedback_with_session(session=session)
 
     if not args.rating and feedback:
-        db.session.delete(feedback)
+        session.delete(feedback)
     elif args.rating and feedback:
         feedback.rating = FeedbackRating(args.rating)
         feedback.content = args.content
@@ -463,14 +496,14 @@ def _update_message_feedback(*, current_user: Account, app_model: App):
             from_source=FeedbackFromSource.ADMIN,
             from_account_id=current_user.id,
         )
-        db.session.add(feedback)
+        session.add(feedback)
 
-    db.session.commit()
+    session.commit()
 
     return SimpleResultResponse(result="success").model_dump(mode="json")
 
 
-def _get_message_suggested_questions(*, current_user: Account, app_model: App, message_id: UUID):
+def _get_message_suggested_questions(*, session: Session, current_user: Account, app_model: App, message_id: UUID):
     message_id_str = str(message_id)
 
     try:
@@ -479,7 +512,7 @@ def _get_message_suggested_questions(*, current_user: Account, app_model: App, m
             message_id=message_id_str,
             user=current_user,
             invoke_from=InvokeFrom.DEBUGGER,
-            session=db.session(),
+            session=session,
         )
     except MessageNotExistsError:
         raise NotFound("Message not found")
@@ -502,10 +535,10 @@ def _get_message_suggested_questions(*, current_user: Account, app_model: App, m
     return dump_response(SuggestedQuestionsResponse, {"data": questions})
 
 
-def _get_message_detail(*, app_model: App, message_id: UUID):
+def _get_message_detail(*, session: Session, app_model: App, message_id: UUID):
     message_id_str = str(message_id)
 
-    message = db.session.scalar(
+    message = session.scalar(
         select(Message).where(Message.id == message_id_str, Message.app_id == app_model.id).limit(1)
     )
 
@@ -513,4 +546,4 @@ def _get_message_detail(*, app_model: App, message_id: UUID):
         raise NotFound("Message Not Exists.")
 
     attach_message_extra_contents([message])
-    return dump_response(MessageDetailResponse, message)
+    return dump_response(MessageDetailResponse, MessageResponseSource(message, session=session))

api/controllers/console/app/model_config.py

@@ -4,9 +4,11 @@ from typing import Any, cast
 from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
 
 from controllers.common.fields import SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -23,7 +25,6 @@ from core.agent.entities import AgentToolEntity
 from core.tools.tool_manager import ToolManager
 from core.tools.utils.configuration import ToolParameterConfigurationManager
 from events.app_event import app_model_config_was_updated
-from extensions.ext_database import db
 from libs.datetime_utils import naive_utc_now
 from libs.login import login_required
 from models.model import App, AppMode, AppModelConfig
@@ -93,14 +94,16 @@ class ModelConfigResource(Resource):
     @account_initialization_required
     @with_current_user_id
     @with_current_tenant_id
+    @with_session
     @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"""
+    def post(self, session: Session, current_tenant_id: str, current_user_id: str, app_model: App):
+        """Modify the app model config and dataset joins in one request transaction."""
         # validate config
         model_configuration = AppModelConfigService.validate_configuration(
             tenant_id=current_tenant_id,
             config=cast(dict, request.json),
             app_mode=AppMode.value_of(app_model.mode),
+            session=session,
         )
 
         new_app_model_config = AppModelConfig(
@@ -110,9 +113,8 @@ class ModelConfigResource(Resource):
         )
         new_app_model_config = new_app_model_config.from_model_config_dict(model_configuration)
 
-        if app_model.mode == AppMode.AGENT_CHAT or app_model.is_agent:
-            # get original app model config
-            original_app_model_config = db.session.get(AppModelConfig, app_model.app_model_config_id)
+        if app_model.mode == AppMode.AGENT_CHAT or app_model.is_agent_with_session(session=session):
+            original_app_model_config = app_model.app_model_config_with_session(session=session)
             if original_app_model_config is None:
                 raise ValueError("Original app model config not found")
             agent_mode = original_app_model_config.agent_mode_dict
@@ -204,14 +206,17 @@ class ModelConfigResource(Resource):
             # update app model config
             new_app_model_config.agent_mode = json.dumps(agent_mode)
 
-        db.session.add(new_app_model_config)
-        db.session.flush()
+        session.add(new_app_model_config)
+        session.flush()
 
         app_model.app_model_config_id = new_app_model_config.id
         app_model.updated_by = current_user_id
         app_model.updated_at = naive_utc_now()
-        db.session.commit()
 
-        app_model_config_was_updated.send(app_model, app_model_config=new_app_model_config)
+        app_model_config_was_updated.send(
+            app_model,
+            app_model_config=new_app_model_config,
+            session=session,
+        )
 
         return {"result": "success"}

api/controllers/console/app/site.py

@@ -3,10 +3,12 @@ from typing import Literal
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
+from sqlalchemy.orm import Session
 from werkzeug.exceptions import NotFound
 
 from constants.languages import supported_language
 from controllers.common.schema import register_schema_models
+from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -19,7 +21,6 @@ from controllers.console.wraps import (
     setup_required,
     with_current_user,
 )
-from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.datetime_utils import naive_utc_now
 from libs.helper import dump_response
@@ -94,10 +95,11 @@ class AppSite(Resource):
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @account_initialization_required
     @with_current_user
+    @with_session
     @get_app_model
-    def post(self, current_user: Account, app_model: App):
+    def post(self, session: Session, 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))
+        site = session.scalar(select(Site).where(Site.app_id == app_model.id).limit(1))
         if not site:
             raise NotFound
 
@@ -126,7 +128,7 @@ class AppSite(Resource):
 
         site.updated_by = current_user.id
         site.updated_at = naive_utc_now()
-        db.session.commit()
+        session.flush()
 
         return dump_response(AppSiteResponse, site)
 
@@ -145,16 +147,17 @@ class AppSiteAccessTokenReset(Resource):
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @account_initialization_required
     @with_current_user
+    @with_session
     @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))
+    def post(self, session: Session, current_user: Account, app_model: App):
+        site = session.scalar(select(Site).where(Site.app_id == app_model.id).limit(1))
 
         if not site:
             raise NotFound
 
-        site.code = Site.generate_code(16)
+        site.code = Site.generate_code(16, session=session)
         site.updated_by = current_user.id
         site.updated_at = naive_utc_now()
-        db.session.commit()
+        session.flush()
 
         return dump_response(AppSiteResponse, site)