refactor(openapi): fold list into get and remove/revoke into delete

Server side of 01a4939731 on feat/difyctl-v2: get lists, describe shows one
item, delete removes one; stream.run.event becomes get.run.event.

.agents/skills/backend-code-review/references/architecture-rule.md

@@ -41,6 +41,7 @@
     # core/policy/publish_policy.py
     from controllers.console.app import request_context
 
+
     def can_publish() -> bool:
         return request_context.current_user.is_admin
     ```
@@ -50,6 +51,7 @@
     def can_publish(role: str) -> bool:
         return role == "admin"
 
+
     # service layer adapts web/user context to domain input
     allowed = can_publish(role=current_user.role)
     ```
@@ -66,6 +68,7 @@
     # api/libs/conversation_filter.py
     from services.conversation_service import ConversationService
 
+
     def should_archive_conversation(conversation, tenant_id: str) -> bool:
         # Domain policy and service dependency are leaking into libs.
         service = ConversationService()
@@ -79,9 +82,11 @@
     def older_than_days(idle_days: int, threshold_days: int) -> bool:
         return idle_days > threshold_days
 
+
     # services/conversation_service.py (business logic stays in service/core)
     from libs.datetime_utils import older_than_days
 
+
     def should_archive_conversation(conversation, tenant_id: str) -> bool:
         threshold_days = 90 if has_paid_plan(tenant_id) else 30
         return older_than_days(conversation.idle_days, threshold_days)

.agents/skills/backend-code-review/references/db-schema-rule.md

@@ -50,6 +50,7 @@
     ```python
     from sqlalchemy.orm import Mapped
 
+
     class Dataset(TypeBase):
         __tablename__ = "datasets"
         id: Mapped[str] = mapped_column(StringUUID, primary_key=True)
@@ -59,6 +60,7 @@
     ```python
     from sqlalchemy.orm import Mapped
 
+
     class Dataset(TypeBase):
         __tablename__ = "datasets"
         id: Mapped[str] = mapped_column(StringUUID, primary_key=True)
@@ -101,6 +103,7 @@
     from sqlalchemy.dialects.postgresql import JSONB
     from sqlalchemy.orm import Mapped
 
+
     class ToolConfig(TypeBase):
         __tablename__ = "tool_configs"
         config: Mapped[dict] = mapped_column(JSONB, nullable=False)
@@ -111,6 +114,7 @@
 
     from models.types import AdjustedJSON
 
+
     class ToolConfig(TypeBase):
         __tablename__ = "tool_configs"
         config: Mapped[dict] = mapped_column(AdjustedJSON(), nullable=False)
@@ -146,7 +150,5 @@
     default_expr = sa.text("'database'::character varying") if _is_pg(conn) else sa.text("'database'")
 
     with op.batch_alter_table("dataset_keyword_tables") as batch_op:
-        batch_op.add_column(
-            sa.Column("data_source_type", sa.String(255), server_default=default_expr, nullable=False)
-        )
+        batch_op.add_column(sa.Column("data_source_type", sa.String(255), server_default=default_expr, nullable=False))
     ```

.agents/skills/backend-code-review/references/repositories-rule.md

@@ -18,9 +18,7 @@
     # Existing repository is ignored and service uses ad-hoc table queries.
     class AppService:
         def archive_app(self, app_id: str, tenant_id: str) -> None:
-            app = self.session.execute(
-                select(App).where(App.id == app_id, App.tenant_id == tenant_id)
-            ).scalar_one()
+            app = self.session.execute(select(App).where(App.id == app_id, App.tenant_id == tenant_id)).scalar_one()
             app.archived = True
             self.session.commit()
     ```
@@ -33,6 +31,7 @@
             app.archived = True
             self.app_repo.save(app)
 
+
     # If the query is missing, extend the existing abstraction.
     active_apps = self.app_repo.list_active_for_tenant(tenant_id=tenant_id)
     ```
@@ -50,9 +49,10 @@
     class ConversationRepository(Protocol):
         def list_recent_for_app(self, app_id: str, tenant_id: str, limit: int) -> list[Conversation]: ...
 
+
     class SqlAlchemyConversationRepository:
-        def list_recent_for_app(self, app_id: str, tenant_id: str, limit: int) -> list[Conversation]:
-            ...
+        def list_recent_for_app(self, app_id: str, tenant_id: str, limit: int) -> list[Conversation]: ...
+
 
     class ConversationService:
         def __init__(self, conversation_repo: ConversationRepository):

.agents/skills/backend-code-review/references/sqlalchemy-rule.md

@@ -126,9 +126,7 @@
 
     # 3) Pessimistic lock with SELECT ... FOR UPDATE (high contention)
     run = session.execute(
-        select(WorkflowRun)
-        .where(WorkflowRun.id == run_id, WorkflowRun.tenant_id == tenant_id)
-        .with_for_update()
+        select(WorkflowRun).where(WorkflowRun.id == run_id, WorkflowRun.tenant_id == tenant_id).with_for_update()
     ).scalar_one()
     run.status = "cancelled"
     session.commit()

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

@@ -5,14 +5,14 @@ description: Use only when the user explicitly requests a review or audit of fro
 
 # Frontend Code Review
 
-Review the requested scope for concrete, reproducible regressions. This skill owns the review phase and routes directly to its bundled rule packs. For a combined review-and-fix request, establish findings before applying implementation or testing guidance.
+Review the requested scope for concrete defects and violations of explicit project contracts. This skill owns review decisions; its references route to canonical rules without activating another skill's implementation workflow.
 
 ## Evidence First
 
 1. Establish the review scope from the requested files or current diff.
 2. Read the changed lines, their behavior owner, and the nearest scoped `AGENTS.md`.
 3. Trace public consumers, generated contracts, primitive APIs, or runtime configuration only when they decide correctness.
-4. Report only findings tied to an observable failure, violated contract, security boundary, or demonstrated maintenance risk.
+4. Report findings tied to an observable failure, violated contract, security boundary, or demonstrated maintenance risk. Explicit team conventions are contracts: establish their scope and exceptions, and do not invent user impact to justify a convention finding.
 
 ## Rule Routing
 
@@ -33,10 +33,10 @@ Read `packages/dify-ui/README.md`, `packages/dify-ui/AGENTS.md`, `packages/dify-
 
 - **P0**: security or privacy leak, data loss, production crash, or inaccessible critical workflow.
 - **P1**: user-visible regression, invalid API or authorization contract, hydration failure, or broken primary interaction.
-- **P2**: concrete maintainability, performance, test, or accessibility defect likely to cause incorrect behavior.
+- **P2**: concrete maintainability, performance, test, or accessibility defect, or a material violation of an explicit project contract.
 - **P3**: minor actionable cleanup; omit unless the user requested a thorough audit.
 
-Lead with findings ordered by severity. Include a tight file and line reference, the failing contract or reproduction path, impact, and a concrete fix direction. If there are no findings, say `No issues found.` and state any material verification gap. Do not add praise sections, speculative risks, or an unsolicited offer to implement fixes.
+Lead with findings ordered by severity. Include a tight file and line reference, the observed failure or applicable project rule, and a concrete fix direction. Explain the rule's applicability for convention findings; describe downstream consequences only when supported by evidence. When no findings remain, say so briefly and state any material verification gap. Do not add praise sections, speculative risks, or an unsolicited offer to implement fixes.
 
 [accessibility]: references/accessibility-ui.md
 [code-quality]: references/code-quality.md

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

@@ -2,32 +2,51 @@
 
 Accessibility findings are first-class review findings. Treat broken keyboard access, missing accessible names, focus loss, and unreachable popup content as correctness bugs, not polish.
 
-Before finalizing UI or accessibility findings, fetch the latest Web Interface Guidelines as a required baseline:
+## Review Evidence
 
-```text
-https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
-```
-
-Do not treat that document as the complete accessibility rule set. Combine it with:
+Use the sources relevant to the changed contract:
 
 - `packages/dify-ui/README.md`, `packages/dify-ui/AGENTS.md`, and the relevant primitive implementation when code uses `@langgenius/dify-ui/*`.
 - Base UI docs and local `.d.ts` contracts when primitive semantics, focus target, labels, or popup reachability are unclear.
 - MDN or relevant WAI-ARIA/browser standards when behavior, compatibility, or deprecation status matters.
 - The current feature's product semantics, because an accessible primitive can still be used in an inaccessible workflow.
 
+Consult current official documentation or standards when these sources leave a behavior unresolved. The [Web Interface Guidelines] are an optional broader UI reference, not a required fetch for each review.
+
 ## Semantic HTML
 
 Flag:
 
 - Clickable `div` or `span` used for actions.
 - Router navigation implemented with button or `onClick` when a `Link` / `<a>` is the real semantic element.
-- Icon-only buttons without `aria-label` or `aria-labelledby`.
+- Icon-only controls without an accessible name; follow the naming rules below and the Dify UI `IconButton` contract.
 - Decorative icons missing `aria-hidden="true"`.
 - Images without `alt`; use `alt=""` only when truly decorative.
 - Heading levels that skip hierarchy in page-level content.
 
 Prefer semantic HTML before ARIA.
 
+## Page Landmarks
+
+When reviewing Web page layouts, navigation, or landmark changes, read [Page landmarks].
+Inspect the composed page with its parent layouts for missing or duplicate main regions,
+inappropriate nesting or roles, and ambiguous or broken landmark names. Check affected
+unit and E2E locators when semantic elements change. Web owns these composition rules;
+use the existing naming contract for label-source decisions.
+
+## Accessible Names And Descriptions
+
+Read [Accessible names and descriptions] when a change affects labels, ARIA naming, help/error relationships, or hidden text. That document owns the shared implementation and review contract.
+
+Flag violations supported by the final rendered behavior:
+
+- Missing or insufficient names, redundant name overrides, or naming attributes prohibited by the element's role.
+- Overrides that omit visible label wording or suppress necessary descendant information.
+- Broken or stale label/description references, including relationships lost when responsive content or overlays unmount.
+- Descriptions used instead of names, repeated help text, or essential structured content available only as a flattened description.
+
+Inspect the computed name and description in the relevant state. Matching an `aria-label` string to nearby text alone does not prove redundancy.
+
 ## Keyboard And Focus
 
 Flag:
@@ -48,7 +67,6 @@ Flag:
 - Missing stable `name` on form fields that submit or validate.
 - Incorrect input `type`, `inputMode`, `autoComplete`, or `spellCheck` for email, token, URL, number, search, code, or username fields.
 - Labels that are not clickable.
-- Submit buttons disabled before a request starts, preventing normal submit behavior.
 - Non-submit buttons inside forms missing `type="button"`.
 - Errors not associated with fields or not reachable by screen readers.
 - Error recovery that does not focus or expose the first invalid field.
@@ -56,16 +74,20 @@ Flag:
 - Placeholder text used as the only label.
 - Password managers accidentally triggered on non-auth fields because autocomplete is missing or wrong.
 
-Prefer visible labels. If visible surrounding text already labels the control, use a visually hidden label or a precise `aria-label`.
+Prefer visible labels and associate them through the appropriate field primitive, a native `label`, or `aria-labelledby`. Do not duplicate an existing label with hidden text or `aria-label`; follow [Accessible names and descriptions] when no suitable visible label exists.
 
 ## Disabled, Loading, And Async States
 
 Flag:
 
-- Loading state without `aria-busy`, `role="status"`, or another accessible update path when it changes user interaction.
+- Loading controls whose accessible name disappears, or whose user-relevant progress has no
+  feature-owned status path. Follow the Dify UI Button contract for focused loading buttons; do not
+  add `aria-busy` to a button as a generic pending-state substitute.
+- The same pending state passed to both Dify UI Button `loading` and `disabled`, which duplicates
+  state ownership and obscures whether `disabled` expresses independent unavailability.
 - Spinner or decorative loading icon exposed to screen readers.
 - Disabled controls that hide the reason users cannot proceed.
-- `aria-disabled` used without manually blocking click, Space, and Enter.
+- Controls marked `aria-disabled` that still activate through supported pointer or keyboard input. Check the primitive's handling before requesting manual event guards.
 - Toasts, inline validation, or async status changes that are not announced when users need the update to continue.
 - Icon-only loading/error affordances without text or accessible status where the state matters.
 
@@ -90,7 +112,7 @@ Use Popover for explanatory content, rich help, and infotips. Use Tooltip only a
 Flag:
 
 - Text in flex/grid children without `min-w-0` when it can overflow.
-- Names, labels, file names, model names, workspace names, or user content lacking `truncate`, `line-clamp`, or `break-words`.
+- Long names, labels, or user content that overflow, obscure adjacent controls, or become unreadable in supported layouts.
 - Right-side icons, badges, checks, or actions that shrink before the text area.
 - Empty arrays or empty strings rendering broken layout instead of an empty state.
 - Button, tab, badge, chip, menu item, or card text that can overlap sibling controls at common viewport widths.
@@ -107,3 +129,7 @@ Flag:
 - Images without dimensions.
 - Loading copy using `...` instead of `…`.
 - Hardcoded dates, times, numbers, or currency formats instead of `Intl.*`.
+
+[Accessible names and descriptions]: ../../../../packages/dify-ui/docs/accessible-names-and-descriptions.md
+[Page landmarks]: ../../../../web/docs/landmarks.md
+[Web Interface Guidelines]: https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

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

@@ -26,15 +26,17 @@ Prefer:
 
 ## Styling
 
+For Dify UI/Base UI state styling and callback composition, apply the package's [Styling] contract,
+including its documented reasons for direct state access.
+
 Flag:
 
 - New CSS modules or ad hoc CSS when Tailwind utilities and Dify tokens cover the need.
 - Component-level plain `.css` files or component CSS imported through `globals.css`; use scoped `*.module.css` only when Tailwind and component variants cannot express the style.
 - Generic color utilities where Dify semantic tokens exist.
-- Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or documented radius mappings exist.
+- Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or standard Tailwind radius classes match the required design value. Apply [Styling] when choosing radius classes.
 - `!` important modifiers or important CSS overrides without a narrow, documented reason.
-- Manual string concatenation, template strings, array `.join(' ')`, or custom ternaries for conditional or multi-line classes.
-- JS conditional class branches for primitive visual states already exposed by Dify UI/Base UI `data-*` selectors.
+- Manual class-list assembly through string concatenation, template strings, array `.join(' ')`, or a custom conditional combiner instead of `cn(...)`. Conditional values passed to `cn(...)` remain valid.
 - Incoming `className` placed before default classes in `cn(...)`, preventing call-site overrides.
 - Arbitrary z-index or one-off layering fixes on overlays.
 
@@ -43,7 +45,6 @@ Use:
 - `cn(...)` from the local package or utility already used by the file.
 - Dify semantic tokens and Tailwind v4 utilities.
 - Existing component variants before one-off class forks.
-- Primitive selectors such as `data-disabled:*`, `data-checked:*`, `data-highlighted:*`, `group-data-*`, `peer-data-*`, and `has-[:focus-visible]` before adding React state or boolean props solely for styling.
 - Component-level variants, semantic tokens, and normal cascade/order before `!` overrides. Use `!` only for a contained compatibility override that cannot be expressed through the component API or local selector structure.
 
 ## Imports
@@ -66,3 +67,5 @@ Flag:
 - Error messages that state only the failure and not the next step.
 
 Use feature-local translation keys by default. Alias only when crossing namespaces. `pnpm i18n:check --file <name>` should pass for any touched translation namespace.
+
+[Styling]: ../../../../packages/dify-ui/docs/styling.md

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

@@ -1,101 +1,31 @@
-# Component Architecture Rules
+# Component Architecture Review
 
-Use these rules for React component structure, ownership, state, props, effects, and module organization.
+Use the canonical reference for the changed concern. These links share rules; they do not activate the implementation skill or its workflow.
 
-## Ownership
+| Concern | Canonical rules |
+| --- | --- |
+| Vertical modules, public entrypoints, data/handler placement, wrappers, Props, and types | [Ownership] |
+| Local/Jotai state, form drafts, route identity, URL state, and persistence | [State] |
+| Effects, navigation, memoization, and subscriptions | [Runtime] |
+| Hotkeys, focus, and secondary surfaces | [Interactions] |
 
-Flag:
+## Apply Rules In Their Actual Scope
 
-- State, query, mutation, or handlers hoisted above the lowest component that actually uses them.
-- Parent components owning row/item actions that do not coordinate a workflow.
-- Prop drilling through multiple pass-through layers.
-- A page/tab-level section component becoming the data owner without needing a shared snapshot or shared loading/error/empty UI.
-- Feature code promoted to shared only because it appears once or might be reused later.
+Explicit team conventions are reviewable contracts, including module organization and public API boundaries. Check the documented exception before reporting a violation. Do not infer an exception solely because the code appears to work, or invent a user-facing failure for a convention finding.
 
-Accept repeated TanStack Query calls in siblings when each component independently consumes the data. Cache deduplication is not a reason to hoist by itself.
+- For owner placement, trace the consumers and required lifetime. Establish whether the parent coordinates a snapshot, submission, navigation, shared UI, or persistence before asking to move state or handlers.
+- For component boundaries, identify the ownership or encapsulation the proposed extraction would improve; file length alone establishes neither.
+- For props and types, check the domain contract and public API. Do not report private props typing style alone; declaration/export syntax matters only for a documented package rule or concrete type, export, or framework defect.
+- For state and Effects, trace the source of truth, external synchronization target, and mount/reset boundary. Controlledness alone does not prove that a draft is lifted or persisted; follow the form and overlay contracts linked by [State].
+- For navigation, distinguish ordinary links from mutation success, guarded redirects, command flows, and submission side effects.
 
-## Component Boundaries
+## Preserve Existing Product Contracts
 
-Flag:
+During refactors, trace the interaction being moved through its real consumer. Navigation, sidebar, dropdown, webapp-list, and app-switching changes must preserve expansion controls, hover persistence, pin/delete actions, routing, keyboard/focus handling, and open-state ownership where present.
 
-- React component files over 300 lines when the file mixes multiple responsibilities that can be split into focused colocated components, hooks, or utilities.
-- Shallow wrappers that only rename props or hide the real primitive.
-- Extra DOM wrappers that do not provide layout, semantics, accessibility, state ownership, or library integration.
-- Dialog/dropdown/popover hidden surfaces that obscure the parent flow when they should be extracted into a small local component.
-- Business forms, menu bodies, or one-off helpers moved away from their owner without reuse or semantic value.
+Check that the changed owner still handles reachable empty, loading, and missing optional-data states, and that primitive wrappers preserve accessible semantics and the public controlled-state contract. Report the actual lost behavior or explicit rule violation; use the package testing policy when assessing regression coverage.
 
-Prefer colocated components split by actual data and state needs.
-
-## Bad Component Design Patterns
-
-Flag:
-
-- Refactors of existing navigation, sidebar, dropdown, webapp list, or app-switching UI that do not preserve behavior-sensitive interactions such as expand/collapse arrows, hover persistence, pin/delete controls, routing, keyboard/focus handling, or open-state ownership.
-- Components that mix data fetching, mutation side effects, popup state, form validation, layout, and row rendering without a clear owner.
-- Generic components with many boolean props that encode one feature's workflow.
-- A shared component that imports feature-specific copy, routes, or API contracts.
-- A feature component that accepts pre-rendered fragments only to avoid placing ownership correctly.
-- A child component that receives both raw server data and separately derived flags for the same concept.
-- A wrapper that changes accessible semantics of the primitive it wraps.
-- A component that exposes controlled props but still keeps a competing private state for the same value.
-- A component that cannot render empty, loading, or missing optional API fields without caller-side preprocessing.
-
-When existing components already own interaction logic, prefer reusing or extending them. If a refactor is necessary, preserve the old interaction contract and add or update focused tests for changed behavior.
-
-## Props And Types
-
-Flag:
-
-- Declaration or export rewrites made only for stylistic uniformity, without changing an owned behavior or contract.
-- Named `Props` types for trivial one-off props where inline typing is clearer.
-- Props named by UI implementation instead of domain/API role.
-- API data converted too early or under a generic name that breaks traceability.
-- Callers duplicating fallback checks that the lowest rendering component already handles.
-
-Do not flag `FC`, `React.FC`, function declarations, arrow functions, named exports, or default exports by syntax alone. Report them only when the chosen form causes a concrete type, lifecycle, export, framework, or enforced package-contract defect.
-
-## Effects
-
-Flag effects that:
-
-- Transform props/state for rendering.
-- Copy one state value into another representing the same concept.
-- Handle user actions that belong in event handlers.
-- Reset local state from props or visibility when derivation, a stable semantic identity, or the intended mounted owner already expresses the lifecycle.
-- Fetch data that belongs in framework APIs or TanStack Query.
-
-If an effect remains, it must synchronize with a named external system: browser API, subscription, timer, analytics-on-visibility, non-React widget, or imperative DOM integration.
-
-## State Modeling
-
-Flag:
-
-- Storing derived booleans, disabled flags, default tabs, or loading labels that can be calculated from current query/feature state.
-- Per-session state held by a longer-lived visibility coordinator and cleared through an open-state Effect or a generated key when the primitive's mounted-content lifecycle already matches the intended state lifetime.
-- A DOM field mirrored into competing prop, default, and React state sources when editing does not require those sources to synchronize.
-- Local state used to fake server data or generated contract fields.
-- UI state persisted to localStorage when it is live app state.
-- Feature-local mock shells wired to unrelated existing APIs before the real API is confirmed.
-
-Review state lifetime before its storage mechanism. For a hidden surface, distinguish the
-visibility coordinator from mounted content. State private to one mounted session belongs in that
-content owner; promote it only when the draft must survive that content owner's unmount or another
-owner coordinates it. A stable semantic identity key may create a new snapshot when the represented
-identity changes; a generated key is not a routine reset command.
-
-Prefer render-time derivation. Keep true local state for user choices, transient input, controlled
-popups, and feature UI state that has no server source. Submit-only DOM fields may remain
-uncontrolled; use local controlled state when React must own the current value to drive rendering
-or coordination. Observing change events or tracking a derived fact such as dirty state does not
-require mirroring the field value. Do not flag controlled state by itself without a concrete
-competing-source, stale-state, or ownership defect.
-
-## Navigation
-
-Flag:
-
-- Imperative router navigation for ordinary links.
-- Button semantics used for navigation.
-- Navigation state hidden in component state when URL state is required for shareable filters, tabs, or pagination.
-
-Use `Link` for normal navigation. Use router APIs for mutation success, guarded redirects, command flows, or form submission side effects.
+[Interactions]: ../../how-to-write-component/references/interactions.md
+[Ownership]: ../../how-to-write-component/references/ownership.md
+[Runtime]: ../../how-to-write-component/references/runtime.md
+[State]: ../../how-to-write-component/references/state.md

.agents/skills/frontend-code-review/references/data-query-contracts.md

@@ -1,74 +1,28 @@
-# Data, Query, And Contract Rules
+# Data, Query, And Contract Review
 
-Use these rules for generated contracts, TanStack Query, mutations, auth/SSR boundaries, URL state, and client persistence.
+[Data and queries] owns generated-client, Query options, mutation/cache, imperative access, SSR, authentication, and tenant rules. [State ownership] owns URL state and persistence. Read only the reference needed by the diff; reading a shared reference does not activate its implementation skill.
 
-## Generated Contracts
+## Generated Contracts And Query Conventions
 
-Flag:
+Review explicit team conventions as contracts, including direct generated options, `skipToken` for missing required input, and shared cache policy. A lint rule may enforce part of a convention; neither a green lint result nor a suppression proves the full contract is satisfied.
 
-- New legacy service/helper wrappers around generated `queryOptions()` or `mutationOptions()`.
-- Continuing to use deprecated contract operations when a ready generated contract exists.
-- Assuming a generated file means an operation is ready without checking deprecated markers, schema shape, and the actual UI consumer.
-- Re-declaring API DTOs in components.
-- Adding compatibility layers instead of migrating the pointed line and deleting the old layer.
+- Establish whether the changed call belongs to a new or migrated surface and whether the generated operation is ready. Check deprecated markers, schema shape, and the real UI consumer before prescribing a migration.
+- Distinguish a pass-through wrapper from a feature hook with actual orchestration. Check whether an independent execution condition or Promise composition justifies the documented query/mutation exception.
+- Trace generated input and output types through their boundaries. Identify the exact DTO mirror, field widening, placeholder input, or lost intentional empty value when reporting a violation.
+- Check whether a local mutation callback owns feature feedback or replaces shared invalidation, retry, or cache defaults. Match optimistic changes to the current list/detail owner.
 
-Backend Pydantic and OpenAPI schemas own API shape. Generated clients and schemas under `packages/contracts/generated/*` are authoritative at frontend boundaries and use the `{ params, query?, body? }` input shape.
+## Imperative Access And SSR
 
-## Queries
+- Check freshness, projection, retries, and the caller's execution condition separately against [Data and queries]. Trace Promise ownership to distinguish an awaited hard gate from soft prefetching with an explicit failure owner.
+- For Server Components, identify who renders the data and who may revalidate it. Check dehydration, the same-key client consumer, error handling, and the intended Suspense/server-rendered-content contract when the diff changes streaming.
+- For auth, setup, roles, branding, or availability, trace authoritative data and the loading/fallback path. A static redirect or placeholder value cannot stand in for a request-dependent decision.
 
-Flag:
+## Tenant, URL, And Persistence Boundaries
 
-- `enabled` used to hide missing required input instead of `input: skipToken`.
-- Fake fallback IDs or placeholder inputs used to force a query to run.
-- Query results copied into local state for rendering.
-- Shared query behavior such as invalidation, stale defaults, or retry rules reimplemented at call sites.
-- `prefetchQuery` treated as a hard gate or as returning data/errors to the caller.
+- Trace the current workspace-switch flow and cache lifetime before reporting missing identity in a query key. Verify backend meaning before treating `workspace_id` and `tenant_id` as interchangeable.
+- For URL and storage changes, identify whether the value is shareable navigation state, live app state, a one-shot signal, or a low-frequency preference. Apply [State ownership] to that category and verify its write/reset owner.
 
-Use `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))` directly unless a feature hook performs real orchestration.
+Report the violated rule and applicable scope or the concrete failing path. Do not invent runtime impact when the finding is a team-convention violation.
 
-## Mutations
-
-Flag:
-
-- Deprecated `useInvalid` or `useReset`.
-- `mutateAsync` used without a need for Promise semantics.
-- Awaited mutations without `try/catch`.
-- Components owning shared cache invalidation that belongs in query defaults.
-- Optimistic updates that do not match current list/detail ownership.
-
-Use generated `mutationOptions()` directly when possible. Put shared cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`.
-
-## SSR, Auth, And Route Boundaries
-
-Flag:
-
-- Request-time auth, setup, workspace role, or tenant decisions moved into static `next.config redirects()`.
-- Dynamic role gates depending on `workspaces.current` implemented as static path redirects.
-- Authorization logic depending on soft `prefetchQuery`.
-- Removing a client fallback before server API unavailable behavior is defined.
-- Global placeholder query contracts introduced to solve a route-local Suspense issue.
-- Branding-sensitive UI reading placeholder defaults without checking pending/placeholder state.
-
-Separate hard gates from soft prefetches. `fetchQuery` can be a server decision boundary; `prefetchQuery` is cache warmup.
-
-## Workspace And Tenant
-
-Flag:
-
-- Treating workspace switch as ordinary CRUD invalidation when the current app flow performs server switch plus full reload.
-- Query keys that omit workspace/tenant identity when the query truly varies by workspace and no full reload boundary applies.
-- Mixing `workspace_id` and `tenant_id` without tracing the current backend/API contract.
-
-Current Dify workspace switch should be reviewed as a tenant cache boundary first.
-
-## URL State And Local Storage
-
-Flag:
-
-- Shareable filters, tabs, pagination, selected panels, or search state hidden only in component state.
-- One-shot navigation signals modeled as subscribed persistent state.
-- Live app state stored in localStorage.
-- Direct `window.localStorage`, `globalThis.localStorage`, or raw storage calls in app code.
-- High-frequency interaction state persisted on every change instead of on commit/settle.
-
-Use URL state for shareable UI state, feature/Jotai/store state for live UI state, and `@/hooks/use-local-storage` only for low-frequency client-only preferences, dismissed notices, and UI defaults.
+[Data and queries]: ../../how-to-write-component/references/data.md
+[State ownership]: ../../how-to-write-component/references/state.md

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

@@ -16,7 +16,7 @@ owner:
 | Forms and field semantics                  | `packages/dify-ui/docs/forms.md`                                     |
 | Selection and typed values                 | `packages/dify-ui/docs/selection.md`                                 |
 | Portals, layers, and floating surfaces     | `packages/dify-ui/docs/overlays.md`                                  |
-| Tailwind and radius tokens                 | `packages/dify-ui/docs/styling.md`                                   |
+| State styling, callbacks, and Tailwind     | `packages/dify-ui/docs/styling.md`                                   |
 | Package tests and Storybook                | `packages/dify-ui/docs/testing.md`                                   |
 
 For consumer code under `web/`, also read `web/AGENTS.md` for application-owned reuse policy and

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

@@ -71,8 +71,6 @@ Flag:
 
 ## React Flow
 
-For workflow React Flow components, keep this Dify-specific rule:
+Use [Dify invariants] for React Flow node/edge consumption and provider availability in RAG Pipe template rendering. Callback-only reads or mutations can use `useStoreApi`.
 
-- UI consumption should use React Flow hooks such as `useNodes` / `useEdges`.
-- Callback-only reads or mutations can use `useStoreApi`.
-- Node components under `web/app/components/workflow/nodes/[nodeName]/node.tsx` must not depend on workflow stores that are absent in RAG Pipe template rendering.
+[Dify invariants]: dify-invariants.md

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

@@ -1,6 +1,6 @@
 # Testing Review Rules
 
-`web/docs/test.md` is the canonical frontend testing policy. Use this file only to translate that policy into review findings.
+Use `web/docs/test.md` for tests owned by `web/` and `packages/dify-ui/docs/testing.md` for tests owned by Dify UI. These owners define their test boundaries, environments, and checks; this reference only adds review questions.
 
 ## Request Missing Tests When Risk Justifies Them
 
@@ -13,7 +13,7 @@ Flag missing coverage when a change alters a reachable contract such as:
 - 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 mechanical changes, pass-through wrappers, implementation details, or visual-only styling unless they affect behavior. Low coverage alone is not a finding.
+Do not request tests for mechanical changes, pass-through wrappers, implementation details, or incidental visual styling. Low coverage alone is not a finding.
 
 ## Flag Low-Value or Fragile Tests
 
@@ -30,8 +30,8 @@ Flag tests that:
 
 - 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.
+- Check mocks against the owning package's policy; allowed mocks must preserve the public contract and leave the behavior under review real.
+- Apply the owning package's admission policy before requesting new automation. Real-browser verification can be a one-off review; a simulator limitation alone does not justify a permanent test.
+- Check that assertions prove the claimed outcome and add evidence beyond existing tests; a browser runtime does not make weak assertions stronger.
 
 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

@@ -5,12 +5,9 @@ description: Use when writing or changing Vitest or React Testing Library tests
 
 # Frontend Testing
 
-`web/docs/test.md` is the single policy owner. Read it before changing frontend tests; this skill adds no separate requirements.
+Read the testing policy for the package that owns the changed tests:
 
-1. Identify the observable contract and regression risk.
-2. Choose the smallest boundary that includes the behavior owner.
-3. Establish the failing case first when practical, then implement one coherent scenario.
-4. Run the focused spec before the affected suite and relevant static checks.
-5. Report the behavior verified and any remaining browser, visual, or end-to-end risk.
+- `web/`: `web/docs/test.md` owns Web test boundaries, environments, and commands.
+- `packages/dify-ui/`: `packages/dify-ui/docs/testing.md` owns primitive test boundaries, environments, Storybook, and commands.
 
-Recommend deleting low-value tests as readily as adding missing behavior coverage. Use `web/docs/test.md` for policy and Web commands; use `packages/dify-ui/docs/testing.md` for Dify UI commands.
+This skill adds no parallel policy or check sequence. Follow the selected owner's requirements, including its validation commands. Recommend deleting low-value tests as readily as adding missing behavior coverage, and report the contract verified and any material verification gap.

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

@@ -7,34 +7,26 @@ description: Use when implementing or refactoring React/TypeScript components an
 
 Use this skill to route component architecture decisions to its bundled references. Read only the references required by the current change.
 
-## First Decisions
-
-| Question | Default | Choose differently when |
-| --- | --- | --- |
-| Where should code live? | In the product workflow, route, or feature owner. | Several verticals need the same stable contract. |
-| Who owns state and handlers? | The lowest owner that consumes them and whose lifetime matches the state. | Another owner coordinates the value or it must survive the local owner's unmount. |
-| Should React control a value? | Leave submit-only DOM fields uncontrolled. | The workflow must own the current value to drive rendering or coordination. |
-| Should state enter Jotai? | Keep component and form state local. | Siblings need one source of truth or scoped workflow persistence. |
-| Who owns URL state? | Next.js route APIs and `nuqs`. | Atoms require a read-only route-identity bridge. |
-| Who owns remote state? | TanStack Query at the lowest consumer. | Atom state drives the query or shared derivations consume it. |
-| Is a wrapper needed? | Use the primitive or direct code. | The wrapper owns behavior, validation, state, or semantics. |
-| Is an Effect needed? | Derive during render or handle the user action. | A named external system must be synchronized. |
-
 ## Topic Routing
 
 - Component moves, module boundaries, props, types, or owner placement: read [`references/ownership.md`][ownership].
+- Dify UI wrappers or primitive state styling: read the package's [Public API authoring] and [Styling] contracts.
 - Jotai, form drafts, route identity, URL state, or persistence: read [`references/state.md`][state].
 - Generated contracts, nullable API data, Query, mutations, SSR, auth, or workspace state: read [`references/data.md`][data].
 - Hotkeys, focus, dialogs, menus, popovers, or other secondary surfaces: read [`references/interactions.md`][interactions] and the overlay guide it references when applicable. Also read [`references/state.md`][state] when the surface owns a draft or other local session state.
 - Effects, navigation, memoization, preloading, or render cost: read [`references/runtime.md`][runtime].
 
-## Workflow
+## Scope And Verification
 
-1. Identify the behavior owner, the required state lifetime, and the public contract being changed.
-2. Read the nearby implementation, tests, and only the routed skill references.
-3. Implement one coherent vertical slice. Do not expand into equivalent patterns elsewhere unless the current contract cannot be completed without them.
-4. Verify observable behavior at the narrowest sufficient boundary, then run the checks documented by the owning package: `web/docs/test.md` or `web/docs/lint.md` for Web, and `packages/dify-ui/docs/testing.md` for Dify UI.
+Identify the behavior owner, state lifetime, and public contract from the nearby implementation and relevant references. Keep the change within that vertical slice unless the contract requires changes elsewhere. Verify the changed behavior and complete the owning package's required checks. For Web, read `web/docs/test.md` for test work and `web/docs/lint.md` for static checks. Dify UI verification is owned by `packages/dify-ui/docs/testing.md`.
 
+## Tailwind CSS
+
+- Write canonical Tailwind v4 classes; prefer canonical utilities over equivalent arbitrary values.
+- Common forms include `w-105` instead of `w-[420px]`, `px-2.25` instead of `px-[9px]`, `bg-linear-to-b` instead of `bg-gradient-to-b`, `wrap-break-word` instead of `break-words`, and `field-sizing-content` instead of `[field-sizing:content]`.
+
+[Public API authoring]: ../../../packages/dify-ui/docs/authoring.md
+[Styling]: ../../../packages/dify-ui/docs/styling.md
 [data]: references/data.md
 [interactions]: references/interactions.md
 [ownership]: references/ownership.md

.agents/skills/how-to-write-component/references/data.md

@@ -8,9 +8,10 @@ Read this document when a component consumes generated contracts, nullable API v
 - Backend Pydantic and OpenAPI schemas own API shape. Follow the generated `{ params, query?, body? }` input shape; when it is wrong, fix the backend schema and regenerate `packages/contracts/generated/*`.
 - Do not hand-write DTO mirrors, widen generated fields or enums, edit generated output, or add a parallel frontend status layer unless it models product state absent from the API.
 - Check deprecated markers, schema shape, and the actual consumer before assuming that a generated operation is ready to use.
+- When a ready generated operation exists for the changed call, migrate deprecated operations and remove the replaced layer instead of adding compatibility wrappers.
 - Normalize only at real boundaries such as user input, search, URL params, filenames, DOM IDs, or a required legacy adapter.
 - Preserve `null`, `undefined`, and intentional empty strings until the final boundary. Do not use `value || undefined` when an empty string means clearing a field.
-- Build required values in the branch that proves them. Avoid `filter(Boolean)`, truthiness filters, non-null assertions after filters, and placeholder values used only to satisfy types.
+- Build required values in the branch that proves them. Do not use truthiness filters, non-null assertions, or placeholders to conceal missing required input or discard valid `0`, `false`, or empty-string values.
 
 ## Queries
 
@@ -18,25 +19,40 @@ Read this document when a component consumes generated contracts, nullable API v
 - If query input comes from atom state, keep it in `atomWithQuery`; do not unwrap the atom in a component solely to call `useQuery`.
 - For missing required input, branch the whole generated input with `skipToken`. Add `enabled` only for an independent execution condition; do not put `skipToken` inside a placeholder payload or coerce IDs to empty strings.
 - Return generated `queryOptions()`, `infiniteOptions()`, or `mutationOptions()` directly from TanStack Query atoms. Pass supported options into the generated call instead of spreading into a parallel object.
-- Share the exact options between prefetch and render when they represent the same request. Do not extract option helpers merely to reuse input construction.
+- For the same logical request, preserve key, input, operation, and result contracts. Reuse exact options only when
+  transport, context, and cache policy are shared; imperative and observer freshness may differ. Do not extract a helper
+  merely to reuse input construction.
 - Avoid pass-through service hooks that only rename generated options. Keep feature hooks for actual orchestration or shared domain behavior.
 
 ## Mutations And Cache
 
 - Use generated `mutationOptions()` directly for owner-local mutations.
-- Put shared invalidation, retries, and cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`. Local callbacks may own toast, close, and navigation effects but must not replace shared cache policy.
+- Do not introduce deprecated `useInvalid` or `useReset` APIs.
+- Put shared invalidation, retries, and cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`. In oRPC v1, caller options override defaults, including callbacks. Local callbacks may own toast, close, and navigation effects but must preserve shared cache behavior.
 - Prefer `mutate(...)`. Use `mutateAsync(...)` only when Promise composition is required, and catch awaited failures.
 - Preserve intentional empty values and current list/detail ownership when updating data. Do not add optimistic updates without a verified owner contract.
 
 ## Prefetch And Hidden Surfaces
 
 - Prefetch expensive secondary content from the trigger or menu-open event when it benefits the visible path. Do not mount hidden subscribers solely to warm the cache.
-- `prefetchQuery` is cache warmup, not an authorization or availability gate. Use a hard fetch boundary when the server must decide whether rendering may proceed.
+- Use `query` or `infiniteQuery` for imperative access. `staleTime` defines cache acceptance; `select` projects the return
+  value without replacing cached query-function data. Imperative queries default to no retries when `retry` is not
+  configured, and observer-only `enabled` does not prevent an imperative call.
+- Migrate deprecated `fetchQuery`, `prefetchQuery`, `ensureQueryData`, and their infinite variants when the current `query` or `infiniteQuery` contract applies. A `staleTime` of `0` treats data as stale; a finite value accepts that freshness window; `Infinity` accepts data until invalidation; `'static'` accepts available data even after invalidation.
+- `await` blocks, `return` transfers the Promise, and `void` discards its value without handling rejection. Handle
+  rejection before discarding a potentially rejecting Promise; use `.catch(noop)` only for intentional silence or
+  feedback owned elsewhere. Hard server gates await the query and preserve rejection.
 
 ## SSR, Authentication, And Workspace
 
 - Static configuration owns path-invariant routing. Request-dependent authentication, setup, role, and tenant decisions belong to SSR or runtime decision boundaries.
 - Distinguish soft SSR cache warming from authoritative decisions. Prefetched or placeholder data must not grant access or represent successful availability.
+- Treat Server Components as query prefetch-and-dehydrate owners by default. Do not render or pass an imperative query
+  result when a browser observer can revalidate the same data unless ownership and freshness explicitly prevent drift.
+- Non-blocking RSC streaming requires pending-query dehydration without redacting Next.js server errors, a
+  `HydrationBoundary` around the same-key client consumer, and Suspense when that content must be server-rendered.
 - Never reuse tenant-scoped state after switching workspaces. Discard it at the switch boundary or isolate it by workspace identity.
+- Trace the current switch flow before choosing cache handling: server switch plus full reload is a tenant boundary, not ordinary CRUD invalidation. Include workspace identity in varying query keys when no full-reload boundary applies, and trace the backend contract before interchanging `workspace_id` and `tenant_id`.
 - Do not make product or authorization decisions from bootstrap defaults. Wait for authoritative data, or render an explicit loading or error state.
+- Preserve an existing client fallback until server API-unavailable behavior has an explicit owner.
 - Keep loading and Suspense behavior inside the feature that owns the request. Do not add fake global data merely to bypass that boundary.

.agents/skills/how-to-write-component/references/interactions.md

@@ -23,10 +23,9 @@ Read this document when a change involves application hotkeys, focus, dialogs, m
 - Follow the [overlay contract] for primitive choice and shared mechanics. The nearest consumer `AGENTS.md` owns application-specific composite reuse policy.
 - Separate behavior ownership from placement ownership: the action may own trigger, open state, and menu content while the caller owns slots, offsets, and alignment.
 - Keep menu and dialog surfaces as siblings when a menu command opens a dialog. Mount the dialog outside popup content.
-- Keep overlay open-state ownership separate from content-session ownership. A controlled root does not require controlled fields or root-owned drafts.
-- Match transient state to the primitive's content mount lifecycle. State below an unmounting content boundary gets a fresh instance after unmount; intentionally kept-mounted content needs an explicit persistence or reset policy.
-- Keep a controlled overlay root at its coordination owner so the primitive can complete exit transitions, focus restoration, and detached-handle behavior. Do not conditionally remove the root to reset content state, and use keys only for stable semantic identity.
+- Use the [overlay contract] to determine content lifetime and preserve the Root's closing lifecycle. Follow [state ownership] for draft placement and semantic identity; portal placement alone does not locate the state owner.
 - Place query subscriptions and mutation observers at the owner whose lifetime matches when they should run. Mounted-session work may belong inside content; work that must start or stop exactly with `open` needs an explicit open-state condition.
 - Prefer primitive-owned open state unless another owner must observe or coordinate it. Analytics callbacks and local cleanup alone do not require a controlled root.
 
 [overlay contract]: ../../../../packages/dify-ui/docs/overlays.md
+[state ownership]: state.md

.agents/skills/how-to-write-component/references/ownership.md

@@ -14,27 +14,32 @@ Read this document when adding, moving, splitting, or refactoring React componen
 
 - Put state, data access, loading, empty, error, and handlers in the lowest owner that uses them and whose mounted lifetime matches the required persistence.
 - Keep coordination in a parent only when it needs one consistent snapshot, the value must intentionally survive the local owner's unmount, or the parent coordinates submission, shared selection, batch behavior, navigation, or cross-section loading and errors.
-- Repeated TanStack Query calls in siblings are acceptable when each sibling independently consumes the data; the cache already deduplicates requests.
+- Repeated TanStack Query hooks for the same key and input in Client Component siblings under one QueryClient are
+  acceptable; shared cache is not a reason to hoist. Separate Server Component QueryClients do not share it, so
+  request-level deduplication needs an identified request-local cache or verified framework or transport owner.
 - Pass stable domain identity across boundaries. Do not pass raw server data together with separately derived flags for the same concept.
-- One pass-through prop layer is acceptable. Repeated forwarding means ownership should move closer to the consumer or into feature-scoped shared state.
+- Revisit prop forwarding when intermediate components obscure the behavior owner; keep clear data flow rather than introducing shared state merely to avoid passing props.
 - Do not replace prop drilling with one large view-model hook. Move each query, derived value, and handler to the concrete owner that consumes it.
 - Keep source selection, defaults, validation, dirty checks, and payload shaping beside the workflow that owns submission.
 
 ## Boundaries
 
+- Prefer reusing or extending the component that already owns an interaction over rebuilding that behavior in a parallel component.
 - State-heavy wizards, drawers, modals, and secondary workflows can form a small vertical surface with an entrypoint, optional feature-local state, and shallow owners matching real visual regions.
 - The entrypoint owns route integration, provider wiring, placement, and open-state coordination. A content or session owner keeps state scoped to that mounted surface.
 - Judge hook lifetime by the component that declares the hook and the primitive's mount contract, not only by where its rendered controls appear in JSX.
 - Separate hidden dialogs, dropdowns, and popovers into small local owners when their content obscures the parent flow.
 - Keep cohesive forms, menu bodies, and one-off helpers local unless they have their own state, reuse, or semantic boundary.
+- Extract components or hooks when they clarify ownership or hide a cohesive implementation; keep logic local when extraction only shortens the file or relocates the same coordination.
 - Avoid wrapper components and wrapper DOM that only rename props, pass children through, or hide the real primitive. A wrapper must own behavior, validation, state, accessibility, layout, or library integration.
+- Keep feature workflows out of shared components: do not encode one feature through many boolean props or import its copy, routes, and API contracts into a generic component. Do not pass pre-rendered fragments merely to avoid assigning the behavior to its owner.
 - Loading states for page sections, cards, lists, tables, forms, and drawers should use skeletons scoped to the loaded content. Reserve spinners for small inline busy indicators.
 
 ## Components And Types
 
 - Choose component declaration and export forms from the actual component contract, framework requirements, and enforced package rules. Existing style is context, not authority; do not rewrite unaffected code solely to normalize `FC`, `function`, arrow-function, named-export, or default-export forms.
-- Type simple one-off props inline. Name a `Props` type when it is reused, exported, complex, or materially clearer.
 - Use API-generated or API-returned types at component boundaries. Keep one-off UI refinements and conversions beside their owner.
+- Name props and converted data after their domain/API role, preserving traceability to the original contract.
 - Preserve domain value types for selections. Do not widen enums, unions, booleans, numbers, objects, or nullable values to `string` before a real boundary requires it.
 - Avoid generic `common.tsx` buckets and aliases that only rename another type. Name files, values, and public types after their domain role.
 - Put fallback and invariant checks in the lowest component that already renders that state. Do not extract helpers whose only purpose is hiding missing display data.

.agents/skills/how-to-write-component/references/state.md

@@ -11,18 +11,19 @@ Read this document when a change involves Jotai, form drafts, route identity, sh
 
 ## Forms And Sessions
 
-- Keep form state in the narrowest owner whose lifetime matches the draft. A draft scoped to one mounted surface belongs to that content or session owner; a draft that must survive its current owner's unmount belongs to an explicit longer-lived feature owner.
-- Prefer uncontrolled fields when values are only read at submit time. Use local controlled state only when React must own the current value to drive dependent UI or linked fields; track derived facts such as dirty state without mirroring the field value. Controlledness does not decide whether a draft is local or persisted.
+- Follow the [form contract] for field controlledness and the [overlay contract] for Root/content mounting and state lifetime. These primitive contracts also apply when reviewing a consumer.
+- Choose the Web draft owner from the required lifetime. Keep mounted-session drafts in the content owner; start with the lowest shared React owner when another component needs the draft or it must survive unmounting. Use feature-scoped atoms only when their coordination or persistence contract is needed.
 - For query-backed defaults, establish the form session after the required defaults are available. `defaultValue` initializes the current mount; a stable semantic identity key may create a fresh snapshot when the represented identity changes. Do not use a generated key as a routine reset command.
-- Promote drafts beyond the session only when another owner reacts to in-progress values, several workflow steps share one draft, or the draft must intentionally survive unmounting. Start with the lowest shared React owner; use feature-scoped atoms only when their coordination or persistence contract is needed.
 - Keep validation, source priority, fallback behavior, dirty checks, and payload assembly in the workflow that owns submission.
+- Derive booleans, disabled flags, default tabs, and loading labels from current state. Do not mirror one value into competing prop, default, and local sources; controlled state alone is not a competing-source defect.
+- Do not use local state to fake server data or generated contract fields, or connect a feature mock shell to an unrelated API before its actual contract is confirmed.
 
 ## Route And URL State
 
 - Treat `useParams`, route arguments, and `nuqs` as the owners of URL identity and updates.
 - Hydrate a primitive atom at the route or surface boundary only when query atoms or shared derived atoms require route identity. Keep URL writes in route and query-state APIs.
 - Within one route-owned feature, choose one route-identity source. Do not hydrate route identity into atoms while also threading the same ID through multiple component layers.
-- Put shareable filters, tabs, pagination, and search state in the URL. Keep one-shot navigation signals and transient UI state out of persistent subscriptions.
+- Put shareable filters, tabs, selected panels, pagination, and search state in the URL. Keep one-shot navigation signals and transient UI state out of persistent subscriptions.
 
 ## Jotai And Query
 
@@ -38,3 +39,6 @@ Read this document when a change involves Jotai, form drafts, route identity, sh
 - Use feature-owned storage modules built on `createLocalStorageState`; callers should not scatter direct storage access or raw keys.
 - Persist high-frequency interaction state only on commit or after updates settle.
 - Do not add ad hoc global event listeners for shared state. Centralize subscriptions through the owning atom, store, or subscription hook.
+
+[form contract]: ../../../../packages/dify-ui/docs/forms.md
+[overlay contract]: ../../../../packages/dify-ui/docs/overlays.md

.github/CODEOWNERS

@@ -26,6 +26,9 @@
 /cli/ @GareArc
 /.github/workflows/cli-tests.yml @GareArc
 
+# Dify Agent
+/dify-agent/ @BeautyyuYanli
+
 # E2E
 /e2e/ @lyzno1
 /.github/workflows/web-e2e.yml @lyzno1
@@ -33,8 +36,24 @@
 # Backend (default owner, more specific rules below will override)
 /api/ @QuantumGhost
 
-# Backend - Tests
+# Backend - Tests (default owners, domain-specific rules below will override)
 /api/tests/ @laipz8200 @QuantumGhost
+/api/tests/*/core/rag/ @JohnJyong
+/api/tests/*/services/rag_pipeline/ @JohnJyong
+/api/tests/*/services/dataset_service/ @JohnJyong
+/api/tests/*/controllers/console/datasets/ @JohnJyong
+/api/tests/*/controllers/service_api/dataset/ @JohnJyong
+/api/tests/*/vdb/ @JohnJyong
+/api/tests/*/core/plugin/ @WH-2099
+/api/tests/*/services/plugin/ @WH-2099
+/api/tests/*/controllers/inner_api/plugin/ @WH-2099
+/api/tests/*/plugin/ @WH-2099
+/api/tests/*/controllers/trigger/ @CourTeous33
+/api/tests/*/core/trigger/ @CourTeous33
+/api/tests/*/trigger/ @CourTeous33
+/api/tests/*/controllers/console/billing/ @zyssyz123
+/api/tests/*/services/enterprise/ @GareArc
+/api/tests/*/migrations/ @snakevash @laipz8200 @MRZHUH
 
 # Backend - RAG (Retrieval Augmented Generation)
 /api/core/rag/ @JohnJyong
@@ -109,8 +128,8 @@
 /api/tasks/async_workflow_tasks.py @Mairuis
 
 # Backend - Billing
-/api/services/billing_service.py @hj24 @zyssyz123
-/api/controllers/console/billing/ @hj24 @zyssyz123
+/api/services/billing_service.py @zyssyz123
+/api/controllers/console/billing/ @zyssyz123
 
 # Backend - Enterprise
 /api/configs/enterprise/ @GareArc
@@ -128,6 +147,12 @@
 # Frontend
 /web/ @iamjoel
 
+# Frontend - Tooling
+/lint.config.ts @hyoban @lyzno1
+/eslint.config.mjs @hyoban @lyzno1
+/knip.config.ts @hyoban @lyzno1
+/vite.config.ts @hyoban @lyzno1
+
 # Frontend - Platform and Features
 /web/config/ @lyzno1
 /web/env.ts @lyzno1

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 name: '🕷️ Bug report'
 description: Report errors or unexpected behavior
 labels:
-  - bug
+  - 🐞 bug
 body:
   - type: checkboxes
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,7 +1,7 @@
 name: '⭐ Feature or enhancement request'
 description: Propose something new.
 labels:
-  - enhancement
+  - 💪 enhancement
 body:
   - type: checkboxes
     attributes:

.github/actions/setup-core-e2e/action.yml

@@ -0,0 +1,29 @@
+name: Setup Core E2E Dependencies
+description: Install API dependencies alongside web dependencies and the selected browser
+
+inputs:
+  browser:
+    description: Browser to install (chromium or webkit)
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Setup web toolchain
+      uses: ./.github/actions/setup-web
+      with:
+        run-install: 'false'
+
+    - name: Setup UV and Python
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      with:
+        enable-cache: true
+        python-version: '3.12'
+        cache-dependency-glob: api/uv.lock
+
+    - name: Install dependencies in parallel
+      shell: bash
+      env:
+        E2E_INSTALL_BROWSER: ${{ inputs.browser }}
+        E2E_SETUP_ACTION_PATH: ${{ github.action_path }}
+      run: bash "$E2E_SETUP_ACTION_PATH/install.sh"

.github/actions/setup-core-e2e/install.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+case "${E2E_INSTALL_BROWSER:-}" in
+  chromium|webkit) ;;
+  *) echo "Expected chromium or webkit" >&2; exit 1 ;;
+esac
+
+# Keep both branches in this step so failures are collected before tests start.
+started=$SECONDS
+timing_dir=$(mktemp -d)
+trap 'rm -rf "$timing_dir"' EXIT
+
+(
+  api_started=$SECONDS
+  uv sync --project api --dev
+  echo "$((SECONDS - api_started))" > "$timing_dir/api"
+) &
+api_pid=$!
+
+(
+  web_started=$SECONDS
+  vp install --frozen-lockfile
+  echo "$((SECONDS - web_started))" > "$timing_dir/web"
+  browser_started=$SECONDS
+  cd e2e
+  vp run "e2e:install:ci:$E2E_INSTALL_BROWSER"
+  echo "$((SECONDS - browser_started))" > "$timing_dir/browser"
+) &
+web_pid=$!
+
+api_status=0
+web_status=0
+wait "$api_pid" || api_status=$?
+wait "$web_pid" || web_status=$?
+
+{
+  echo "### E2E dependency preparation ($E2E_INSTALL_BROWSER)"
+  echo ""
+  echo "Parallel install wall time: $((SECONDS - started))s"
+  echo ""
+  echo "| Phase | Seconds |"
+  echo "| --- | ---: |"
+  for phase in api web browser; do
+    if [[ -f "$timing_dir/$phase" ]]; then
+      echo "| $phase | $(cat "$timing_dir/$phase") |"
+    fi
+  done
+  echo ""
+  echo "API exit status: $api_status; Web/browser exit status: $web_status"
+} >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+
+if (( api_status != 0 || web_status != 0 )); then
+  echo "E2E dependency installation failed (API: $api_status, Web/browser: $web_status)" >&2
+  exit 1
+fi

.github/actions/setup-web/action.yml

@@ -1,16 +1,29 @@
 name: Setup Web Environment
 description: Set up Node.js, Vite+, pnpm, and web dependencies
 
+inputs:
+  run-install:
+    description: Install web dependencies after setting up the toolchain
+    default: 'true'
+  cache-save:
+    description: Save the dependency cache after the job completes
+    default: 'true'
+
 runs:
   using: composite
   steps:
-    - name: Setup pnpm
-      uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+    - name: Setup pnpm and Node.js
+      uses: pnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9b # v2.1.0
       with:
-        run_install: false
+        install: false
     - name: Setup Vite+
-      uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0
+      uses: voidzero-dev/setup-vp@9fd26ff49f9b5e6276c2b493da4454ad4527f7f4 # v1.20.0
       with:
-        node-version-file: package.json
+        node-manager: false
+        package-manager: |
+          pnpm: false
+          npm: false
         cache: true
-        run-install: true
+        # Nested composite post actions can evaluate inputs in the outer scope.
+        cache-save: ${{ inputs.cache-save || 'true' }}
+        run-install: ${{ inputs.run-install }}

.github/actions/wait-e2e-web-build/action.yml

@@ -0,0 +1,21 @@
+name: Wait for Core E2E Web Build
+description: Wait for the current workflow run's Web build artifact while the producer finishes independently
+
+outputs:
+  artifact-id:
+    description: ID of the ready Web build artifact
+    value: ${{ steps.wait.outputs.result }}
+
+runs:
+  using: composite
+  steps:
+    - name: Wait for build artifact
+      id: wait
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        E2E_WAIT_ACTION_PATH: ${{ github.action_path }}
+      with:
+        result-encoding: string
+        script: |
+          const waitForBuild = require(`${process.env.E2E_WAIT_ACTION_PATH}/wait.cjs`)
+          return await waitForBuild({ github, context, core, runAttempt: Number(process.env.GITHUB_RUN_ATTEMPT) })

.github/actions/wait-e2e-web-build/wait.cjs

@@ -0,0 +1,65 @@
+const { setTimeout: delay } = require('node:timers/promises')
+
+module.exports = async function waitForBuild({
+  github,
+  context,
+  core,
+  runAttempt,
+  now = Date.now,
+  sleep = delay,
+  timeoutMs = 30 * 60 * 1000,
+}) {
+  const started = now()
+  const run = { ...context.repo, run_id: context.runId, per_page: 100 }
+  core.info('Waiting for core-e2e-web-build in this workflow run')
+
+  while (now() - started < timeoutMs) {
+    const jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRunAttempt, {
+      ...run,
+      attempt_number: runAttempt,
+    })
+    const producer = jobs.find(
+      (job) =>
+        job.name === 'Prepare Core E2E Web Build' ||
+        job.name.endsWith(' / Prepare Core E2E Web Build'),
+    )
+    if (producer?.status === 'completed' && producer.conclusion !== 'success') {
+      throw new Error(
+        `Web build finished with ${producer.conclusion} before publishing an artifact`,
+      )
+    }
+
+    if (producer && ['in_progress', 'completed'].includes(producer.status)) {
+      const artifacts = await github.paginate(github.rest.actions.listWorkflowRunArtifacts, run)
+      const upload = producer.steps?.find((step) => step.name === 'Upload Web build')
+      const artifact = artifacts.find((item) => {
+        if (item.expired || !/^core-e2e-web-build-[1-9]\d*$/.test(item.name)) return false
+        if (producer.status === 'in_progress') {
+          // A rebuilding producer must publish this attempt's immutable artifact.
+          return item.name === `core-e2e-web-build-${runAttempt}`
+        }
+        // GitHub relabels reused successful jobs with the current run_attempt.
+        // Their upload step keeps its original timestamps, identifying the artifact
+        // to reuse when only consumers are rerun (including across several attempts).
+        return (
+          upload?.conclusion === 'success' &&
+          item.created_at >= upload.started_at &&
+          item.created_at <= upload.completed_at
+        )
+      })
+      if (artifact) {
+        const seconds = Math.round((now() - started) / 1000)
+        core.info(`Web build artifact ${artifact.name} ready after ${seconds}s`)
+        await core.summary
+          .addHeading('E2E Web build wait')
+          .addRaw(`Artifact wait: ${seconds}s`)
+          .write()
+        return String(artifact.id)
+      }
+    }
+
+    await sleep(Math.min(10000, timeoutMs - (now() - started)))
+  }
+
+  throw new Error('Timed out waiting for core-e2e-web-build in this workflow run')
+}

.github/actions/wait-e2e-web-build/wait.test.cjs

@@ -0,0 +1,164 @@
+const assert = require('node:assert/strict')
+const { test } = require('node:test')
+const waitForBuild = require('./wait.cjs')
+
+function fixture({ artifacts = [], jobs = [producer], error, runAttempt = 2 } = {}) {
+  let elapsed = 0
+  const calls = []
+  const summary = {
+    addHeading() {
+      return this
+    },
+    addRaw() {
+      return this
+    },
+    async write() {},
+  }
+  return {
+    calls,
+    options: {
+      context: { repo: { owner: 'owner', repo: 'repo' }, runId: 123 },
+      core: { info() {}, summary },
+      runAttempt,
+      github: {
+        rest: {
+          actions: { listWorkflowRunArtifacts: 'artifacts', listJobsForWorkflowRunAttempt: 'jobs' },
+        },
+        async paginate(endpoint, params) {
+          calls.push({ endpoint, params })
+          if (error) throw error
+          const values = endpoint === 'artifacts' ? artifacts : jobs
+          return typeof values === 'function' ? values(elapsed) : values
+        },
+      },
+      now: () => elapsed,
+      sleep: async (ms) => {
+        elapsed += ms
+      },
+      timeoutMs: 20000,
+    },
+  }
+}
+
+const producer = {
+  name: 'Run Web Full-Stack E2E / Prepare Core E2E Web Build',
+  status: 'in_progress',
+  run_attempt: 2,
+}
+const artifact = {
+  id: 42,
+  name: 'core-e2e-web-build-2',
+  expired: false,
+  created_at: '2026-09-22T04:08:11Z',
+}
+const oldArtifact = {
+  ...artifact,
+  id: 41,
+  name: 'core-e2e-web-build-1',
+  created_at: '2026-09-22T03:08:11Z',
+}
+const successfulProducer = {
+  ...producer,
+  status: 'completed',
+  conclusion: 'success',
+  steps: [
+    {
+      name: 'Upload Web build',
+      conclusion: 'success',
+      started_at: '2026-09-22T04:08:08Z',
+      completed_at: '2026-09-22T04:08:12Z',
+    },
+  ],
+}
+
+test('starts consuming the current artifact without waiting for producer cache saves', async () => {
+  const { options, calls } = fixture({ artifacts: (elapsed) => (elapsed ? [artifact] : []) })
+  assert.equal(await waitForBuild(options), '42')
+  assert.equal(options.now(), 10000)
+  assert.deepEqual(
+    calls.map((call) => call.endpoint),
+    ['jobs', 'artifacts', 'jobs', 'artifacts'],
+  )
+  for (const { endpoint, params } of calls) {
+    assert.equal(params.run_id, 123)
+    assert.equal(params.owner, 'owner')
+    assert.equal(params.repo, 'repo')
+    if (endpoint === 'jobs') assert.equal(params.attempt_number, 2)
+  }
+})
+
+test('full reruns ignore the old artifact until the rebuilding producer publishes this attempt', async () => {
+  const { options } = fixture({
+    artifacts: (elapsed) => (elapsed ? [oldArtifact, artifact] : [oldArtifact]),
+  })
+  assert.equal(await waitForBuild(options), '42')
+  assert.equal(options.now(), 10000)
+})
+
+test('does not use an old artifact before the current producer appears or while it is queued', async () => {
+  const { options } = fixture({
+    artifacts: [oldArtifact],
+    jobs: (elapsed) => (elapsed ? [{ ...producer, status: 'queued' }] : []),
+  })
+  await assert.rejects(waitForBuild(options), /Timed out/)
+})
+
+test('consumer-only reruns reuse the actual successful upload despite a relabeled run_attempt', async () => {
+  const { options } = fixture({
+    runAttempt: 4,
+    artifacts: [oldArtifact, artifact],
+    jobs: [{ ...successfulProducer, run_attempt: 4 }],
+  })
+  assert.equal(await waitForBuild(options), '42')
+  assert.equal(options.now(), 0)
+})
+
+for (const conclusion of ['failure', 'cancelled', 'skipped']) {
+  test(`does not fall back to an old artifact when the producer finishes with ${conclusion}`, async () => {
+    const { options } = fixture({
+      artifacts: [oldArtifact, artifact],
+      jobs: [{ ...producer, status: 'completed', conclusion }],
+    })
+    await assert.rejects(waitForBuild(options), new RegExp(`Web build finished with ${conclusion}`))
+    assert.equal(options.now(), 0)
+  })
+}
+
+test('ignores unrelated and expired artifacts and stops at the deadline', async () => {
+  const { options } = fixture({
+    artifacts: [
+      { ...artifact, expired: true },
+      { ...artifact, name: 'other' },
+    ],
+  })
+  await assert.rejects(waitForBuild(options), /Timed out/)
+  assert.equal(options.now(), 20000)
+})
+
+test('completed rebuilt producers select their upload instead of the old artifact', async () => {
+  const { options } = fixture({ artifacts: [oldArtifact, artifact], jobs: [successfulProducer] })
+  assert.equal(await waitForBuild(options), '42')
+})
+
+test('allows artifact visibility to catch up after a successful producer finishes', async () => {
+  const { options } = fixture({
+    artifacts: (elapsed) => (elapsed ? [oldArtifact, artifact] : [oldArtifact]),
+    jobs: [successfulProducer],
+  })
+  assert.equal(await waitForBuild(options), '42')
+  assert.equal(options.now(), 10000)
+})
+
+test('does not reuse artifacts without a successful matching upload step', async () => {
+  const { options } = fixture({
+    artifacts: [artifact],
+    jobs: [{ ...successfulProducer, steps: [] }],
+  })
+  await assert.rejects(waitForBuild(options), /Timed out/)
+})
+
+test('reports API errors rather than silently waiting until timeout', async () => {
+  const { options } = fixture({ error: new Error('Resource not accessible by integration') })
+  await assert.rejects(waitForBuild(options), /Resource not accessible/)
+  assert.equal(options.now(), 0)
+})

.github/pull_request_template.md

@@ -1,7 +1,7 @@
 > [!IMPORTANT]
 >
 > 1. Make sure you have read our [contribution guidelines](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md)
-> 1. Ensure there is an associated issue and you have been assigned to it
+> 1. Ensure there is an associated issue
 > 1. Use the correct syntax to link this PR: `Fixes #<issue number>`.
 
 ## Summary
@@ -19,6 +19,6 @@
 
 - [ ] This change requires a documentation update, included: [Dify Document](https://github.com/langgenius/dify-docs)
 - [ ] I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
-- [ ] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
+- [ ] I've verified the change and added or updated tests where meaningful regression risk justifies coverage.
 - [ ] I've updated the documentation accordingly.
 - [ ] I ran `make lint && make type-check` (backend) and `vp staged` (frontend) to appease the lint gods

.github/scripts/generate-i18n-changes.mjs

@@ -8,7 +8,8 @@ const headSha = process.env.HEAD_SHA || ''
 const files = (process.env.CHANGED_FILES || '').split(/\s+/).filter(Boolean)
 const outputPath = process.env.I18N_CHANGES_OUTPUT_PATH || '/tmp/i18n-changes.json'
 
-const englishPath = (fileStem) => path.join(repoRoot, 'web', 'i18n', 'en-US', `${fileStem}.json`)
+const englishPath = (fileStem) =>
+  path.join(repoRoot, 'web', 'i18n', 'locales', 'en-US', `${fileStem}.json`)
 
 const readCurrentJson = (fileStem) => {
   const filePath = englishPath(fileStem)
@@ -21,7 +22,7 @@ const readBaseJson = (fileStem) => {
   if (!baseSha) return null
 
   try {
-    const relativePath = `web/i18n/en-US/${fileStem}.json`
+    const relativePath = `web/i18n/locales/en-US/${fileStem}.json`
     const content = execFileSync('git', ['show', `${baseSha}:${relativePath}`], {
       encoding: 'utf8',
     })

.github/scripts/size-labeler.test.cjs

@@ -0,0 +1,94 @@
+const fs = require('node:fs')
+const assert = require('node:assert/strict')
+const test = require('node:test')
+const source = fs.readFileSync(
+  require('node:path').join(__dirname, '../workflows/size-labeler.yml'),
+  'utf8',
+)
+const script = source
+  .replace(/\r\n/g, '\n')
+  .split('          script: |\n')[1]
+  .split('\n')
+  .map((l) => l.replace(/^            /, ''))
+  .join('\n')
+const run = new (Object.getPrototypeOf(async function () {}).constructor)(
+  'github',
+  'context',
+  'core',
+  script,
+)
+async function scenario(files, existing = [], changed = files.length) {
+  const calls = []
+  const warnings = []
+  const api = {
+    pulls: {
+      get: async () => ({ data: { changed_files: changed } }),
+      listFiles: 'files',
+    },
+    issues: {
+      listLabelsOnIssue: 'labels',
+      addLabels: async (p) => calls.push(['add', p.labels[0]]),
+      removeLabel: async (p) => calls.push(['remove', p.name]),
+    },
+  }
+  await run(
+    {
+      rest: api,
+      paginate: async (endpoint) =>
+        endpoint === 'files' ? files : existing.map((name) => ({ name })),
+    },
+    {
+      repo: { owner: 'test', repo: 'repo' },
+      payload: { pull_request: { number: 1 } },
+    },
+    { warning: (s) => warnings.push(s) },
+  )
+  return { calls, warnings }
+}
+for (const [n, label] of [
+  [0, 'XS'],
+  [9, 'XS'],
+  [10, 'S'],
+  [29, 'S'],
+  [30, 'M'],
+  [99, 'M'],
+  [100, 'L'],
+  [499, 'L'],
+  [500, 'XL'],
+  [999, 'XL'],
+  [1000, 'XXL'],
+]) {
+  test(`threshold ${n}`, async () =>
+    assert.deepEqual((await scenario([{ filename: 'a.py', additions: n, deletions: 0 }])).calls, [
+      ['add', `size:${label}`],
+    ]))
+}
+test('count deletions', async () =>
+  assert.deepEqual((await scenario([{ filename: 'a.py', additions: 0, deletions: 30 }])).calls, [
+    ['add', 'size:M'],
+  ]))
+test('ignore nested lockfiles', async () =>
+  assert.deepEqual(
+    (
+      await scenario([
+        { filename: 'api/uv.lock', additions: 9000, deletions: 5 },
+        { filename: 'web/pnpm-lock.yaml', additions: 5000, deletions: 0 },
+      ])
+    ).calls,
+    [['add', 'size:XS']],
+  ))
+test('replace stale size only', async () =>
+  assert.deepEqual(
+    (await scenario([{ filename: 'a.py', additions: 10, deletions: 0 }], ['size:L', 'bug', 'web']))
+      .calls,
+    [
+      ['add', 'size:S'],
+      ['remove', 'size:L'],
+    ],
+  ))
+test('idempotent', async () => assert.deepEqual((await scenario([], ['size:XS', 'bug'])).calls, []))
+test('incomplete file list', async () => {
+  const r = await scenario([], ['size:L'], 3001)
+  assert.deepEqual(r.calls, [])
+  assert.equal(r.warnings.length, 1)
+})

.github/workflows/accessibility-e2e.yml

@@ -52,7 +52,7 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: '3.12'

.github/workflows/api-tests.yml

@@ -14,28 +14,79 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  api-unit-plan:
+    name: Plan API unit shards
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: '3.12'
+          enable-cache: false
+      - name: Download shared timing baseline
+        # Public statistics are independent of PR refs and require no credentials.
+        run: |
+          if ! curl --fail --silent --show-error --location \
+            --connect-timeout 5 --max-time 15 --retry 2 --retry-max-time 30 \
+            https://raw.githubusercontent.com/langgenius/dify-test-infra/generated-stats/stats/test-times.json \
+            --output unit-test-durations.json; then
+            rm -f unit-test-durations.json
+            echo '::warning::Timing baseline unavailable; using round-robin file allocation.'
+          fi
+      - name: Freeze file assignments for every shard
+        run: |
+          uv run --project api --no-sync python api/dev/pytest_sharding.py \
+            --shard-index 1 --shard-total 2 \
+            --durations unit-test-durations.json \
+            --write-plan unit-test-plan.json \
+            --split-threshold 60 \
+            --ignore api/tests/unit_tests/controllers \
+            api/tests/unit_tests \
+            api/providers/vdb/*/tests/unit_tests \
+            api/providers/trace/*/tests/unit_tests
+      - name: Upload shared plan
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-unit-plan
+          path: |
+            unit-test-plan.json
+            unit-test-durations.json
+          retention-days: 7
+          if-no-files-found: error
+
   api-unit:
-    name: API Unit Tests
+    needs: api-unit-plan
+    name: API Unit Tests (${{ matrix.python-version }}, shard ${{ matrix.shardIndex }}/${{ matrix.shardTotal }})
     runs-on: depot-ubuntu-24.04
     env:
-      COVERAGE_FILE: coverage-unit
+      PYTHONUNBUFFERED: '1'
+      COVERAGE_FILE: coverage-unit-${{ matrix.python-version }}-${{ matrix.shardIndex }}
     defaults:
       run:
         shell: bash
     strategy:
+      fail-fast: false
       matrix:
         python-version:
           - '3.12'
+        shardIndex:
+          - 1
+          - 2
+        shardTotal:
+          - 2
 
     steps:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -47,34 +98,116 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
+      - name: Download shared plan
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: api-unit-plan
+
       - name: Run Unit Tests
         run: |
+          uv run --project api python api/dev/pytest_sharding.py \
+            --plan unit-test-plan.json \
+            --shard-index "${{ matrix.shardIndex }}" \
+            --shard-total "${{ matrix.shardTotal }}" \
+            --ignore api/tests/unit_tests/controllers \
+            api/tests/unit_tests \
+            api/providers/vdb/*/tests/unit_tests \
+            api/providers/trace/*/tests/unit_tests > "$RUNNER_TEMP/unit-test-files.txt"
           uv run --project api pytest \
             -p no:benchmark \
             --timeout "${PYTEST_TIMEOUT:-20}" \
             -n auto \
-            api/tests/unit_tests \
-            api/providers/vdb/*/tests/unit_tests \
-            api/providers/trace/*/tests/unit_tests \
-            --ignore=api/tests/unit_tests/controllers
-          # Controller tests register Flask routes at import time, so keep them out of xdist.
-          uv run --project api pytest \
-            --timeout "${PYTEST_TIMEOUT:-20}" \
-            --cov-append \
-            api/tests/unit_tests/controllers
+            -o 'addopts=--cov=./api --cov-branch --import-mode=importlib' \
+            --cov-report= \
+            --file-shard-plan unit-test-plan.json \
+            --shard-index "${{ matrix.shardIndex }}" \
+            --shard-total "${{ matrix.shardTotal }}" \
+            --write-test-durations "test-results/durations-${{ matrix.shardIndex }}.json" \
+            --junitxml=test-results/unit.xml \
+            "@$RUNNER_TEMP/unit-test-files.txt"
+
+      - name: Upload unit test reports
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-test-results-unit-${{ matrix.python-version }}-${{ matrix.shardIndex }}
+          path: test-results/*.xml
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Upload successful timing observations
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-unit-durations-${{ matrix.shardIndex }}
+          path: test-results/durations-*.json
+          retention-days: 7
+          if-no-files-found: error
 
       - name: Upload unit coverage data
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: api-coverage-unit
-          path: coverage-unit
+          name: api-coverage-unit-${{ matrix.python-version }}-${{ matrix.shardIndex }}
+          path: ${{ env.COVERAGE_FILE }}
+          if-no-files-found: error
+          retention-days: 1
+
+  api-controllers:
+    name: API Controller Tests (3.12)
+    runs-on: depot-ubuntu-24.04
+    env:
+      PYTHONUNBUFFERED: '1'
+      COVERAGE_FILE: coverage-controllers-3.12
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          python-version: '3.12'
+          cache-dependency-glob: api/uv.lock
+
+      - name: Check UV lockfile
+        run: uv lock --project api --check
+
+      - name: Install dependencies
+        run: uv sync --project api --dev
+
+      - name: Run Controller Tests
+        # Controller tests register Flask routes at import time, so keep them out of xdist.
+        run: |
+          uv run --project api pytest \
+            --timeout "${PYTEST_TIMEOUT:-20}" \
+            -o 'addopts=--cov=./api --cov-branch --import-mode=importlib' \
+            --cov-report= \
+            --junitxml=test-results/controllers.xml \
+            api/tests/unit_tests/controllers
+
+      - name: Upload controller test reports
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-test-results-controllers-3.12
+          path: test-results/*.xml
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Upload controller coverage data
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-coverage-controllers-3.12
+          path: ${{ env.COVERAGE_FILE }}
+          if-no-files-found: error
           retention-days: 1
 
   api-integration:
-    name: API Integration Tests
-    runs-on: depot-ubuntu-24.04
+    name: API Integration Tests (${{ matrix.python-version }})
+    runs-on: depot-ubuntu-24.04-4
     env:
-      COVERAGE_FILE: coverage-integration
+      COVERAGE_FILE: coverage-integration-${{ matrix.python-version }}
       STORAGE_TYPE: opendal
       OPENDAL_SCHEME: fs
       OPENDAL_FS_ROOT: /tmp/dify-storage
@@ -82,6 +215,7 @@ jobs:
       run:
         shell: bash
     strategy:
+      fail-fast: false
       matrix:
         python-version:
           - '3.12'
@@ -90,11 +224,10 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -111,7 +244,10 @@ jobs:
           uv run --project api pytest \
             -p no:benchmark \
             --start-middleware \
+            --middleware-stop-timeout 2 \
             -n auto \
+            -o 'addopts=--cov=./api --cov-branch --import-mode=importlib' \
+            --cov-report= \
             --timeout "${PYTEST_TIMEOUT:-180}" \
             api/tests/integration_tests/workflow \
             api/tests/integration_tests/tools \
@@ -120,8 +256,9 @@ jobs:
       - name: Upload integration coverage data
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: api-coverage-integration
-          path: coverage-integration
+          name: api-coverage-integration-${{ matrix.python-version }}
+          path: ${{ env.COVERAGE_FILE }}
+          if-no-files-found: error
           retention-days: 1
 
   api-coverage:
@@ -129,6 +266,7 @@ jobs:
     runs-on: depot-ubuntu-24.04
     needs:
       - api-unit
+      - api-controllers
       - api-integration
     env:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
@@ -141,18 +279,12 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
-          enable-cache: true
           python-version: '3.12'
-          cache-dependency-glob: api/uv.lock
-
-      - name: Install dependencies
-        run: uv sync --project api --dev
 
       - name: Download coverage data
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -164,20 +296,34 @@ jobs:
       - name: Combine coverage
         run: |
           set -euo pipefail
+          coverage_version=$(python3 -c 'import tomllib; print(next(p["version"] for p in tomllib.load(open("api/uv.lock", "rb"))["package"] if p["name"] == "coverage"))')
 
-          echo "### API Coverage" >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "Merged backend coverage report generated for Codecov project status." >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
+          {
+            echo "### API Coverage"
+            echo ""
+            echo "Merged backend coverage report generated for Codecov project status."
+            echo ""
+          } >> "$GITHUB_STEP_SUMMARY"
 
-          unit_coverage="$(find coverage-data -type f -name coverage-unit -print -quit)"
-          integration_coverage="$(find coverage-data -type f -name coverage-integration -print -quit)"
-          : "${unit_coverage:?coverage-unit artifact not found}"
-          : "${integration_coverage:?coverage-integration artifact not found}"
+          mapfile -t unit_coverage < <(find coverage-data -type f -name 'coverage-unit-*' -print | sort)
+          mapfile -t controller_coverage < <(find coverage-data -type f -name 'coverage-controllers-*' -print | sort)
+          mapfile -t integration_coverage < <(find coverage-data -type f -name 'coverage-integration-*' -print | sort)
+          if [[ "${#unit_coverage[@]}" -ne 2 ]]; then
+            echo "expected 2 unit coverage artifacts, found ${#unit_coverage[@]}" >&2
+            exit 1
+          fi
+          if [[ "${#controller_coverage[@]}" -ne 1 ]]; then
+            echo "expected 1 controller coverage artifact, found ${#controller_coverage[@]}" >&2
+            exit 1
+          fi
+          if [[ "${#integration_coverage[@]}" -ne 1 ]]; then
+            echo "expected 1 integration coverage artifact, found ${#integration_coverage[@]}" >&2
+            exit 1
+          fi
 
           report_file="$(mktemp)"
-          uv run --project api coverage combine "$unit_coverage" "$integration_coverage"
-          uv run --project api coverage report --show-missing | tee "$report_file"
+          uvx --from "coverage==$coverage_version" coverage combine "${unit_coverage[@]}" "${controller_coverage[@]}" "${integration_coverage[@]}"
+          uvx --from "coverage==$coverage_version" coverage report --show-missing | tee "$report_file"
           echo "Summary: \`$(tail -n 1 "$report_file")\`" >> "$GITHUB_STEP_SUMMARY"
           {
             echo ""
@@ -188,11 +334,10 @@ jobs:
             echo '```'
             echo "</details>"
           } >> "$GITHUB_STEP_SUMMARY"
-          uv run --project api coverage xml -o coverage.xml
+          uvx --from "coverage==$coverage_version" coverage xml -o coverage.xml
 
       - name: Report coverage
-        if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           files: ./coverage.xml
           disable_search: true

.github/workflows/autofix.yml

@@ -64,7 +64,7 @@ jobs:
           python-version: '3.11'
 
       - if: github.event_name != 'merge_group' && (steps.api-changes.outputs.any_changed == 'true' || steps.frontend-contract-changes.outputs.any_changed == 'true' || steps.dify-agent-changes.outputs.any_changed == 'true')
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 
       - name: Generate Docker Compose
         if: github.event_name != 'merge_group' && steps.docker-compose-changes.outputs.any_changed == 'true'

.github/workflows/build-push.yml

@@ -160,10 +160,10 @@ jobs:
             file: 'docker/Dockerfile'
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Validate Docker image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           push: false
           context: ${{ matrix.build_context }}
@@ -245,8 +245,14 @@ jobs:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
+      - name: Use Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: package.json
+          cache: ''
+
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Login to Docker Hub
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0

.github/workflows/cli-e2e.yml

@@ -87,10 +87,9 @@ jobs:
         with:
           bun-version: latest
 
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+      - uses: pnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9b # v2.1.0
         with:
-          package_json_field: packageManager
-          run_install: false
+          install: false
 
       - name: Install CLI dependencies
         working-directory: cli
@@ -131,11 +130,6 @@ jobs:
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
-        with:
-          package_json_field: packageManager
-          run_install: false
-      - run: pnpm install --frozen-lockfile
       - run: pnpm tree:gen
 
       - name: Run framework + output + error-handling
@@ -181,11 +175,6 @@ jobs:
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
-        with:
-          package_json_field: packageManager
-          run_install: false
-      - run: pnpm install --frozen-lockfile
       - run: pnpm tree:gen
 
       - name: Run discovery suite
@@ -247,11 +236,6 @@ jobs:
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
-        with:
-          package_json_field: packageManager
-          run_install: false
-      - run: pnpm install --frozen-lockfile
       - run: pnpm tree:gen
 
       - name: 'Run run/${{ matrix.name }}'
@@ -312,11 +296,6 @@ jobs:
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
-        with:
-          package_json_field: packageManager
-          run_install: false
-      - run: pnpm install --frozen-lockfile
       - run: pnpm tree:gen
 
       - name: Run auth/login + status + whoami
@@ -371,11 +350,6 @@ jobs:
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
-        with:
-          package_json_field: packageManager
-          run_install: false
-      - run: pnpm install --frozen-lockfile
       - run: pnpm tree:gen
 
       - name: Run use / devices / logout / agent (serial)

.github/workflows/cli-tests.yml

@@ -51,7 +51,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' && matrix.os == 'depot-ubuntu-24.04' }}
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           directory: cli/coverage
           flags: cli

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

@@ -19,7 +19,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: '3.12'
@@ -40,7 +40,7 @@ jobs:
           cp envs/middleware.env.example middleware.env
 
       - name: Set up Middlewares
-        uses: hoverkraft-tech/compose-action@ee6af68587292d72db67743171809c19787df4c9 # v3.1.0
+        uses: hoverkraft-tech/compose-action@b659c744ee9bed25aea2307c017ad849bd104433 # v3.2.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml
@@ -69,7 +69,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: '3.12'
@@ -94,7 +94,7 @@ jobs:
           sed -i 's/DB_USERNAME=postgres/DB_USERNAME=mysql/' middleware.env
 
       - name: Set up Middlewares
-        uses: hoverkraft-tech/compose-action@ee6af68587292d72db67743171809c19787df4c9 # v3.1.0
+        uses: hoverkraft-tech/compose-action@b659c744ee9bed25aea2307c017ad849bd104433 # v3.2.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml

.github/workflows/deploy-knowledge.yml

@@ -67,5 +67,7 @@ jobs:
           host: ${{ secrets.SSH_NEW_RAG_HOST }}
           username: ${{ secrets.SSH_USER }}
           key: ${{ secrets.SSH_PRIVATE_KEY }}
+          # Allow the shared deployment lock and Celery warm shutdown to finish.
+          command_timeout: 300m
           script: |
             ${{ vars.SSH_SCRIPT || secrets.SSH_SCRIPT }}

.github/workflows/dify-agent-tests.yml

@@ -31,7 +31,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/docker-build.yml

@@ -96,10 +96,10 @@ jobs:
             file: 'docker/Dockerfile'
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Build Docker Image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           push: false
           context: ${{ matrix.context }}

.github/workflows/image-resources.yml

@@ -0,0 +1,39 @@
+name: Image optimization
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  image-resources:
+    name: Image optimization
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up workspace toolchain
+        uses: ./.github/actions/setup-web
+        with:
+          run-install: 'false'
+
+      - name: Install image checker dependencies
+        run: pnpm --filter @dify/image-resources... install --frozen-lockfile --ignore-scripts
+
+      - name: Type-check image checker
+        run: pnpm --filter @dify/image-resources type-check
+
+      - name: Test image checker
+        run: pnpm --filter @dify/image-resources test
+
+      - name: Check image optimization
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          pnpm --filter @dify/image-resources check:images --base "$BASE_SHA"

.github/workflows/main-ci.yml

@@ -37,8 +37,6 @@ jobs:
   # Check which paths were changed to determine which tests to run
   check-changes:
     name: Check Changed Files
-    needs: pre_job
-    if: needs.pre_job.outputs.should_skip != 'true'
     runs-on: depot-ubuntu-24.04
     outputs:
       api-changed: ${{ steps.changes.outputs.api }}
@@ -49,6 +47,11 @@ jobs:
       migration-changed: ${{ steps.changes.outputs.migration }}
       sandbox-runtime-changed: ${{ steps.changes.outputs.sandbox-runtime }}
       dify-agent-changed: ${{ steps.changes.outputs.dify-agent }}
+      python-style-changed: ${{ steps.changes.outputs.python-style }}
+      dify-agent-style-changed: ${{ steps.changes.outputs.dify-agent-style }}
+      web-style-changed: ${{ steps.changes.outputs.web-style }}
+      ts-common-style-changed: ${{ steps.changes.outputs.ts-common-style }}
+      superlinter-changed: ${{ steps.changes.outputs.superlinter }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
@@ -95,8 +98,6 @@ jobs:
               - '.github/actions/setup-web/**'
             e2e:
               - 'api/**'
-              - 'api/pyproject.toml'
-              - 'api/uv.lock'
               - 'e2e/**'
               - 'web/**'
               - 'packages/**'
@@ -105,9 +106,13 @@ jobs:
               - 'pnpm-workspace.yaml'
               - 'docker/docker-compose.middleware.yaml'
               - 'docker/envs/middleware.env.example'
+              - 'docker/ssrf_proxy/**'
+              - 'docker/volumes/sandbox/conf/**'
               - '.github/workflows/web-e2e.yml'
               - '.github/workflows/main-ci.yml'
               - '.github/actions/setup-web/**'
+              - '.github/actions/setup-core-e2e/**'
+              - '.github/actions/wait-e2e-web-build/**'
             vdb:
               - 'api/core/rag/datasource/**'
               - 'api/tests/integration_tests/vdb/**'
@@ -150,6 +155,58 @@ jobs:
               - 'docker/generate_docker_compose'
               - 'docker/ssrf_proxy/**'
               - 'docker/volumes/sandbox/conf/**'
+            python-style:
+              - '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'
+            dify-agent-style:
+              - 'dify-agent/**'
+              - '.github/workflows/style.yml'
+              - '.github/workflows/main-ci.yml'
+            web-style:
+              - 'web/**'
+              - 'e2e/**'
+              - 'sdks/nodejs-client/**'
+              - 'packages/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'knip.config.ts'
+              - 'scripts/check-web-production-unused-after-knip-fix.mjs'
+              - '.github/workflows/style.yml'
+              - '.github/actions/setup-web/**'
+            ts-common-style:
+              - 'web/**'
+              - 'cli/**'
+              - 'e2e/**'
+              - 'sdks/nodejs-client/**'
+              - 'packages/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'vite.config.ts'
+              - 'lint.config.ts'
+              - 'eslint.config.mjs'
+              - 'knip.config.ts'
+              - 'scripts/check-web-production-unused-after-knip-fix.mjs'
+              - 'oxlint-suppressions.json'
+              - 'eslint-suppressions.json'
+              - '.vscode/**'
+              - '.github/**'
+            superlinter:
+              - '**.sh'
+              - '**.yaml'
+              - '**.yml'
+              - '**Dockerfile'
+              - 'dev/**'
+              - '.editorconfig'
+              - '.vite-hooks/**'
 
   # Run tests in parallel while always emitting stable required checks.
   api-tests-run:
@@ -396,10 +453,19 @@ jobs:
 
   style-check:
     name: Style Check
-    needs: pre_job
+    if: ${{ always() }}
+    needs:
+      - pre_job
+      - check-changes
     uses: ./.github/workflows/style.yml
     with:
       base-rev: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha }}
+      classification-succeeded: ${{ needs.check-changes.result == 'success' }}
+      run-python-style: ${{ needs.check-changes.outputs.python-style-changed == 'true' }}
+      run-dify-agent-style: ${{ needs.check-changes.outputs.dify-agent-style-changed == 'true' }}
+      run-web-style: ${{ needs.check-changes.outputs.web-style-changed == 'true' }}
+      run-ts-common-style: ${{ needs.check-changes.outputs.ts-common-style-changed == 'true' }}
+      run-superlinter: ${{ needs.check-changes.outputs.superlinter-changed == 'true' }}
       skip-checks: ${{ needs.pre_job.outputs.should_skip == 'true' }}
 
   vdb-tests-run:

.github/workflows/post-merge.yml

@@ -44,6 +44,8 @@ jobs:
               - '.github/actions/setup-web/**'
               - 'docker/docker-compose.middleware.yaml'
               - 'docker/envs/middleware.env.example'
+              - 'docker/ssrf_proxy/**'
+              - 'docker/volumes/sandbox/conf/**'
               - 'dify-agent/**'
               - 'dify-agent-runtime/**'
               - 'api/pyproject.toml'
@@ -53,12 +55,30 @@ jobs:
               - 'api/core/app/apps/agent_app/**'
               - 'api/core/workflow/nodes/agent_v2/**'
               - 'api/controllers/console/agent/**'
+              - 'api/controllers/console/app/agent*.py'
+              - 'api/controllers/console/app/audio.py'
+              - 'api/controllers/common/agent_access.py'
+              - 'api/controllers/inner_api/agent/**'
+              - 'api/controllers/inner_api/wraps.py'
+              - 'api/controllers/service_api/app/completion.py'
+              - 'api/controllers/service_api/wraps.py'
+              - 'api/controllers/web/completion.py'
+              - 'api/controllers/web/wraps.py'
+              - 'api/services/agent_llm_inner_service.py'
+              - 'api/services/agent_tool_inner_service.py'
+              - 'api/services/audio_service.py'
+              - 'api/services/entities/agent_llm_inner.py'
+              - 'api/services/entities/agent_tool_inner.py'
+              - 'api/services/errors/agent_tool_inner.py'
               - 'api/services/agent/**'
               - 'api/core/plugin/**'
               - 'api/services/plugin/**'
               - 'api/core/tools/**'
               - 'api/services/tools/**'
               - 'packages/contracts/package.json'
+              - 'packages/contracts/console.ts'
+              - 'packages/contracts/generated/api/console/router.gen.ts'
+              - 'packages/contracts/generated/api/web/**'
               - 'packages/contracts/generated/api/console/agent/**'
               - 'packages/contracts/generated/api/console/apps/**'
               - 'packages/contracts/generated/api/console/datasets/**'
@@ -66,20 +86,27 @@ jobs:
               - 'packages/contracts/generated/api/console/workspaces/**'
               - 'packages/contracts/generated/api/service/**'
               - 'web/features/agent-v2/**'
-              - 'web/app/(commonLayout)/agents/**'
-              - 'web/app/(commonLayout)/@detailSidebar/agents/**'
-              - 'web/app/(commonLayout)/roster/**'
+              - 'web/app/\(commonLayout\)/agents/**'
+              - 'web/app/\(commonLayout\)/@detailSidebar/agents/**'
+              - 'web/app/\(shareLayout\)/chat/**'
+              - 'web/app/\(shareLayout\)/components/**'
+              - 'web/app/components/base/chat/chat-with-history/**'
               - 'web/app/components/base/chat/chat/**'
               - 'web/app/components/base/voice-input/**'
+              - 'web/app/components/workflow/index.tsx'
+              - 'web/app/components/workflow/block-selector/**'
+              - 'web/app/components/workflow/hooks/use-node-keyboard-interactions.ts'
+              - 'web/app/components/workflow/hooks/use-nodes-interactions.ts'
+              - 'web/app/components/workflow/hooks/use-nodes-sync-draft.ts'
+              - 'web/app/components/workflow/nodes/_base/**'
               - 'web/app/components/workflow/nodes/agent-v2/**'
-              - 'web/i18n/en-US/agent-v-2.json'
-              - 'web/i18n/en-US/common.json'
+              - 'web/i18n/locales/en-US/agent-v-2.json'
+              - 'web/i18n/locales/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/console/**'
               - 'web/service/share.ts'
+              - 'web/service/use-share.ts'
+              - 'web/service/webapp-address.ts'
               - 'web/package.json'
               - 'pnpm-workspace.yaml'
 
@@ -87,6 +114,9 @@ jobs:
     name: External Runtime E2E
     needs: check-changes
     if: needs.check-changes.outputs.external-e2e-changed == 'true'
+    permissions:
+      actions: read
+      contents: read
     uses: ./.github/workflows/web-e2e.yml
     with:
       run-external-runtime: true

.github/workflows/pyrefly-diff.yml

@@ -22,7 +22,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
 

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

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
 

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

@@ -22,7 +22,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
 

.github/workflows/size-labeler.yml

@@ -0,0 +1,55 @@
+name: Pull Request Size Labeler
+
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize, ready_for_review, edited]
+
+permissions:
+  pull-requests: write
+
+concurrency:
+  group: size-labeler-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  label:
+    runs-on: depot-ubuntu-24.04
+    steps:
+      # Only read PR metadata. Never check out or execute the PR's code here.
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo
+            const issue_number = context.payload.pull_request.number
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: issue_number })
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner, repo, pull_number: issue_number, per_page: 100,
+            })
+            // GitHub caps this endpoint at 3,000 files; avoid labeling a partial count.
+            if (files.length !== pr.changed_files) {
+              core.warning('Skipping size label because the changed-file list is incomplete')
+              return
+            }
+            const ignoredNames = new Set(['uv.lock', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'])
+            const changes = files
+              .filter(file => !ignoredNames.has(file.filename.split('/').pop()))
+              .reduce((total, file) => total + file.additions + file.deletions, 0)
+            // Match the descriptions of the repository's existing size labels.
+            const buckets = [
+              [10, 'size:XS'], [30, 'size:S'], [100, 'size:M'],
+              [500, 'size:L'], [1000, 'size:XL'], [Infinity, 'size:XXL'],
+            ]
+            const label = buckets.find(([limit]) => changes < limit)[1]
+            const sizeLabels = new Set(buckets.map(([, name]) => name))
+            const labels = await github.paginate(github.rest.issues.listLabelsOnIssue, {
+              owner, repo, issue_number, per_page: 100,
+            })
+            // Add first so an API error cannot leave the PR without a size label.
+            if (!labels.some(item => item.name === label)) {
+              await github.rest.issues.addLabels({ owner, repo, issue_number, labels: [label] })
+            }
+            for (const item of labels) {
+              if (sizeLabels.has(item.name) && item.name !== label) {
+                await github.rest.issues.removeLabel({ owner, repo, issue_number, name: item.name })
+              }
+            }

.github/workflows/style.yml

@@ -6,6 +6,30 @@ on:
       base-rev:
         required: true
         type: string
+      classification-succeeded:
+        description: Whether the caller successfully classified the changed files.
+        required: true
+        type: boolean
+      run-python-style:
+        description: Run Python style checks for the changed files.
+        required: true
+        type: boolean
+      run-dify-agent-style:
+        description: Run Dify Agent style checks for the changed files.
+        required: true
+        type: boolean
+      run-web-style:
+        description: Run Web style checks for the changed files.
+        required: true
+        type: boolean
+      run-ts-common-style:
+        description: Run shared TypeScript style checks for the changed files.
+        required: true
+        type: boolean
+      run-superlinter:
+        description: Run SuperLinter for the changed files.
+        required: true
+        type: boolean
       skip-checks:
         description: Create the required check runs without repeating previously successful work.
         required: false
@@ -20,72 +44,72 @@ permissions:
 jobs:
   python-style:
     name: Python Style
-    if: ${{ !inputs.skip-checks }}
+    if: ${{ !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-python-style || inputs.run-dify-agent-style) }}
     runs-on: depot-ubuntu-24.04
 
     steps:
+      - name: Verify changed-file classification
+        if: ${{ !inputs.classification-succeeded }}
+        run: |
+          echo "Changed-file classification failed; refusing to skip Python style checks." >&2
+          exit 1
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
 
-      - name: Check changed files
-        id: changed-files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        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@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: false
           python-version: '3.12'
-          cache-dependency-glob: api/uv.lock
+          cache-dependency-glob: |
+            api/uv.lock
+            dify-agent/uv.lock
 
       - name: Install dependencies
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         run: uv sync --project api --dev
 
       - name: Run Import Linter
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         run: uv run --directory api --dev lint-imports
 
       - name: Run Response Contract Linter
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         run: uv run --project api --dev python api/dev/lint_response_contracts.py --fail-on-mismatch
 
       - name: Run No New Getattr Guard
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         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'
+        if: inputs.run-python-style
         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'
+        if: inputs.run-python-style
         env:
           PYREFLY_OUTPUT_FORMAT: github
         run: make type-check-core
 
+      - name: Run Dify Agent Ruff
+        if: inputs.run-dify-agent-style
+        run: make -C dify-agent check
+
+      - name: Run Dify Agent Type Checks
+        if: inputs.run-dify-agent-style
+        run: make -C dify-agent typecheck
+
       - name: Dotenv check
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         run: uv run --project api dotenv-linter ./api/.env.example ./web/.env.example
 
   web-style:
     name: Web Style
-    if: ${{ !inputs.skip-checks }}
+    if: ${{ !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-web-style) }}
     runs-on: depot-ubuntu-24.04
     defaults:
       run:
@@ -95,126 +119,89 @@ jobs:
       pull-requests: read
 
     steps:
+      - name: Verify changed-file classification
+        if: ${{ !inputs.classification-succeeded }}
+        working-directory: .
+        run: |
+          echo "Changed-file classification failed; refusing to skip Web style checks." >&2
+          exit 1
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - name: Check changed files
-        id: changed-files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            web/**
-            e2e/**
-            sdks/nodejs-client/**
-            packages/**
-            package.json
-            pnpm-lock.yaml
-            pnpm-workspace.yaml
-            knip.config.ts
-            scripts/check-web-production-unused-after-knip-fix.mjs
-            .github/workflows/style.yml
-            .github/actions/setup-web/**
-
       - name: Setup web environment
-        if: steps.changed-files.outputs.any_changed == 'true'
         uses: ./.github/actions/setup-web
 
       - name: Web tsslint
-        if: steps.changed-files.outputs.any_changed == 'true'
         env:
           NODE_OPTIONS: --max-old-space-size=4096
         run: vp run lint:tss
 
       - name: Web dead code check
-        if: steps.changed-files.outputs.any_changed == 'true'
         working-directory: .
         run: vp run knip
 
+      - name: Web build and unused translations check
+        env:
+          NODE_OPTIONS: --max-old-space-size=8192
+        run: vp run build:vinext
+
       - name: Web dead code check production
-        if: steps.changed-files.outputs.any_changed == 'true'
         working-directory: .
         run: vp run knip:production
 
       - name: Web production unused declarations check
-        if: steps.changed-files.outputs.any_changed == 'true'
         working-directory: .
         run: vp run knip:production-unused-check
 
   ts-common-style:
     name: TS Common
-    if: ${{ !inputs.skip-checks }}
+    if: ${{ !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-ts-common-style) }}
     runs-on: depot-ubuntu-24.04-4
     permissions:
       checks: write
       pull-requests: read
 
     steps:
+      - name: Verify changed-file classification
+        if: ${{ !inputs.classification-succeeded }}
+        run: |
+          echo "Changed-file classification failed; refusing to skip TypeScript style checks." >&2
+          exit 1
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - name: Check changed files
-        id: changed-files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            web/**
-            cli/**
-            e2e/**
-            sdks/nodejs-client/**
-            packages/**
-            package.json
-            pnpm-lock.yaml
-            pnpm-workspace.yaml
-            vite.config.ts
-            lint.config.ts
-            eslint.config.mjs
-            knip.config.ts
-            scripts/check-web-production-unused-after-knip-fix.mjs
-            oxlint-suppressions.json
-            eslint-suppressions.json
-            .vscode/**
-            .github/**
-
       - name: Setup web environment
-        if: steps.changed-files.outputs.any_changed == 'true'
         uses: ./.github/actions/setup-web
 
       - name: Static check
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: pnpm -w check
+        run: vp run -w check
 
   superlinter:
     name: SuperLinter
-    if: ${{ !inputs.skip-checks }}
+    if: ${{ !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-superlinter) }}
     runs-on: depot-ubuntu-24.04
 
     steps:
+      - name: Verify changed-file classification
+        if: ${{ !inputs.classification-succeeded }}
+        run: |
+          echo "Changed-file classification failed; refusing to skip SuperLinter." >&2
+          exit 1
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
-      - name: Check changed files
-        id: changed-files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            **.sh
-            **.yaml
-            **.yml
-            **Dockerfile
-            dev/**
-            .editorconfig
-            .vite-hooks/**
-
       - name: Super-linter
         uses: super-linter/super-linter/slim@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0
-        if: steps.changed-files.outputs.any_changed == 'true'
         env:
           BASH_SEVERITY: warning
           DEFAULT_BRANCH: origin/main

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

@@ -69,7 +69,7 @@ jobs:
             /supported: true/ && value != \"en-US\" {
               printf \"%s \", value
             }
-          " web/i18n-config/languages.ts | sed 's/[[:space:]]*$//')
+          " web/i18n/languages.ts | sed 's/[[:space:]]*$//')
 
           generate_changes_json() {
             node .github/scripts/generate-i18n-changes.mjs
@@ -110,9 +110,9 @@ jobs:
             elif [ "$SYNC_MODE" = "incremental" ]; then
               BASE_SHA=$(git rev-parse HEAD~1 2>/dev/null || true)
               if [ -n "$BASE_SHA" ]; then
-                CHANGED_FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- 'web/i18n/en-US/*.json' 2>/dev/null | sed -n 's@^.*/@@p' | sed 's/\.json$//' | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+                CHANGED_FILES=$(git diff --name-only --find-renames=100% --diff-filter=AMDT "$BASE_SHA" "$HEAD_SHA" -- 'web/i18n/' 2>/dev/null | sed -n '\@^web/i18n/locales/en-US/[^/]*\.json$@p' | sed -n 's@^.*/@@p' | sed 's/\.json$//' | tr '\n' ' ' | sed 's/[[:space:]]*$//')
               else
-                CHANGED_FILES=$(find web/i18n/en-US -maxdepth 1 -type f -name '*.json' -print | sed -n 's@^.*/@@p' | sed 's/\.json$//' | sort | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+                CHANGED_FILES=$(find web/i18n/locales/en-US -maxdepth 1 -type f -name '*.json' -print | sed -n 's@^.*/@@p' | sed 's/\.json$//' | sort | tr '\n' ' ' | sed 's/[[:space:]]*$//')
               fi
             elif [ "$SYNC_MODE" = "full" ]; then
               echo "workflow_dispatch full mode requires the files input to stay within CI limits." >&2
@@ -162,7 +162,7 @@ jobs:
 
       - name: Run Claude Code for Translation Sync
         if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@833fb0f8c9f6686b33d963a8bae0a94f4936ab2a # v1.0.211
+        uses: anthropics/claude-code-action@4036a180cf690f49529f5d8c79c998855287f590 # v1.0.230
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,12 +170,12 @@ jobs:
           show_full_output: ${{ github.event_name == 'workflow_dispatch' }}
           prompt: |
             You are the i18n sync agent for the Dify repository.
-            Your job is to keep translations synchronized with the English source files under `${{ github.workspace }}/web/i18n/en-US/`.
+            Your job is to keep translations synchronized with the English source files under `${{ github.workspace }}/web/i18n/locales/en-US/`.
 
             Use absolute paths at all times:
             - Repo root: `${{ github.workspace }}`
             - Web directory: `${{ github.workspace }}/web`
-            - Language config: `${{ github.workspace }}/web/i18n-config/languages.ts`
+            - Language config: `${{ github.workspace }}/web/i18n/languages.ts`
 
             Inputs:
             - Files in scope: `${{ steps.context.outputs.CHANGED_FILES }}`
@@ -198,12 +198,12 @@ jobs:
             Required execution plan:
             1. Resolve target languages.
                - Use the provided `Target languages` value as the source of truth.
-               - If it is unexpectedly empty, read `${{ github.workspace }}/web/i18n-config/languages.ts` and use every language with `supported: true` except `en-US`.
+               - If it is unexpectedly empty, read `${{ github.workspace }}/web/i18n/languages.ts` and use every language with `supported: true` except `en-US`.
             2. Stay strictly in scope.
                - Only process the files listed in `Files in scope`.
                - Only process the resolved target languages, never `en-US`.
                - Do not touch unrelated i18n files.
-               - Do not modify `${{ github.workspace }}/web/i18n/en-US/`.
+               - Do not modify `${{ github.workspace }}/web/i18n/locales/en-US/`.
             3. Resolve source changes.
                - If `Structured change set available` is `true`, read `/tmp/i18n-changes.json` and use it as the source of truth for file-level and key-level changes.
                - For each file entry:
@@ -227,7 +227,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 fmt <repo-relative edited paths such as web/i18n/...>`
+               - Run `vp fmt <repo-relative edited paths such as web/i18n/locales/...>`
                - 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.
@@ -241,7 +241,7 @@ jobs:
         if: steps.context.outputs.CHANGED_FILES != ''
         shell: bash
         run: |
-          if [ -z "$(git -C "${{ github.workspace }}" status --porcelain -- web/i18n/)" ]; then
+          if [ -z "$(git -C "${{ github.workspace }}" status --porcelain -- web/i18n/locales/)" ]; then
             echo "has_changes=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
@@ -260,7 +260,7 @@ jobs:
         shell: bash
         run: |
           git -C "${{ github.workspace }}" checkout -B "${{ steps.pr_meta.outputs.branch_name }}"
-          git -C "${{ github.workspace }}" add web/i18n/
+          git -C "${{ github.workspace }}" add web/i18n/locales/
           git -C "${{ github.workspace }}" commit -m "chore(i18n): sync translations with en-US"
 
       - name: Push translation branch
@@ -326,7 +326,7 @@ jobs:
             '## Verification',
             '',
             `- \`vp run dify-web#i18n:check --file ${process.env.FILES_IN_SCOPE} --lang ${process.env.TARGET_LANGS}\``,
-            `- \`vp fmt <repo-relative edited paths such as web/i18n/...>\``,
+            `- \`vp fmt <repo-relative edited paths such as web/i18n/locales/...>\``,
             '',
             '## Notes',
             '',

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

@@ -4,7 +4,7 @@ on:
   push:
     branches: [main]
     paths:
-      - 'web/i18n/en-US/*.json'
+      - 'web/i18n/locales/en-US/*.json'
 
 permissions:
   contents: write
@@ -36,9 +36,9 @@ jobs:
           HEAD_SHA="${{ github.sha }}"
 
           if [ -n "$BASE_SHA" ]; then
-            CHANGED_FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- 'web/i18n/en-US/*.json' 2>/dev/null | sed -n 's@^.*/@@p' | sed 's/\.json$//' | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+            CHANGED_FILES=$(git diff --name-only --find-renames=100% --diff-filter=AMDT "$BASE_SHA" "$HEAD_SHA" -- 'web/i18n/' 2>/dev/null | sed -n '\@^web/i18n/locales/en-US/[^/]*\.json$@p' | sed -n 's@^.*/@@p' | sed 's/\.json$//' | tr '\n' ' ' | sed 's/[[:space:]]*$//')
           else
-            CHANGED_FILES=$(find web/i18n/en-US -maxdepth 1 -type f -name '*.json' -print | sed -n 's@^.*/@@p' | sed 's/\.json$//' | sort | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+            CHANGED_FILES=$(find web/i18n/locales/en-US -maxdepth 1 -type f -name '*.json' -print | sed -n 's@^.*/@@p' | sed 's/\.json$//' | sort | tr '\n' ' ' | sed 's/[[:space:]]*$//')
           fi
 
           export BASE_SHA HEAD_SHA CHANGED_FILES

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

@@ -36,7 +36,7 @@ jobs:
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/vdb-tests.yml

@@ -33,7 +33,7 @@ jobs:
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/web-e2e.yml

@@ -9,6 +9,7 @@ on:
         type: boolean
 
 permissions:
+  actions: read
   contents: read
 
 jobs:
@@ -24,8 +25,31 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Test Web build synchronization
+        run: node --test .github/actions/wait-e2e-web-build/wait.test.cjs
+
+      - name: Compute build source hash
+        id: build-source
+        shell: bash
+        run: |
+          # Hash tracked build inputs, excluding generated files and backend-only changes.
+          source_hash=$(git ls-tree -r HEAD -- web packages e2e/scripts e2e/package.json e2e/test-env.ts package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc .github/actions/setup-web .github/workflows/web-e2e.yml | sha256sum | cut -d ' ' -f 1)
+          echo "hash=$source_hash" >> "$GITHUB_OUTPUT"
+
       - name: Setup web dependencies
         uses: ./.github/actions/setup-web
+        with:
+          # Browser jobs already save this dependency cache; avoid duplicate uploads.
+          cache-save: 'false'
+
+      - name: Restore Next.js build cache
+        id: next-cache
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: web/.next/cache
+          key: e2e-next-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml') }}-${{ steps.build-source.outputs.hash }}
+          restore-keys: |
+            e2e-next-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml') }}-
 
       - name: Run E2E support unit tests
         working-directory: ./e2e
@@ -35,7 +59,15 @@ jobs:
         working-directory: ./e2e
         env:
           E2E_FORCE_WEB_BUILD: '1'
-        run: vp run e2e:web:build
+          CACHE_HIT: ${{ steps.next-cache.outputs.cache-hit || 'false' }}
+        run: |
+          started=$SECONDS
+          vp run e2e:web:build
+          {
+            echo "### E2E Web build"
+            echo "Build: $((SECONDS - started))s"
+            echo "Exact cache hit: $CACHE_HIT (false can include a compatible fallback)"
+          } >> "$GITHUB_STEP_SUMMARY"
 
       - name: Package Web build
         run: >-
@@ -48,16 +80,21 @@ jobs:
       - name: Upload Web build
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: core-e2e-web-build
+          name: core-e2e-web-build-${{ github.run_attempt }}
           path: e2e-web-build.tar
           if-no-files-found: error
-          overwrite: true
           retention-days: 7
 
+      - name: Save Next.js build cache
+        if: github.event_name != 'merge_group' && steps.next-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: web/.next/cache
+          key: ${{ steps.next-cache.outputs.cache-primary-key }}
+
   chromium-full:
     name: Chromium Full (${{ matrix.shard }}/3)
     if: ${{ !inputs.run-external-runtime }}
-    needs: core-build
     runs-on: ubuntu-24.04
     timeout-minutes: 45
     strategy:
@@ -76,32 +113,27 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Setup web dependencies
-        uses: ./.github/actions/setup-web
-
-      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - name: Prepare Chromium E2E dependencies
+        timeout-minutes: 15
+        uses: ./.github/actions/setup-core-e2e
         with:
-          enable-cache: true
-          python-version: '3.12'
-          cache-dependency-glob: api/uv.lock
+          browser: chromium
 
-      - name: Install API dependencies
-        run: uv sync --project api --dev
+      # Install dependencies while core-build runs, then wait only for its artifact.
+      - name: Wait for Web build
+        id: web-build
+        timeout-minutes: 35
+        uses: ./.github/actions/wait-e2e-web-build
 
       - name: Download Web build
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          name: core-e2e-web-build
+          artifact-ids: ${{ steps.web-build.outputs.artifact-id }}
+          github-token: ${{ github.token }}
 
       - name: Extract Web build
         run: tar -xf e2e-web-build.tar -C web
 
-      - name: Install Chromium
-        timeout-minutes: 15
-        working-directory: ./e2e
-        run: vp run e2e:install:ci:chromium
-
       - name: Run Chromium full shard
         working-directory: ./e2e
         run: vp run e2e:full -- --shard ${{ matrix.shard }}/3
@@ -130,9 +162,8 @@ jobs:
   webkit-smoke:
     name: WebKit Browser Smoke
     if: ${{ !inputs.run-external-runtime }}
-    needs: core-build
     runs-on: ubuntu-24.04
-    timeout-minutes: 30
+    timeout-minutes: 45
     env:
       E2E_ADMIN_EMAIL: e2e-admin@example.com
       E2E_ADMIN_NAME: E2E Admin
@@ -146,32 +177,27 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Setup web dependencies
-        uses: ./.github/actions/setup-web
-
-      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - name: Prepare WebKit E2E dependencies
+        timeout-minutes: 15
+        uses: ./.github/actions/setup-core-e2e
         with:
-          enable-cache: true
-          python-version: '3.12'
-          cache-dependency-glob: api/uv.lock
+          browser: webkit
 
-      - name: Install API dependencies
-        run: uv sync --project api --dev
+      # Install dependencies while core-build runs, then wait only for its artifact.
+      - name: Wait for Web build
+        id: web-build
+        timeout-minutes: 35
+        uses: ./.github/actions/wait-e2e-web-build
 
       - name: Download Web build
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          name: core-e2e-web-build
+          artifact-ids: ${{ steps.web-build.outputs.artifact-id }}
+          github-token: ${{ github.token }}
 
       - name: Extract Web build
         run: tar -xf e2e-web-build.tar -C web
 
-      - name: Install WebKit
-        timeout-minutes: 15
-        working-directory: ./e2e
-        run: vp run e2e:install:ci:webkit
-
       - name: Run WebKit browser smoke
         working-directory: ./e2e
         run: vp run e2e:full -- --tags '@browser-smoke'
@@ -213,7 +239,7 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: '3.12'

.github/workflows/web-tests.yml

@@ -111,8 +111,7 @@ jobs:
         run: vp test --merge-reports --coverage --silent=passed-only
 
       - name: Report coverage
-        if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           directory: web/coverage
           flags: web
@@ -157,8 +156,7 @@ jobs:
           retention-days: 7
 
       - name: Report coverage
-        if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           directory: packages/dify-ui/coverage
           flags: dify-ui

.gitignore

@@ -185,6 +185,7 @@ docker/volumes/minio/*
 docker/volumes/milvus/*
 docker/volumes/chroma/*
 docker/volumes/opensearch/data/*
+docker/volumes/openshell-mtls/*
 docker/volumes/myscale/data/*
 docker/volumes/myscale/log/*
 docker/volumes/unstructured/*

.vite-hooks/pre-commit

@@ -1,11 +1,5 @@
 #!/bin/sh
-# get the list of modified files
-files=$(git diff --cached --name-only)
-
-# check if api or web directory is modified
-
-api_modified=false
-skip_web_checks=false
+set -eu
 
 git_path() {
     git rev-parse --git-path "$1"
@@ -17,42 +11,7 @@ if [ -f "$(git_path MERGE_HEAD)" ] || \
    [ -f "$(git_path SQUASH_MSG)" ] || \
    [ -d "$(git_path rebase-merge)" ] || \
    [ -d "$(git_path rebase-apply)" ]; then
-    skip_web_checks=true
-fi
-
-for file in $files
-do
-    # Use POSIX compliant pattern matching
-    case "$file" in
-        api/*.py)
-            # set api_modified flag to true
-            api_modified=true
-            ;;
-    esac
-done
-
-# run linters based on the modified modules
-
-if $api_modified; then
-    echo "Running Ruff linter on api module"
-
-    # run Ruff linter auto-fixing
-    uv run --project api --dev ruff check --fix ./api
-
-    # run Ruff linter checks
-    uv run --project api --dev ruff check  ./api || status=$?
-
-    status=${status:-0}
-
-    if [ $status -ne 0 ]; then
-      echo "Ruff linter on api module error, exit code: $status"
-      echo "Please run 'dev/reformat' to fix the fixable linting errors."
-      exit 1
-    fi
-fi
-
-if $skip_web_checks; then
-    echo "Git operation in progress, skipping web checks"
+    echo "Git operation in progress, skipping staged checks; CI validates the result."
     exit 0
 fi
 

AGENTS.md

@@ -1,15 +1,9 @@
 # AGENTS.md
 
-Dify is an open-source platform for building LLM applications, agentic workflows, and RAG pipelines. This monorepo contains the backend API (`api/`), frontend application (`web/`), deployment assets (`docker/`), standalone agent backend (`dify-agent/`), CLI (`cli/`), and end-to-end suite (`e2e/`). Follow the nearest scoped `AGENTS.md` for the files being changed.
+Dify is an open-source platform for building LLM applications, agentic workflows, and RAG pipelines. This monorepo contains the backend API (`api/`), frontend application (`web/`), deployment assets (`docker/`), standalone agent backend (`dify-agent/`), CLI (`cli/`), and end-to-end suite (`e2e/`). Follow the nearest scoped `AGENTS.md` for the files being changed. Apply its guidance within the user's requested scope; explicit user instructions take precedence over workflow defaults.
 
 ## Repository Gotchas
 
 - Run backend commands through `uv run --project api <command>`.
 - Backend integration tests are CI-only and are not expected to run locally.
 - Keep `docker/.env.example` limited to variables required for a default Docker Compose deployment to start. Put optional and provider-specific settings in the matching `docker/envs/*.env.example` file; `docker/.env` overrides those service-specific env files.
-
-## Frontend Workflow
-
-- For truncated text disclosure and native `title` decisions, follow [Truncated Text Disclosure].
-
-[Truncated Text Disclosure]: web/docs/truncated-text-disclosure.md

CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

CONTRIBUTING.md

@@ -22,6 +22,8 @@ Don't forget to link an existing issue or open a new issue in the PR's descripti
 
 ### Bug reports
 
+For security vulnerabilities, follow our [security policy](./SECURITY.md) and report privately instead of opening a public issue.
+
 > [!IMPORTANT]
 > Please make sure to include the following information when submitting a bug report:
 
@@ -36,7 +38,7 @@ How we prioritize:
 
 | Issue Type | Priority |
 | ------------------------------------------------------------ | --------------- |
-| Bugs in core functions (cloud service, cannot login, applications not working, security loopholes) | Critical |
+| Bugs in core functions (cloud service, cannot login, applications not working) | Critical |
 | Non-critical bugs, performance boosts | Medium Priority |
 | Minor fixes (typos, confusing but working UI) | Low Priority |
 
@@ -71,6 +73,10 @@ How we prioritize:
 1. Please link the issue in the PR description, `fixes #<issue_number>`
 1. Get merged!
 
+### AI-assisted contributions
+
+AI tools are welcome, but you are responsible for understanding and verifying every change you submit. Describe the problem, your solution, and actual test results in your own words. Unreviewed or repetitive low-quality submissions may be closed.
+
 ### Setup the project
 
 #### Frontend

README.md

@@ -104,8 +104,7 @@ Intuitive interface for crafting prompts, comparing model performance, and addin
 **4. RAG Pipeline**:
 Extensive RAG capabilities that cover everything from document ingestion to retrieval, with out-of-box support for text extraction from PDFs, PPTs, and other common document formats.
 
-**5. Agent capabilities**:
-You can define agents based on LLM Function Calling or ReAct, and add pre-built or custom tools for the agent. Dify provides 50+ built-in tools for AI agents, such as Google Search, DALL·E, Stable Diffusion and WolframAlpha.
+**5. Agent**: Autonomous agents with a sandbox of their own: they run commands, install software, and handle files to get open-ended tasks done. Describe the agent you want and it builds itself. Give it skills, connect tools from [Dify Marketplace](https://marketplace.dify.ai/?category=tool), MCP servers, or your own APIs, and put it to work as a chat app or as a step in any workflow.
 
 **6. LLMOps**:
 Monitor and analyze application logs and performance over time. You could continuously improve prompts, datasets, and models based on production data and annotations.
@@ -122,8 +121,8 @@ All of Dify's offerings come with corresponding APIs, so you could effortlessly
   Quickly get Dify running in your environment with this [starter guide](#quick-start).
   Use our [documentation](https://docs.dify.ai) for further references and more in-depth instructions.
 
-- **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/>
+- **[Dify Enterprise](https://dify.ai/dify-enterprise)<br/>**
+  For organizations requiring self-hosting, SSO, RBAC Security and Enterprise Support SLAs, please fill out [this form](https://share-na2.hsforms.com/14-09ff5HS92Sh4m3f4yrcw40s9fk) to speak to a solution representative. <br/>
 
 ## Staying ahead
 
@@ -141,7 +140,7 @@ Dify welcomes contributions of all kinds:
 
 - **Code**: Read the [Contribution Guide](CONTRIBUTING.md), then browse [good first issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
 - **Ideas and feedback**: Start or join a [GitHub Discussion](https://github.com/langgenius/dify/discussions).
-- **Translations**: Follow the [internationalization guide](web/i18n-config/README.md) to add or update a locale.
+- **Translations**: Follow the [internationalization guide](web/i18n/README.md) to add or update a locale.
 - **Community**: Share the apps you build, help other users, and spread the word about Dify.
 
 ### Contributors

api/.env.example

@@ -234,6 +234,7 @@ VECTOR_INDEX_NAME_PREFIX=Vector_index
 
 # Weaviate configuration
 WEAVIATE_ENDPOINT=http://localhost:8080
+WEAVIATE_GRPC_ENDPOINT=grpc://localhost:50051
 WEAVIATE_API_KEY=WVF5YThaHlkYwhGUSmCRgsX3tD5ngdN8pkih
 WEAVIATE_BATCH_SIZE=100
 WEAVIATE_TOKENIZATION=word
@@ -459,6 +460,12 @@ UPLOAD_IMAGE_FILE_SIZE_LIMIT=10
 UPLOAD_VIDEO_FILE_SIZE_LIMIT=100
 UPLOAD_AUDIO_FILE_SIZE_LIMIT=50
 UPLOAD_SKILL_FILE_SIZE_LIMIT=50
+SKILL_PACKAGE_MAX_UNCOMPRESSED_BYTES=209715200
+SKILL_PACKAGE_MAX_ENTRIES=5000
+SKILL_PACKAGE_MAX_SKILL_MD_BYTES=1048576
+AGENT_PACKAGE_MAX_BYTES=536870912
+AGENT_PACKAGE_MAX_MANIFEST_BYTES=5242880
+AGENT_PACKAGE_MAX_ENTRIES=5000
 
 # Comma-separated list of file extensions blocked from upload for security reasons.
 # Extensions should be lowercase without dots (e.g., exe,bat,sh,dll).

api/.importlinter

@@ -203,6 +203,7 @@ forbidden_modules =
 name = Account application services and contracts are framework and persistence neutral
 type = forbidden
 source_modules =
+    services.account_access_service
     services.account_avatar_service
     services.account_change_email_ports
     services.account_change_email_service
@@ -214,10 +215,16 @@ source_modules =
     services.account_forgot_password_service
     services.account_initialization_service
     services.account_integration_service
+    services.account_login_service
+    services.account_oauth_service
     services.account_password_service
     services.account_ports
     services.account_profile_service
+    services.entities.account_access_entities
     services.entities.account_entities
+    services.entities.account_login_entities
+    services.entities.account_oauth_entities
+    services.entities.auth_audit_entities
 forbidden_modules =
     configs
     controllers
@@ -257,6 +264,49 @@ forbidden_modules =
     sqlalchemy
     werkzeug
 
+[importlinter:contract:app-tracing-config-service-boundary]
+name = App tracing configuration service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_tracing_config_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:message-file-preview-service-boundary]
+name = Message file preview application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.message_file_preview_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:upload-file-delivery-service-boundary]
+name = Upload file delivery application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.upload_file_delivery_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
 [importlinter:contract:webapp-access-query-service-boundary]
 name = Web app access query application service is framework and persistence neutral
 type = forbidden
@@ -418,6 +468,36 @@ forbidden_modules =
     sqlalchemy
     werkzeug
 
+[importlinter:contract:file-grant-service-boundary]
+name = File grant application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.file_grant_service
+    services.entities.file_grant_entities
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:plugin-file-upload-service-boundary]
+name = Plugin file upload application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.plugin_file_upload_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
 [importlinter:contract:account-activation-service-boundary]
 name = Account activation application service is framework and persistence neutral
 type = forbidden
@@ -449,6 +529,20 @@ forbidden_modules =
     sqlalchemy
     werkzeug
 
+[importlinter:contract:tool-file-download-service-boundary]
+name = Tool file download application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.tool_file_download_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
 [importlinter:contract:recommended-app-query-service-boundary]
 name = Recommended app query application service is framework and persistence neutral
 type = forbidden
@@ -474,6 +568,52 @@ source_modules =
 forbidden_modules =
     flask
 
+[importlinter:contract:trial-app-application-boundary]
+name = Trial app access and generation services are framework and persistence neutral
+type = forbidden
+source_modules =
+    services.trial_app_access_service
+    services.trial_app_generation_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.app_generate_service
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:app-preview-query-boundary]
+name = App preview queries are framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_preview_query_service
+    services.app_preview_details_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:message-suggested-questions-boundary]
+name = Message suggested questions port is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.message_suggested_questions_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.message_service
+    sqlalchemy
+    werkzeug
+
 [importlinter:contract:billing-application-boundary]
 name = Billing application services and ports are framework and infrastructure neutral
 type = forbidden

api/AGENTS.md

@@ -23,3 +23,8 @@ Run direct Python commands through `uv run --project api`. Docker-backed integra
 - Use Pydantic v2 for request and response models. Reuse domain-specific exceptions and translate them at the controller boundary.
 - Use existing Celery task and queue owners for asynchronous work; do not route unrelated jobs through workflow-specific services.
 - Celery tasks that may be retried or redelivered must keep side effects idempotent and log affected resource identifiers.
+
+## Typing Best Practises
+
+- Treat nullable types (`T | None`) strictly as union types; document the semantic meaning for each branch.
+- Treat default parameter values as introducing distinct function overloads; verify that every added default has demonstrable practical utility and avoids masking unsafe runtime states.

api/README.md

@@ -87,16 +87,17 @@ The scripts resolve paths relative to their location, so you can run them from a
    uv sync --group dev
    ```
 
-1. Run the tests locally with mocked system environment variables in `tool.pytest_env` section in `pyproject.toml`, more can check [Claude.md](../CLAUDE.md)
+1. Run the tests locally with mocked system environment variables in `tool.pytest_env` section in `pyproject.toml`, more can check [AGENTS.md](../AGENTS.md)
+
+   Continue in the `api` directory from the previous step.
 
    ```bash
-   cd api
    uv run pytest                           # Run all tests
    uv run pytest tests/unit_tests/         # Unit tests only
    uv run pytest tests/integration_tests/  # Integration tests
 
    # Code quality
-   ./dev/reformat               # Run all formatters and linters
+   ../dev/reformat              # Run all formatters and linters
    uv run ruff check --fix ./   # Fix linting issues
    uv run ruff format ./        # Format code
    uv run pyrefly check         # Type checking

api/app_factory.py

@@ -105,6 +105,10 @@ def create_flask_app_with_configs() -> DifyApp:
     dify_app = DifyApp(__name__)
     dify_app.config.from_mapping(dify_config.model_dump())
     dify_app.config["RESTX_INCLUDE_ALL_MODELS"] = True
+    # flask-restx appends url-map suggestions to 404 bodies: they enumerate routes to
+    # anonymous callers, and a policy 404 on an existing route (edition admission)
+    # ends up suggesting the very path that was just requested.
+    dify_app.config["RESTX_ERROR_404_HELP"] = False
 
     # add before request hook
     @dify_app.before_request

api/clients/agent_backend/request_builder.py

@@ -36,6 +36,11 @@ from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyK
 from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
 from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
 from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
+from dify_agent.layers.user_prompt import (
+    DIFY_USER_PROMPT_LAYER_TYPE_ID,
+    DifyUserPromptFileConfig,
+    DifyUserPromptLayerConfig,
+)
 from dify_agent.protocol import (
     DIFY_AGENT_HISTORY_LAYER_ID,
     DIFY_AGENT_MODEL_LAYER_ID,
@@ -246,6 +251,7 @@ class AgentBackendAgentAppRunInput(BaseModel):
     execution_context: DifyExecutionContextLayerConfig
     backend_binding_ref: str = Field(min_length=1)
     user_prompt: str
+    user_files: list[DifyUserPromptFileConfig] = Field(default_factory=list)
     agent_soul_prompt: str | None = None
     agent_config_version_kind: AgentConfigVersionKind = "snapshot"
     idempotency_key: str | None = None
@@ -310,9 +316,9 @@ class AgentBackendRunRequestBuilder:
             [
                 RunLayerSpec(
                     name=AGENT_APP_USER_PROMPT_LAYER_ID,
-                    type=PLAIN_PROMPT_LAYER_TYPE_ID,
+                    type=DIFY_USER_PROMPT_LAYER_TYPE_ID,
                     metadata={**run_input.metadata, "origin": "agent_app_user_prompt"},
-                    config=PromptLayerConfig(user=run_input.user_prompt),
+                    config=DifyUserPromptLayerConfig(text=run_input.user_prompt, files=run_input.user_files),
                 ),
                 RunLayerSpec(
                     name=DIFY_EXECUTION_CONTEXT_LAYER_ID,
@@ -632,7 +638,7 @@ class AgentBackendRunRequestBuilder:
         )
 
 
-_SENSITIVE_KEY_PARTS = ("secret", "credential", "token", "password", "api_key")
+_SENSITIVE_KEY_PARTS = ("secret", "credential", "token", "password", "api_key", "base64_data")
 
 
 def redact_for_agent_backend_log(value: object) -> object:
@@ -641,9 +647,10 @@ def redact_for_agent_backend_log(value: object) -> object:
         return redact_for_agent_backend_log(value.model_dump(mode="json", warnings=False))
     if isinstance(value, dict):
         redacted: dict[object, object] = {}
+        is_multimodal_file = value.get("type") == "image" and "filename" in value and "mime_type" in value
         for key, item in value.items():
             key_text = str(key).lower()
-            if any(part in key_text for part in _SENSITIVE_KEY_PARTS):
+            if any(part in key_text for part in _SENSITIVE_KEY_PARTS) or (is_multimodal_file and key_text == "url"):
                 redacted[key] = "[REDACTED]"
             else:
                 redacted[key] = redact_for_agent_backend_log(item)

api/commands/__init__.py

@@ -23,6 +23,7 @@ from .plugin import (
     transform_datasource_credentials,
 )
 from .rbac import (
+    migrate_agent_permissions_to_rbac,
     migrate_dataset_permissions_to_rbac,
     migrate_member_roles_to_rbac,
     migrate_only_me_resource_whitelist_scopes_to_automatic_include,
@@ -81,6 +82,7 @@ __all__ = [
     "install_plugins",
     "install_rag_pipeline_plugins",
     "legacy_model_types",
+    "migrate_agent_permissions_to_rbac",
     "migrate_annotation_vector_database",
     "migrate_data_for_plugin",
     "migrate_dataset_permissions_to_rbac",

api/commands/plugin.py

@@ -32,7 +32,7 @@ logger = logging.getLogger(__name__)
 @click.command("setup-system-tool-oauth-client", help="Setup system tool oauth client.")
 @click.option("--provider", prompt=True, help="Provider name")
 @click.option("--client-params", prompt=True, help="Client Params")
-def setup_system_tool_oauth_client(provider, client_params):
+def setup_system_tool_oauth_client(provider: str, client_params: str):
     """
     Setup system tool oauth client
     """
@@ -79,7 +79,7 @@ def setup_system_tool_oauth_client(provider, client_params):
 @click.command("setup-system-trigger-oauth-client", help="Setup system trigger oauth client.")
 @click.option("--provider", prompt=True, help="Provider name")
 @click.option("--client-params", prompt=True, help="Client Params")
-def setup_system_trigger_oauth_client(provider, client_params):
+def setup_system_trigger_oauth_client(provider: str, client_params: str):
     """
     Setup system trigger oauth client
     """
@@ -129,7 +129,7 @@ def setup_system_trigger_oauth_client(provider, client_params):
 @click.command("setup-datasource-oauth-client", help="Setup datasource oauth client.")
 @click.option("--provider", prompt=True, help="Provider name")
 @click.option("--client-params", prompt=True, help="Client Params")
-def setup_datasource_oauth_client(provider, client_params):
+def setup_datasource_oauth_client(provider: str, client_params: str):
     """
     Setup datasource oauth client
     """

api/commands/rbac.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import json
 from collections.abc import Iterator
 from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from enum import StrEnum
 
 import click
 from sqlalchemy import select
@@ -11,12 +13,34 @@ from sqlalchemy.orm import Session
 from configs import dify_config
 from core.db.session_factory import session_factory
 from core.rbac import RBACResourceWhitelistScope
-from models import App, Dataset, DatasetPermission, DatasetPermissionEnum, TenantAccountJoin, TenantAccountRole
-from services.enterprise.rbac_service import ListOption, RBACService, ReplaceMemberBindings, ReplaceUserAccessPolicies
+from models import (
+    Agent,
+    AgentStatus,
+    App,
+    Dataset,
+    DatasetPermission,
+    DatasetPermissionEnum,
+    Tenant,
+    TenantAccountJoin,
+    TenantAccountRole,
+)
+from services.enterprise.rbac_service import (
+    LegacyAgentRoleMigration,
+    ListOption,
+    RBACResourceType,
+    RBACService,
+    ReplaceMemberBindings,
+    ReplaceUserAccessPolicies,
+)
 
 _RBAC_DEFAULT_ACCESS_POLICY_ID = "default"
 _RBAC_RESOURCE_ACCESS_POLICY_BATCH_SIZE = 500
 
+_AGENT_MIGRATION_STATE_LABEL = {
+    False: "would change",
+    True: "changed",
+}
+
 _LEGACY_ROLE_TO_BUILTIN_TAG = {
     TenantAccountRole.OWNER.value: "owner",
     TenantAccountRole.ADMIN.value: "admin",
@@ -67,6 +91,88 @@ def _resolve_builtin_role_id(tenant_id: str, operator_account_id: str, legacy_ro
     return _resolve_builtin_role_ids(tenant_id, operator_account_id)[legacy_role]
 
 
+def _iter_tenant_ids(tenant_id: str | None, *, batch_size: int) -> Iterator[str]:
+    if tenant_id:
+        yield tenant_id
+        return
+    last_id: str | None = None
+    while True:
+        with session_factory.create_session() as session:
+            stmt = select(Tenant.id).order_by(Tenant.id.asc()).limit(batch_size)
+            if last_id is not None:
+                stmt = stmt.where(Tenant.id > last_id)
+            rows = session.execute(stmt).scalars().all()
+        if not rows:
+            return
+        for row in rows:
+            yield str(row)
+        last_id = str(rows[-1])
+
+
+def _emit_agent_migration_event(payload: dict[str, object]) -> None:
+    click.echo(json.dumps(payload, sort_keys=True))
+
+
+@dataclass(frozen=True)
+class _AgentMigrationEventKind:
+    event_stem: str
+    include_tenant_id: bool = True
+
+    @property
+    def skipped(self) -> str:
+        return f"{self.event_stem}_skipped"
+
+    @property
+    def failed(self) -> str:
+        return f"{self.event_stem}_failed"
+
+    def outcome(self, *, apply: bool) -> str:
+        return f"{self.event_stem}_applied" if apply else f"{self.event_stem}_proposed_change"
+
+
+_AGENT_ROLE_MIGRATION_EVENT_KIND = _AgentMigrationEventKind(event_stem="agent_manage_role_migration")
+_AGENT_ROLE_TEMPLATE_MIGRATION_EVENT_KIND = _AgentMigrationEventKind(
+    event_stem="agent_manage_role_template_migration", include_tenant_id=False
+)
+_AGENT_ACCESS_BOOTSTRAP_EVENT_KIND = _AgentMigrationEventKind(event_stem="agent_access_bootstrap")
+
+_AGENT_BACKING_APP_SPECIFIC_WHITELIST_EVENT = "agent_backing_app_has_specific_whitelist"
+_AGENT_ACCESS_BOOTSTRAP_MEMBER_SOURCE = "workspace_members"
+
+
+class _AgentAccessBootstrapReason(StrEnum):
+    ALREADY_INITIALIZED = "already_initialized"
+    MISSING_WHITELIST_SCOPE = "missing_whitelist_scope"
+    NO_CREATOR = "no_creator"
+
+
+def _agent_manage_role_event(
+    tenant_id: str | None,
+    entry: LegacyAgentRoleMigration,
+    *,
+    apply: bool,
+    kind: _AgentMigrationEventKind,
+) -> dict[str, object]:
+    base: dict[str, object] = {
+        "dry_run": not apply,
+        "role_id": entry.role_id,
+        "role_name": entry.role_name,
+    }
+    if kind.include_tenant_id:
+        base["tenant_id"] = tenant_id
+    if entry.skipped:
+        return {**base, "event": kind.skipped, "reason": entry.skipped}
+    return {
+        **base,
+        "event": kind.outcome(apply=apply),
+        "after": {
+            "added_keys": entry.added_keys,
+            "removed_keys": entry.removed_keys,
+            "bound_policies": entry.bound_policies,
+        },
+    }
+
+
 def _iter_tenant_member_batches(
     tenant_id: str | None,
     *,
@@ -1005,3 +1111,302 @@ def migrate_dataset_permissions_to_rbac(
                 fg="green",
             )
         )
+
+
+_AgentRow = tuple[str, str | None, str | None]
+
+
+def _iter_agent_row_batches(tenant_id: str, batch_size: int) -> Iterator[list[_AgentRow]]:
+    last_agent_id: str | None = None
+    while True:
+        with session_factory.create_session() as session:
+            stmt = (
+                select(Agent.id, Agent.created_by, Agent.backing_app_id)
+                .where(Agent.tenant_id == tenant_id, Agent.status != AgentStatus.ARCHIVED)
+                .order_by(Agent.id.asc())
+                .limit(batch_size)
+            )
+            if last_agent_id:
+                stmt = stmt.where(Agent.id > last_agent_id)
+
+            rows = list(session.execute(stmt).all())
+            if not rows:
+                return
+
+        yield [
+            (
+                str(row.id),
+                str(row.created_by) if row.created_by else None,
+                str(row.backing_app_id) if row.backing_app_id else None,
+            )
+            for row in rows
+        ]
+
+        last_agent_id = str(rows[-1].id)
+
+
+@dataclass
+class _AgentAccessBootstrapCounts:
+    changed: int = 0
+    already_initialized: int = 0
+
+
+@dataclass(frozen=True)
+class _AgentAccessBootstrapOptions:
+    tenant_id: str
+    agent_id: str
+    creator_account_id: str | None
+    backing_app_id: str | None
+    operator_account_id: str
+    member_batch_size: int
+    apply: bool
+    initialized: bool
+
+
+def _report_backing_app_specific_whitelist(options: _AgentAccessBootstrapOptions) -> None:
+    if not options.backing_app_id:
+        return
+    app_config = _resource_legacy_whitelist_config(
+        "app",
+        tenant_id=options.tenant_id,
+        operator_account_id=options.operator_account_id,
+        resource_id=options.backing_app_id,
+    )
+    if _normalize_rbac_whitelist_scope(app_config.rbac_whitelist_scope) is not RBACResourceWhitelistScope.SPECIFIC:
+        return
+    _emit_agent_migration_event(
+        {
+            "event": _AGENT_BACKING_APP_SPECIFIC_WHITELIST_EVENT,
+            "dry_run": not options.apply,
+            "tenant_id": options.tenant_id,
+            "agent_id": options.agent_id,
+            "app_id": options.backing_app_id,
+            "backing_app_account_ids": sorted(set(app_config.account_ids)),
+        }
+    )
+
+
+def _write_agent_access_rows(options: _AgentAccessBootstrapOptions) -> None:
+    for batch in _workspace_member_account_id_batches(options.tenant_id, options.member_batch_size):
+        RBACService.AgentAccess.replace_user_access_policies(
+            tenant_id=options.tenant_id,
+            account_id=options.operator_account_id,
+            agent_id=options.agent_id,
+            target_account_id=None,
+            payload=ReplaceUserAccessPolicies(
+                access_policy_ids=[_RBAC_DEFAULT_ACCESS_POLICY_ID],
+                account_ids=batch,
+            ),
+        )
+    if options.creator_account_id:
+        RBACService.AccessPolicies.sync_creator_access_policy_member_bindings(
+            tenant_id=options.tenant_id,
+            account_id=options.creator_account_id,
+            resource_type=RBACResourceType.AGENT,
+            resource_id=options.agent_id,
+        )
+    RBACService.AgentAccess.replace_whitelist(
+        tenant_id=options.tenant_id,
+        account_id=options.operator_account_id,
+        agent_id=options.agent_id,
+        payload=ReplaceMemberBindings(automatic_include_workspace_members=True),
+    )
+
+
+def _emit_agent_access_bootstrap_skipped(
+    options: _AgentAccessBootstrapOptions,
+    reason: _AgentAccessBootstrapReason,
+) -> None:
+    _emit_agent_migration_event(
+        {
+            "event": _AGENT_ACCESS_BOOTSTRAP_EVENT_KIND.skipped,
+            "reason": reason.value,
+            "dry_run": not options.apply,
+            "tenant_id": options.tenant_id,
+            "agent_id": options.agent_id,
+            "operator_account_id": options.operator_account_id,
+        }
+    )
+
+
+def _agent_access_bootstrap_failure(
+    options: _AgentAccessBootstrapOptions,
+    exc: Exception,
+) -> click.ClickException:
+    _emit_agent_migration_event(
+        {
+            "event": _AGENT_ACCESS_BOOTSTRAP_EVENT_KIND.failed,
+            "tenant_id": options.tenant_id,
+            "agent_id": options.agent_id,
+            "error": str(exc),
+        }
+    )
+    return click.ClickException(f"tenant {options.tenant_id} agent {options.agent_id}: {exc}")
+
+
+def _bootstrap_agent_access(options: _AgentAccessBootstrapOptions, counts: _AgentAccessBootstrapCounts) -> None:
+    if options.initialized:
+        counts.already_initialized += 1
+        _emit_agent_access_bootstrap_skipped(options, _AgentAccessBootstrapReason.ALREADY_INITIALIZED)
+        return
+
+    config = RBACService.AgentAccess.legacy_whitelist_config(
+        tenant_id=options.tenant_id,
+        account_id=options.operator_account_id,
+        agent_id=options.agent_id,
+    )
+    try:
+        scope = _normalize_rbac_whitelist_scope(config.rbac_whitelist_scope)
+    except ValueError as exc:
+        raise _agent_access_bootstrap_failure(options, exc) from exc
+    if scope is None:
+        _emit_agent_access_bootstrap_skipped(options, _AgentAccessBootstrapReason.MISSING_WHITELIST_SCOPE)
+        return
+
+    account_ids = sorted(set(config.account_ids))
+    _report_backing_app_specific_whitelist(options)
+
+    if options.apply:
+        try:
+            _write_agent_access_rows(options)
+        except Exception as exc:
+            raise _agent_access_bootstrap_failure(options, exc) from exc
+    counts.changed += 1
+
+    event: dict[str, object] = {
+        "event": _AGENT_ACCESS_BOOTSTRAP_EVENT_KIND.outcome(apply=options.apply),
+        "dry_run": not options.apply,
+        "tenant_id": options.tenant_id,
+        "agent_id": options.agent_id,
+        "operator_account_id": options.operator_account_id,
+        "before": {"rbac_whitelist_scope": scope.value, "whitelist_account_ids": account_ids},
+        "after": {
+            "automatic_include_workspace_members": True,
+            "default_policy_member_source": _AGENT_ACCESS_BOOTSTRAP_MEMBER_SOURCE,
+            "creator_access_policy_synced": bool(options.creator_account_id),
+        },
+    }
+    if not options.creator_account_id:
+        event["reason"] = _AgentAccessBootstrapReason.NO_CREATOR.value
+    _emit_agent_migration_event(event)
+
+
+def _bootstrap_tenant_agent_access(
+    tenant_id: str,
+    *,
+    agent_batch_size: int,
+    member_batch_size: int,
+    apply: bool,
+    counts: _AgentAccessBootstrapCounts,
+) -> None:
+    owner_account_id: str | None = None
+    for rows in _iter_agent_row_batches(tenant_id, agent_batch_size):
+        initialized_agent_ids = set(
+            RBACService.Migrations.list_configured_agent_ids(tenant_id, [agent_id for agent_id, _, _ in rows])
+        )
+        for agent_id, creator_account_id, backing_app_id in rows:
+            if creator_account_id:
+                operator_account_id = creator_account_id
+            else:
+                if owner_account_id is None:
+                    with session_factory.create_session() as session:
+                        owner_account_id = _owner_account_id(tenant_id, session=session)
+                operator_account_id = owner_account_id
+            _bootstrap_agent_access(
+                _AgentAccessBootstrapOptions(
+                    tenant_id=tenant_id,
+                    agent_id=agent_id,
+                    creator_account_id=creator_account_id,
+                    backing_app_id=backing_app_id,
+                    operator_account_id=operator_account_id,
+                    member_batch_size=member_batch_size,
+                    apply=apply,
+                    initialized=agent_id in initialized_agent_ids,
+                ),
+                counts,
+            )
+
+
+@click.command(
+    "rbac-migrate-agent-permissions",
+    help=(
+        "Upgrade step for agent RBAC. Phase 1 asks the RBAC service to replace agent.manage on every "
+        "custom role with agent.create plus the agent.full_access binding. Phase 2 bootstraps the access "
+        "rows pre-existing agents never got, so they stay visible to workspace members. Agents that "
+        "already have a whitelist scope row are skipped. Dry run by default."
+    ),
+)
+@click.option("--tenant-id", help="Only migrate a single workspace.")
+@click.option(
+    "--batch-size",
+    default=500,
+    show_default=True,
+    type=click.IntRange(min=1),
+    help="Tenants fetched per database batch.",
+)
+@click.option(
+    "--agent-batch-size",
+    default=500,
+    show_default=True,
+    type=click.IntRange(min=1),
+    help="Agents fetched per database batch.",
+)
+@click.option(
+    "--member-batch-size",
+    default=_RBAC_RESOURCE_ACCESS_POLICY_BATCH_SIZE,
+    show_default=True,
+    type=click.IntRange(min=1),
+    help="Workspace members written per default-policy call when bootstrapping an agent.",
+)
+@click.option("--apply", is_flag=True, default=False, help="Write changes. Without it nothing is written.")
+def migrate_agent_permissions_to_rbac(
+    tenant_id: str | None,
+    batch_size: int,
+    agent_batch_size: int,
+    member_batch_size: int,
+    apply: bool,
+) -> None:
+    click.echo(click.style("Starting agent RBAC migration: custom roles holding agent.manage.", fg="green"))
+    tenant_count = 0
+    role_count = 0
+    skipped_count = 0
+    seen_template_ids: set[str] = set()
+    template_count = 0
+    agent_counts = _AgentAccessBootstrapCounts()
+    for workspace_id in _iter_tenant_ids(tenant_id, batch_size=batch_size):
+        tenant_count += 1
+        try:
+            report = RBACService.Migrations.migrate_agent_manage_roles(workspace_id, apply=apply)
+        except Exception as exc:
+            raise click.ClickException(f"tenant {workspace_id}: {exc}") from exc
+        for entry in report.roles:
+            role_count += 1
+            if entry.skipped:
+                skipped_count += 1
+            _emit_agent_migration_event(
+                _agent_manage_role_event(workspace_id, entry, apply=apply, kind=_AGENT_ROLE_MIGRATION_EVENT_KIND)
+            )
+        for template in report.role_templates:
+            if template.role_id in seen_template_ids:
+                continue
+            seen_template_ids.add(template.role_id)
+            template_count += 1
+            _emit_agent_migration_event(
+                _agent_manage_role_event(None, template, apply=apply, kind=_AGENT_ROLE_TEMPLATE_MIGRATION_EVENT_KIND)
+            )
+        _bootstrap_tenant_agent_access(
+            workspace_id,
+            agent_batch_size=agent_batch_size,
+            member_batch_size=member_batch_size,
+            apply=apply,
+            counts=agent_counts,
+        )
+    role_state = _AGENT_MIGRATION_STATE_LABEL[apply]
+    click.echo(
+        f"{tenant_count} tenant(s), {role_count} role(s) {role_state}, {skipped_count} skipped, "
+        f"{template_count} template(s) {role_state}, "
+        f"{agent_counts.changed} agent(s) {role_state}, "
+        f"{agent_counts.already_initialized} already initialised"
+    )
+    if not apply:
+        click.echo(click.style("Dry run: no changes written. Re-run with --apply.", fg="yellow"))

api/commands/storage.py

@@ -751,7 +751,7 @@ def migrate_oss(
                             UploadFile.storage_type == source_storage_type,
                             UploadFile.key.in_(copied_upload_file_keys),
                         )
-                        .values(storage_type=dify_config.STORAGE_TYPE)
+                        .values(storage_type=StorageType(dify_config.STORAGE_TYPE))
                     ),
                 ).rowcount
                 db.session.commit()

api/configs/extra/agent_backend_config.py

@@ -7,6 +7,18 @@ class AgentBackendConfig(BaseSettings):
     Configuration settings for the Agent backend runtime integration.
     """
 
+    AGENT_SANDBOX_METERING_ENABLED: bool = Field(default=False, description="Persist independent E2B runtime usage.")
+    AGENT_SANDBOX_METERING_PROJECT_ID: str = Field(
+        default="", description="Allowed E2B project/team for this database."
+    )
+    AGENT_SANDBOX_METERING_START_AT: str = Field(
+        default="", description="Immutable UTC activation instant, aligned to a whole second; required when enabled."
+    )
+    AGENT_SANDBOX_METERING_INTERVAL_SECONDS: int | str = Field(
+        default=60,
+        description="Celery Beat interval in seconds; validated only when registering optional usage collection.",
+    )
+
     AGENT_BACKEND_BASE_URL: str | None = Field(
         description="Base URL for the Dify Agent backend service.",
         default=None,

api/configs/feature/__init__.py

@@ -481,6 +481,36 @@ class FileUploadConfig(BaseSettings):
         default=50,
     )
 
+    SKILL_PACKAGE_MAX_UNCOMPRESSED_BYTES: PositiveInt = Field(
+        description="Maximum total uncompressed size of a Skill package in bytes",
+        default=200 * 1024 * 1024,
+    )
+
+    SKILL_PACKAGE_MAX_ENTRIES: PositiveInt = Field(
+        description="Maximum number of entries in a Skill package",
+        default=5000,
+    )
+
+    SKILL_PACKAGE_MAX_SKILL_MD_BYTES: PositiveInt = Field(
+        description="Maximum allowed SKILL.md size in bytes",
+        default=1 * 1024 * 1024,
+    )
+
+    AGENT_PACKAGE_MAX_BYTES: PositiveInt = Field(
+        description="Maximum allowed Agent package size in bytes",
+        default=512 * 1024 * 1024,
+    )
+
+    AGENT_PACKAGE_MAX_MANIFEST_BYTES: PositiveInt = Field(
+        description="Maximum allowed size of each Agent package YAML document in bytes",
+        default=5 * 1024 * 1024,
+    )
+
+    AGENT_PACKAGE_MAX_ENTRIES: PositiveInt = Field(
+        description="Maximum number of entries in an Agent package",
+        default=5000,
+    )
+
     BATCH_UPLOAD_LIMIT: NonNegativeInt = Field(
         description="Maximum number of files allowed in a batch upload operation",
         default=20,
@@ -1614,7 +1644,7 @@ class AccountConfig(BaseSettings):
     )
 
     EDUCATION_ENABLED: bool = Field(
-        description="whether to enable education identity",
+        description="whether to enable education identity (CLOUD deployments only)",
         default=False,
     )
 

api/configs/packaging/pyproject.py

@@ -6,17 +6,6 @@ class PyProjectConfig(BaseModel):
     version: str = Field(description="Dify version", default="")
 
 
-class DifyToolConfig(BaseModel):
-    min_difyctl_version: str = Field(
-        description="Oldest difyctl version served on /openapi/v1",
-        default="0.0.0",
-    )
-
-
-class ToolConfig(BaseModel):
-    dify: DifyToolConfig = Field(default=DifyToolConfig())
-
-
 class PyProjectTomlConfig(BaseSettings):
     """
     configs in api/pyproject.toml
@@ -26,8 +15,3 @@ class PyProjectTomlConfig(BaseSettings):
         description="configs in the project section of pyproject.toml",
         default=PyProjectConfig(),
     )
-
-    tool: ToolConfig = Field(
-        description="configs in the [tool.*] section of pyproject.toml",
-        default=ToolConfig(),
-    )

api/configs/remote_settings_sources/apollo/__init__.py

@@ -52,5 +52,4 @@ class ApolloSettingsSource(RemoteSettingsSource):
     def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
         if not isinstance(self.remote_configs, dict):
             raise ValueError(f"remote configs is not dict, but {type(self.remote_configs)}")
-        field_value = self.remote_configs.get(field_name)
-        return field_value, field_name, False
+        return self.resolve_field_value(self.remote_configs, field, field_name)

api/configs/remote_settings_sources/base.py

@@ -1,6 +1,7 @@
 from collections.abc import Mapping
 from typing import Any
 
+from pydantic import AliasChoices
 from pydantic.fields import FieldInfo
 
 
@@ -11,5 +12,28 @@ class RemoteSettingsSource:
     def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
         raise NotImplementedError
 
+    @staticmethod
+    def resolve_field_value(
+        remote_configs: Mapping[str, Any], field: FieldInfo, field_name: str
+    ) -> tuple[Any, str, bool]:
+        field_value = remote_configs.get(field_name)
+        if field_value is not None:
+            return field_value, field_name, False
+
+        validation_alias = field.validation_alias
+        if isinstance(validation_alias, str):
+            aliases = [validation_alias]
+        elif isinstance(validation_alias, AliasChoices):
+            aliases = [alias for alias in validation_alias.choices if isinstance(alias, str)]
+        else:
+            aliases = []
+
+        for alias in aliases:
+            field_value = remote_configs.get(alias)
+            if field_value is not None:
+                return field_value, alias, False
+
+        return None, field_name, False
+
     def prepare_field_value(self, field_name: str, field: FieldInfo, value: Any, value_is_complex: bool):
         return value

api/configs/remote_settings_sources/nacos/__init__.py

@@ -43,8 +43,4 @@ class NacosSettingsSource(RemoteSettingsSource):
 
     @override
     def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
-        field_value = self.remote_configs.get(field_name)
-        if field_value is None:
-            return None, field_name, False
-
-        return field_value, field_name, False
+        return self.resolve_field_value(self.remote_configs, field, field_name)

api/conftest.py

@@ -8,6 +8,7 @@ tests below their directory, and this setup is shared by api/tests and api/provi
 
 from __future__ import annotations
 
+from dataclasses import replace
 from pathlib import Path
 
 import pytest
@@ -33,6 +34,26 @@ ensure_backend_test_environment(_REPO_ROOT)
 
 def pytest_addoption(parser: pytest.Parser) -> None:
     group = parser.getgroup("dify")
+    group.addoption("--file-shard-plan", type=Path, help="Shared pre-collection file/partition assignment.")
+    group.addoption("--write-test-durations", type=Path, help="Write successful-run file durations for CI history.")
+    group.addoption(
+        "--middleware-stop-timeout",
+        type=int,
+        default=None,
+        help="Override the shutdown grace period in seconds for pytest-started middleware only.",
+    )
+    group.addoption(
+        "--shard-index",
+        type=int,
+        default=1,
+        help="One-based index of the test shard to run.",
+    )
+    group.addoption(
+        "--shard-total",
+        type=int,
+        default=1,
+        help="Total number of test shards.",
+    )
     group.addoption(
         "--start-middleware",
         action="store_true",
@@ -58,9 +79,60 @@ def pytest_addoption(parser: pytest.Parser) -> None:
 
 
 def pytest_configure(config: pytest.Config) -> None:
+    shard_index = config.getoption("shard_index")
+    shard_total = config.getoption("shard_total")
+    if shard_total < 1:
+        raise pytest.UsageError("--shard-total must be at least 1")
+    if not 1 <= shard_index <= shard_total:
+        raise pytest.UsageError("--shard-index must be between 1 and --shard-total")
+    stop_timeout = config.getoption("middleware_stop_timeout")
+    if stop_timeout is not None and stop_timeout < 0:
+        raise pytest.UsageError("--middleware-stop-timeout must be nonnegative")
+
+    durations_path = config.getoption("write_test_durations")
+    if durations_path is not None and not hasattr(config, "workerinput"):
+        from tests.pytest_timing import TestDurationsPlugin
+
+        config.pluginmanager.register(TestDurationsPlugin(durations_path), "dify-test-durations")
+
     config.stash[_DIFY_COMPOSE_STACKS_KEY] = []
 
 
+def pytest_collection_modifyitems(config: pytest.Config, items: list[pytest.Item]) -> None:
+    """Apply the shared file plan, or the legacy round-robin testcase shard."""
+    shard_index = config.getoption("shard_index")
+    shard_total = config.getoption("shard_total")
+    if plan_path := config.getoption("file_shard_plan"):
+        import json
+
+        from dev.pytest_sharding import case_shard
+
+        plan = json.loads(plan_path.read_text())
+        selected_items: list[pytest.Item] = []
+        deselected_items: list[pytest.Item] = []
+        for item in items:
+            filename = item.path.relative_to(_REPO_ROOT).as_posix()
+            # Missing files are a broken plan, not an excuse to silently drop tests.
+            targets = plan[filename]
+            case = item.nodeid.split("::", 1)[1]
+            destination = selected_items if case_shard(case, targets) == shard_index else deselected_items
+            destination.append(item)
+        config.hook.pytest_deselected(items=deselected_items)
+        items[:] = selected_items
+        return
+    if shard_total == 1:
+        return
+
+    selected: list[pytest.Item] = []
+    deselected: list[pytest.Item] = []
+    for item_index, item in enumerate(items):
+        target = selected if item_index % shard_total == shard_index - 1 else deselected
+        target.append(item)
+
+    config.hook.pytest_deselected(items=deselected)
+    items[:] = selected
+
+
 def pytest_sessionstart(session: pytest.Session) -> None:
     config = session.config
     if hasattr(config, "workerinput"):
@@ -70,6 +142,10 @@ def pytest_sessionstart(session: pytest.Session) -> None:
     if config.getoption("start_middleware"):
         ensure_compose_env_files(_REPO_ROOT)
         stack = build_middleware_stack(_REPO_ROOT, parse_services(config.getoption("middleware_services")))
+        stack = replace(
+            stack,
+            shutdown_timeout_seconds=config.getoption("middleware_stop_timeout"),
+        )
         stack.up()
         stacks.append(stack)
 

api/constants/__init__.py

@@ -79,3 +79,4 @@ COOKIE_NAME_PASSPORT = "passport"
 HEADER_NAME_CSRF_TOKEN = "X-CSRF-Token"
 HEADER_NAME_APP_CODE = "X-App-Code"
 HEADER_NAME_PASSPORT = "X-App-Passport"
+HEADER_NAME_CATALOG = "X-Dify-Catalog"

api/constants/languages.py

@@ -8,6 +8,7 @@ language_timezone_mapping = {
     "de-DE": "Europe/Berlin",
     "ja-JP": "Asia/Tokyo",
     "ko-KR": "Asia/Seoul",
+    "lo-LA": "Asia/Vientiane",
     "ru-RU": "Europe/Moscow",
     "it-IT": "Europe/Rome",
     "uk-UA": "Europe/Kyiv",
@@ -22,6 +23,7 @@ language_timezone_mapping = {
     "id-ID": "Asia/Jakarta",
     "ar-TN": "Africa/Tunis",
     "nl-NL": "Europe/Amsterdam",
+    "az-AZ": "Asia/Baku",
 }
 
 languages = list(language_timezone_mapping.keys())

api/controllers/API_SCHEMA_GUIDE.md

@@ -239,12 +239,12 @@ to the legacy area and avoid importing RESTX model objects from controllers.
 
 ## Verifying Swagger
 
-For schema and documentation changes, run focused tests and generate Swagger JSON:
+For schema and documentation changes, run focused tests and generate Swagger JSON from the repository root:
 
 ```bash
-uv run --project . pytest tests/unit_tests/controllers/common/test_schema.py
-uv run --project . pytest tests/unit_tests/commands/test_generate_swagger_specs.py tests/unit_tests/controllers/test_swagger.py
-uv run --project . dev/generate_swagger_specs.py --output-dir /tmp/dify-openapi-check
+uv run --project api pytest api/tests/unit_tests/controllers/common/test_schema.py
+uv run --project api pytest api/tests/unit_tests/commands/test_generate_swagger_specs.py api/tests/unit_tests/controllers/test_swagger.py
+uv run --project api python api/dev/generate_swagger_specs.py --output-dir /tmp/dify-openapi-check
 ```
 
 Inspect affected endpoints with `jq`. Check that:
@@ -253,3 +253,31 @@ Inspect affected endpoints with `jq`. Check that:
 - Request bodies appear only where the endpoint has a body.
 - Responses reference the expected `*Response` schema.
 - Response schemas use public serialized names, not internal validation aliases like `inputs_dict`.
+
+## Service API Documentation Handoff
+
+The `dify-docs` repository imports `service-openapi.json` for the `/v1` API. It keeps a pinned export and adds
+descriptions, examples, translations, and existing page URLs through documentation annotations. Fields, constraints,
+references, response statuses, and security come from this repository's export.
+
+Verify the public schema against request validation and response serialization, including intentional schema overrides
+and excluded fields. Fix an inaccurate contract here and regenerate it before updating the documentation snapshot.
+Record the full source commit SHA when handing off the export. For coordinated changes that are not committed yet,
+also provide the source patch used to produce it; replace that patch with a clean committed export after merging.
+
+The manual import, annotation review, build, and validation commands live in `tools/api-pipeline/README.md` in
+`dify-docs`. Regenerate this repository's OpenAPI Markdown and TypeScript/Zod contracts whenever their inputs change.
+
+## Catalog metadata on /openapi/v1
+
+Every `@endpoint` on `/openapi/v1` declares `op` (dotted lowercase id), `kind`
+(`object|list|sse|text|file`) and a one-line `summary`; they live on the route's
+`EndpointSpec`. `controllers/openapi/_catalog.py` derives the rest (input schema, bind,
+tags) from the route and its Pydantic models. Files are declared in the body model with
+`UploadPart`; never add a separate files decorator or parse `request.files` in a handler.
+Run ops are per app mode (`console_app.<mode>.run`), each a self-contained route with the exact
+body that mode takes.
+Next steps for the caller go in a `hints` field (see `_hints.py`); `hints` is reserved.
+Frozen after release: kind names, bind values, the pagination envelope, and any field the
+CLI's fold table reads from an SSE event. Breaking input changes get a new op id; the old
+one stays and is marked `deprecated=True`.

api/controllers/common/agent_access.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sqlalchemy.orm import Session
+
+from services.agent.roster_service import AgentRosterService
+from services.enterprise import rbac_service as enterprise_rbac_service
+
+if TYPE_CHECKING:
+    from services.app_service import AppListBaseParams
+    from services.enterprise.rbac_service import MyPermissionsResponse
+
+
+AGENT_LIST_PERMISSION_KEYS: frozenset[str] = frozenset({"agent.acl.preview"})
+
+
+def has_agent_list_permission(permission_keys: Sequence[str]) -> bool:
+    """Return whether the permission set makes an Agent visible in resource lists."""
+    return any(permission_key in AGENT_LIST_PERMISSION_KEYS for permission_key in permission_keys)
+
+
+@dataclass(frozen=True)
+class AgentAccessFilter:
+    """Resolved resource-level visibility for Agent list endpoints.
+
+    ``accessible_agent_ids`` of ``None`` means every Agent is visible. An
+    explicit set limits list queries to exactly those Agent resources.
+    """
+
+    accessible_agent_ids: set[str] | None
+
+    @classmethod
+    def unrestricted(cls) -> AgentAccessFilter:
+        return cls(accessible_agent_ids=None)
+
+    def apply_to_app_params(self, params: AppListBaseParams, *, tenant_id: str, session: Session) -> None:
+        """Translate visible Agent ids to their Agent App ids before pagination."""
+        if self.accessible_agent_ids is None:
+            return
+        if not self.accessible_agent_ids:
+            params.accessible_app_ids = []
+            return
+
+        params.accessible_app_ids = AgentRosterService(session).load_app_ids_for_agents(
+            tenant_id=tenant_id,
+            agent_ids=sorted(self.accessible_agent_ids),
+        )
+
+
+def resolve_agent_access_filter(
+    tenant_id: str,
+    account_id: str,
+    *,
+    session: Session,
+    permissions: MyPermissionsResponse | None = None,
+) -> AgentAccessFilter:
+    """Compute Agent resources visible to an account in a workspace."""
+    if permissions is None:
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+            tenant_id,
+            account_id,
+            session=session,
+        )
+    whitelist_scope = enterprise_rbac_service.RBACService.AgentAccess.whitelist_resources(tenant_id, account_id)
+    has_default_preview = has_agent_list_permission(
+        permissions.agent.default_permission_keys
+    ) or has_agent_list_permission(permissions.workspace.permission_keys)
+
+    permission_agent_ids: set[str] | None = None
+    if not has_default_preview:
+        permission_agent_ids = {
+            override.resource_id
+            for override in permissions.agent.overrides
+            if has_agent_list_permission(override.permission_keys)
+        }
+
+    if whitelist_scope.unrestricted:
+        accessible_agent_ids = permission_agent_ids
+    else:
+        accessible_agent_ids = set(whitelist_scope.resource_ids)
+
+    return AgentAccessFilter(accessible_agent_ids=accessible_agent_ids)

api/controllers/common/errors.py

@@ -1,18 +1,54 @@
-from werkzeug.exceptions import HTTPException
-
 from libs.exception import BaseHTTPException
 
 
-class FilenameNotExistsError(HTTPException):
+class FilenameNotExistsError(BaseHTTPException):
+    error_code = "filename_not_exists_error"
     code = 400
     description = "The specified filename does not exist."
 
 
-class RemoteFileUploadError(HTTPException):
+class RemoteFileUploadError(BaseHTTPException):
+    error_code = "remote_file_upload_error"
     code = 400
     description = "Error uploading remote file."
 
 
+class RemoteFileInvalidUrlError(BaseHTTPException):
+    error_code = "remote_file_invalid_url"
+    description = "The remote file URL is invalid."
+    code = 400
+
+
+class RemoteFileUrlBlockedError(BaseHTTPException):
+    error_code = "remote_file_url_blocked"
+    description = "The remote file URL is not allowed."
+    code = 400
+
+
+class RemoteFileNotFoundError(BaseHTTPException):
+    error_code = "remote_file_not_found"
+    description = "The remote file could not be found."
+    code = 404
+
+
+class RemoteFileAccessDeniedError(BaseHTTPException):
+    error_code = "remote_file_access_denied"
+    description = "The remote file cannot be accessed without authorization."
+    code = 400
+
+
+class RemoteFileUnavailableError(BaseHTTPException):
+    error_code = "remote_file_unavailable"
+    description = "The remote file is temporarily unavailable."
+    code = 502
+
+
+class RemoteFileInvalidResponseError(BaseHTTPException):
+    error_code = "remote_file_invalid_response"
+    description = "The remote file server returned an invalid response."
+    code = 502
+
+
 class FileTooLargeError(BaseHTTPException):
     error_code = "file_too_large"
     description = "File size exceeded. {message}"

api/controllers/common/helpers.py

@@ -1,39 +1,4 @@
-import contextlib
-import mimetypes
-import os
-import platform
-import re
 import urllib.parse
-import warnings
-from uuid import uuid4
-
-import httpx
-
-try:
-    import magic
-except ImportError:
-    if platform.system() == "Windows":
-        warnings.warn(
-            "To use python-magic guess MIMETYPE, you need to run `pip install python-magic-bin`", stacklevel=2
-        )
-    elif platform.system() == "Darwin":
-        warnings.warn("To use python-magic guess MIMETYPE, you need to run `brew install libmagic`", stacklevel=2)
-    elif platform.system() == "Linux":
-        warnings.warn(
-            "To use python-magic guess MIMETYPE, you need to run `sudo apt-get install libmagic1`", stacklevel=2
-        )
-    else:
-        warnings.warn("To use python-magic guess MIMETYPE, you need to install `libmagic`", stacklevel=2)
-    magic = None  # type: ignore[assignment]
-
-from pydantic import BaseModel
-
-
-class FileInfo(BaseModel):
-    filename: str
-    extension: str
-    mimetype: str
-    size: int
 
 
 def decode_remote_url(url: str, query_string: bytes | str = b"") -> str:
@@ -45,59 +10,15 @@ def decode_remote_url(url: str, query_string: bytes | str = b"") -> str:
     if not raw_query:
         return decoded_url
 
+    try:
+        has_query = bool(urllib.parse.urlsplit(decoded_url).query)
+    except ValueError:
+        has_query = False
+
     if decoded_url.endswith(("?", "&")):
         separator = ""
-    elif urllib.parse.urlsplit(decoded_url).query:
+    elif has_query:
         separator = "&"
     else:
         separator = "?"
     return f"{decoded_url}{separator}{raw_query}"
-
-
-def guess_file_info_from_response(response: httpx.Response):
-    url = str(response.url)
-    # Try to extract filename from URL
-    parsed_url = urllib.parse.urlparse(url)
-    url_path = parsed_url.path
-    # Decode percent-encoded characters in the path segment
-    filename = urllib.parse.unquote(os.path.basename(url_path))
-
-    # If filename couldn't be extracted, use Content-Disposition header
-    if not filename:
-        content_disposition = response.headers.get("Content-Disposition")
-        if content_disposition:
-            filename_match = re.search(r'filename="?(.+)"?', content_disposition)
-            if filename_match:
-                filename = filename_match.group(1)
-
-    # If still no filename, generate a unique one
-    if not filename:
-        unique_name = str(uuid4())
-        filename = f"{unique_name}"
-
-    # Guess MIME type from filename first, then URL
-    mimetype, _ = mimetypes.guess_type(filename)
-    if mimetype is None:
-        mimetype, _ = mimetypes.guess_type(url)
-    if mimetype is None:
-        # If guessing fails, use Content-Type from response headers
-        mimetype = response.headers.get("Content-Type", "application/octet-stream")
-
-    # Use python-magic to guess MIME type if still unknown or generic
-    if mimetype == "application/octet-stream" and magic is not None:
-        with contextlib.suppress(magic.MagicException):
-            mimetype = magic.from_buffer(response.content[:1024], mime=True)
-
-    extension = os.path.splitext(filename)[1]
-
-    # Ensure filename has an extension
-    if not extension:
-        extension = mimetypes.guess_extension(mimetype) or ".bin"
-        filename = f"{filename}{extension}"
-
-    return FileInfo(
-        filename=filename,
-        extension=extension,
-        mimetype=mimetype,
-        size=int(response.headers.get("Content-Length", -1)),
-    )

api/controllers/common/rbac/__init__.py

@@ -0,0 +1,29 @@
+from core.rbac import RBACPermission, RBACResourceScope
+
+from .checks import RBAC_CHECKS_ATTR, RBACCheck, enforce_rbac_checks
+from .locators import (
+    AgentBehindApp,
+    AgentId,
+    DatasetByPipeline,
+    DatasetId,
+    PlainApp,
+    ResourceIdentity,
+    ResourceLocator,
+    Workspace,
+)
+
+__all__ = [
+    "RBAC_CHECKS_ATTR",
+    "AgentBehindApp",
+    "AgentId",
+    "DatasetByPipeline",
+    "DatasetId",
+    "PlainApp",
+    "RBACCheck",
+    "RBACPermission",
+    "RBACResourceScope",
+    "ResourceIdentity",
+    "ResourceLocator",
+    "Workspace",
+    "enforce_rbac_checks",
+]

api/controllers/common/rbac/checks.py

@@ -0,0 +1,65 @@
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+from flask import request
+from werkzeug.exceptions import Forbidden, NotFound
+
+from configs import dify_config
+from core.rbac import RBACPermission, RBACResourceScope
+from services.enterprise.rbac_service import RBACService
+
+from .locators import ResourceLocator, Workspace
+
+__all__ = ["RBAC_CHECKS_ATTR", "RBACCheck", "enforce_rbac_checks"]
+
+RBAC_CHECKS_ATTR = "rbac_checks"
+
+
+@dataclass(frozen=True)
+class RBACCheck:
+    scene: RBACPermission
+    locator: ResourceLocator
+
+    def __post_init__(self) -> None:
+        if isinstance(self.locator, Workspace) or self.scene.scope is RBACResourceScope.WORKSPACE:
+            return
+        if self.locator.scope is not self.scene.scope:
+            raise ValueError(
+                f"{self.scene} is a {self.scene.scope} scene but {self.locator!r} locates {self.locator.scope}"
+            )
+
+
+def enforce_rbac_checks(
+    *,
+    tenant_id: str,
+    account_id: str,
+    checks: Sequence[RBACCheck],
+    path_args: Mapping[str, object] | None = None,
+) -> None:
+    if not dify_config.RBAC_ENABLED:
+        return
+    try:
+        view_args = request.view_args or {}
+    except RuntimeError:
+        view_args = {}
+    merged: dict[str, object] = {**view_args, **(path_args or {})}
+    applicable = [
+        (check, identity) for check in checks if (identity := check.locator.locate(tenant_id, merged)) is not None
+    ]
+    if not applicable:
+        raise NotFound()
+    for check, identity in applicable:
+        is_workspace = identity.scope is RBACResourceScope.WORKSPACE
+        owner = None if is_workspace else check.locator.owner_id(tenant_id, identity)
+        if owner is not None and owner == account_id:
+            return
+        allowed = RBACService.CheckAccess.check(
+            tenant_id,
+            account_id,
+            scene=check.scene,
+            resource_type=None if is_workspace else identity.scope,
+            resource_id=None if is_workspace else identity.id,
+        )
+        if allowed:
+            return
+    raise Forbidden()

api/controllers/common/rbac/locators.py

@@ -0,0 +1,145 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, override, runtime_checkable
+
+from flask import g
+from werkzeug.exceptions import NotFound
+
+from core.rbac import RBACResourceScope
+from extensions.ext_database import db
+from services.rbac_resource_service import RBACResourceService
+
+if TYPE_CHECKING:
+    from models.agent import Agent
+
+__all__ = [
+    "AgentBehindApp",
+    "AgentId",
+    "DatasetByPipeline",
+    "DatasetId",
+    "PlainApp",
+    "ResourceIdentity",
+    "ResourceLocator",
+    "Workspace",
+    "agent_binding",
+]
+
+_AGENT_BINDING_CACHE_KEY = "_rbac_agent_bindings"
+
+
+@dataclass(frozen=True)
+class ResourceIdentity:
+    scope: RBACResourceScope
+    id: str
+
+
+@runtime_checkable
+class ResourceLocator(Protocol):
+    scope: RBACResourceScope
+
+    def locate(self, tenant_id: str, path_args: Mapping[str, object]) -> ResourceIdentity | None: ...
+
+    def owner_id(self, tenant_id: str, identity: ResourceIdentity) -> str | None: ...
+
+
+def _required(path_args: Mapping[str, object], param: str) -> str:
+    value = path_args.get(param)
+    if not value:
+        raise ValueError(f"Missing {param} in request path")
+    return str(value)
+
+
+def agent_binding(tenant_id: str, app_id: str) -> "Agent | None":
+    cache: dict[tuple[str, str], Agent | None] = g.setdefault(_AGENT_BINDING_CACHE_KEY, {})
+    key = (tenant_id, app_id)
+    if key not in cache:
+        cache[key] = RBACResourceService.get_app_agent_binding(db.session, tenant_id, app_id)
+    return cache[key]
+
+
+class Workspace:
+    scope = RBACResourceScope.WORKSPACE
+
+    def locate(self, tenant_id: str, path_args: Mapping[str, object]) -> ResourceIdentity | None:
+        return ResourceIdentity(self.scope, "")
+
+    def owner_id(self, tenant_id: str, identity: ResourceIdentity) -> str | None:
+        return None
+
+    def __repr__(self) -> str:
+        return "Workspace()"
+
+
+class _ParamLocator:
+    scope: RBACResourceScope
+    default_param: str
+
+    def __init__(self, param: str | None = None):
+        self.param = param or self.default_param
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.param!r})"
+
+
+class AgentId(_ParamLocator):
+    scope = RBACResourceScope.AGENT
+    default_param = "agent_id"
+
+    def locate(self, tenant_id: str, path_args: Mapping[str, object]) -> ResourceIdentity | None:
+        return ResourceIdentity(self.scope, _required(path_args, self.param))
+
+    def owner_id(self, tenant_id: str, identity: ResourceIdentity) -> str | None:
+        return None
+
+
+class PlainApp(_ParamLocator):
+    scope = RBACResourceScope.APP
+    default_param = "app_id"
+
+    def locate(self, tenant_id: str, path_args: Mapping[str, object]) -> ResourceIdentity | None:
+        app_id = _required(path_args, self.param)
+        if agent_binding(tenant_id, app_id) is not None:
+            return None
+        return ResourceIdentity(self.scope, app_id)
+
+    def owner_id(self, tenant_id: str, identity: ResourceIdentity) -> str | None:
+        return RBACResourceService.get_app_maintainer(db.session, tenant_id, identity.id)
+
+
+class AgentBehindApp(_ParamLocator):
+    scope = RBACResourceScope.AGENT
+    default_param = "app_id"
+
+    def locate(self, tenant_id: str, path_args: Mapping[str, object]) -> ResourceIdentity | None:
+        from models.agent import AgentScope
+
+        binding = agent_binding(tenant_id, _required(path_args, self.param))
+        if binding is None or binding.scope == AgentScope.WORKFLOW_ONLY:
+            return None
+        return ResourceIdentity(self.scope, str(binding.id))
+
+    def owner_id(self, tenant_id: str, identity: ResourceIdentity) -> str | None:
+        return None
+
+
+class DatasetId(_ParamLocator):
+    scope = RBACResourceScope.DATASET
+    default_param = "dataset_id"
+
+    def locate(self, tenant_id: str, path_args: Mapping[str, object]) -> ResourceIdentity | None:
+        return ResourceIdentity(self.scope, _required(path_args, self.param))
+
+    def owner_id(self, tenant_id: str, identity: ResourceIdentity) -> str | None:
+        return RBACResourceService.get_dataset_maintainer(db.session, tenant_id, identity.id)
+
+
+class DatasetByPipeline(DatasetId):
+    default_param = "pipeline_id"
+
+    @override
+    def locate(self, tenant_id: str, path_args: Mapping[str, object]) -> ResourceIdentity | None:
+        pipeline_id = _required(path_args, self.param)
+        dataset_id = RBACResourceService.get_dataset_id_by_pipeline(db.session, tenant_id, pipeline_id)
+        if dataset_id is None:
+            raise NotFound("Dataset not found for pipeline")
+        return ResourceIdentity(self.scope, dataset_id)

api/controllers/common/wraps.py

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

api/controllers/console/__init__.py

@@ -1,5 +1,7 @@
+from collections import OrderedDict
 from http import HTTPStatus
 from importlib import import_module
+from typing import cast
 
 from flask import Blueprint, current_app, got_request_exception
 from flask_restx import Namespace
@@ -29,6 +31,11 @@ def _handle_active_workspace_required_error(error: ActiveWorkspaceRequiredError)
     }, status.value
 
 
+# Flask-RESTX dispatches in registration order; the shared Exception handler
+# must not shadow this Console-specific error mapping.
+cast(OrderedDict[type[Exception], object], api.error_handlers).move_to_end(ActiveWorkspaceRequiredError, last=False)
+
+
 console_ns = Namespace("console", description="Console management API operations", path="/")
 
 RESOURCE_MODULES = (

api/controllers/console/agent/app_helpers.py

@@ -19,3 +19,8 @@ def resolve_agent_runtime_app_model(*, session: Session, tenant_id: str, agent_i
     """
 
     return AgentRosterService(session).get_agent_runtime_app_model(tenant_id=tenant_id, agent_id=str(agent_id))
+
+
+def resolve_existing_agent_runtime_app_model(*, session: Session, tenant_id: str, agent_id: UUID) -> App:
+    """Resolve persisted runtime state for read-only Agent endpoints."""
+    return AgentRosterService(session).get_existing_agent_runtime_app_model(tenant_id=tenant_id, agent_id=str(agent_id))

api/controllers/console/agent/composer.py

@@ -4,13 +4,13 @@ from flask_restx import Resource
 from sqlalchemy.orm import Session
 from werkzeug.exceptions import NotFound
 
+from controllers.common.rbac import AgentId, PlainApp, RBACCheck, Workspace
 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 agent_manage_required_for_agent_app, get_app_model
+from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
     model_validate,
@@ -94,7 +94,7 @@ class WorkflowAgentComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -134,7 +134,7 @@ class WorkflowAgentComposerCopyFromRosterApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -246,8 +246,8 @@ class WorkflowAgentComposerSaveToRosterApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_CREATE, Workspace()))
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -323,9 +323,7 @@ class SnippetAgentComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(
-        RBACResourceScope.WORKSPACE, RBACPermission.SNIPPETS_CREATE_AND_MODIFY, resource_required=False
-    )
+    @rbac_permission_required(RBACCheck(RBACPermission.SNIPPETS_CREATE_AND_MODIFY, Workspace()))
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -362,9 +360,7 @@ class SnippetAgentComposerCopyFromRosterApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(
-        RBACResourceScope.WORKSPACE, RBACPermission.SNIPPETS_CREATE_AND_MODIFY, resource_required=False
-    )
+    @rbac_permission_required(RBACCheck(RBACPermission.SNIPPETS_CREATE_AND_MODIFY, Workspace()))
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -476,10 +472,8 @@ class SnippetAgentComposerSaveToRosterApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(
-        RBACResourceScope.WORKSPACE, RBACPermission.SNIPPETS_CREATE_AND_MODIFY, resource_required=False
-    )
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.SNIPPETS_CREATE_AND_MODIFY, Workspace()))
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_CREATE, Workspace()))
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -512,9 +506,9 @@ class AgentComposerApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_tenant_id
-    @with_session
+    @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID):
         return dump_response(
             AgentAppComposerResponse,
@@ -527,7 +521,7 @@ class AgentComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -554,8 +548,9 @@ class AgentComposerValidateApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_tenant_id
-    @with_session
+    @with_session(write=False)
     @model_validate(ComposerSavePayload)
     def post(self, req_data: ComposerSavePayload, session: Session, tenant_id: str, agent_id: UUID):
         AgentComposerService.load_agent_composer(session=session, tenant_id=tenant_id, agent_id=str(agent_id))
@@ -575,6 +570,7 @@ class AgentComposerCandidatesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user_id
     @with_current_tenant_id
     @with_session(write=False)

api/controllers/console/agent/roster.py

@@ -7,6 +7,9 @@ from pydantic import AliasChoices, BaseModel, Field, field_validator
 from sqlalchemy import func, or_, select
 from sqlalchemy.orm import Session
 
+from configs import dify_config
+from controllers.common.agent_access import resolve_agent_access_filter
+from controllers.common.rbac import AgentId, RBACCheck, Workspace
 from controllers.common.schema import (
     query_params_from_model,
     query_params_from_request,
@@ -32,10 +35,8 @@ from controllers.console.app.app import (
 from controllers.console.app.app import (
     UpdateAppPayload as GenericUpdateAppPayload,
 )
-from controllers.console.app.wraps import agent_manage_required_for_agent_app
 from controllers.console.wraps import (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
     enterprise_license_required,
@@ -47,6 +48,7 @@ from controllers.console.wraps import (
     with_current_user,
 )
 from core.agent.publish_visibility import agent_has_workflow_callable_active_snapshot
+from enums import DeploymentEdition
 from fields.agent_fields import (
     AgentConfigDraftSummaryResponse,
     AgentConfigSnapshotDetailResponse,
@@ -79,8 +81,10 @@ from services.agent.observability_service import (
 )
 from services.agent.roster_service import AgentRosterService
 from services.app_service import AgentAppPublicationCounts, AppListParams, AppService, CreateAppParams
+from services.enterprise import rbac_service as enterprise_rbac_service
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.agent_entities import ComposerSavePayload, RosterListQuery
+from services.feature_service import FeatureService
 from services.system_feature_service import SystemFeatureService
 
 AgentPublicationStatus = Literal["published", "drafts"]
@@ -252,6 +256,7 @@ class AgentStatisticsQuery(BaseModel):
 
 
 class AgentAppPartial(GenericAppPartial):
+    permission_keys: list[str]
     app_id: str | None = None
     backing_app_id: str | None = None
     hidden_app_backed: bool = False
@@ -264,6 +269,7 @@ class AgentAppPartial(GenericAppPartial):
 
 
 class AgentAppDetailWithSite(GenericAppDetailWithSite):
+    permission_keys: list[str]
     app_id: str | None = None
     backing_app_id: str | None = None
     hidden_app_backed: bool = False
@@ -393,7 +399,7 @@ def _serialize_agent_app_detail(
         app_model.access_mode = app_setting.access_mode  # type: ignore[attr-defined]
 
     roster_service = _agent_roster_service(session)
-    payload = AgentAppDetailWithSite.model_validate(
+    payload = GenericAppDetailWithSite.model_validate(
         app_model,
         from_attributes=True,
         context={"session": session},
@@ -430,7 +436,14 @@ def _serialize_agent_app_detail(
     payload["debug_conversation_message_count"] = message_count
     payload["role"] = agent.role or ""
     payload["access_ready"] = agent_has_workflow_callable_active_snapshot(session=session, agent=agent)
-    return payload
+    permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+        app_model.tenant_id,
+        current_user.id,
+        agent_id=agent.id,
+        session=session,
+    )
+    payload["permission_keys"] = permissions.agent.permission_keys_by_resource_ids([agent.id]).get(agent.id, [])
+    return AgentAppDetailWithSite.model_validate(payload).model_dump(mode="json", exclude={"bound_agent_id"})
 
 
 def _serialize_agent_app_pagination(
@@ -440,6 +453,7 @@ def _serialize_agent_app_pagination(
     tenant_id: str,
     current_user: Account,
     publication_counts: AgentAppPublicationCounts,
+    agent_permissions: enterprise_rbac_service.ResourcePermissionSnapshot,
 ) -> dict:
     """Serialize Agent App lists with roster-shaped items.
 
@@ -472,20 +486,23 @@ def _serialize_agent_app_pagination(
         agents=list(agents_by_app_id.values()),
         account_id=current_user.id,
     )
-    payload = AgentAppPagination.model_validate(
+    permission_keys_by_agent_id = agent_permissions.permission_keys_by_resource_ids(
+        [agent.id for agent in agents_by_app_id.values()]
+    )
+    payload = GenericAppPagination.model_validate(
         {
             "page": app_pagination.page,
             "limit": app_pagination.per_page,
             "total": app_pagination.total,
             "has_more": app_pagination.has_next,
             "data": app_pagination.items,
-            "publication_counts": {
-                "published": publication_counts.published,
-                "drafts": publication_counts.drafts,
-            },
         },
         context={"session": session},
     ).model_dump(mode="json")
+    payload["publication_counts"] = {
+        "published": publication_counts.published,
+        "drafts": publication_counts.drafts,
+    }
     for item in payload["data"]:
         app_id = item["id"]
         item.pop("bound_agent_id", None)
@@ -496,6 +513,7 @@ def _serialize_agent_app_pagination(
             item["hidden_app_backed"] = False
             item["id"] = agent.id
             item["debug_conversation_id"] = debug_conversation_ids_by_agent_id.get(agent.id)
+            item["permission_keys"] = permission_keys_by_agent_id.get(str(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)
@@ -608,7 +626,6 @@ class AgentAppListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -629,6 +646,20 @@ class AgentAppListApi(Resource):
             agent_is_published=agent_is_published,
         )
 
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+            current_tenant_id,
+            current_user.id,
+            session=session,
+        )
+        if dify_config.RBAC_ENABLED:
+            access_filter = resolve_agent_access_filter(
+                current_tenant_id,
+                current_user.id,
+                session=session,
+                permissions=permissions,
+            )
+            access_filter.apply_to_app_params(params, tenant_id=current_tenant_id, session=session)
+
         app_service = AppService()
         publication_counts = app_service.get_agent_publication_counts(
             current_user.id,
@@ -657,6 +688,7 @@ class AgentAppListApi(Resource):
             tenant_id=current_tenant_id,
             current_user=current_user,
             publication_counts=publication_counts,
+            agent_permissions=permissions.agent,
         )
 
     @console_ns.expect(console_ns.models[AgentAppCreatePayload.__name__])
@@ -668,7 +700,7 @@ class AgentAppListApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_CREATE, Workspace()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -694,7 +726,7 @@ class AgentAppApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @enterprise_license_required
     @with_current_user
     @with_current_tenant_id
@@ -711,7 +743,7 @@ class AgentAppApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -744,7 +776,7 @@ class AgentAppApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_DELETE, AgentId()))
     @with_current_tenant_id
     @with_session
     def delete(self, session: Session, tenant_id: str, agent_id: UUID):
@@ -765,6 +797,7 @@ class AgentDebugConversationRefreshApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_TEST_AND_RUN, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -790,7 +823,7 @@ class AgentPublishApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_RELEASE_AND_VERSION, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -820,7 +853,7 @@ class AgentBuildDraftCheckoutApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -850,6 +883,7 @@ class AgentBuildDraftApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -867,6 +901,7 @@ class AgentBuildDraftApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -892,6 +927,7 @@ class AgentBuildDraftApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -911,7 +947,7 @@ class AgentBuildDraftApplyApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -934,7 +970,8 @@ class AgentAppCopyApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_CREATE, Workspace()))
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -967,7 +1004,7 @@ class AgentApiAccessApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_ACCESS_POINT_VIEW, AgentId()))
     @with_current_tenant_id
     @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID):
@@ -984,7 +1021,7 @@ class AgentApiStatusApi(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_RELEASE_AND_VERSION)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentId()))
     @with_current_tenant_id
     @with_session
     @model_validate(AgentApiStatusPayload)
@@ -1002,7 +1039,7 @@ class AgentApiKeyListApi(BaseApiKeyListResource):
     token_prefix = "app-"
 
     @console_ns.response(200, "Agent service API keys", console_ns.models[ApiKeyList.__name__])
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_RELEASE_AND_VERSION)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_ACCESS_POINT_VIEW, AgentId()))
     @with_current_tenant_id
     @edit_permission_required
     @with_session(write=False)
@@ -1014,7 +1051,7 @@ class AgentApiKeyListApi(BaseApiKeyListResource):
     @console_ns.response(400, "Maximum keys exceeded")
     @with_current_tenant_id
     @edit_permission_required
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_RELEASE_AND_VERSION)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentId()))
     @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)
@@ -1033,7 +1070,7 @@ class AgentApiKeyApi(BaseApiKeyResource):
     @console_ns.response(204, "Agent service API key deleted")
     @with_current_user
     @with_current_tenant_id
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_RELEASE_AND_VERSION)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentId()))
     @with_session
     def delete(
         self,
@@ -1055,10 +1092,33 @@ class AgentInviteOptionsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
     @model_validate(AgentInviteOptionsQuery)
-    def get(self, req_data: AgentInviteOptionsQuery, session: Session, tenant_id: str):
+    def get(
+        self,
+        req_data: AgentInviteOptionsQuery,
+        session: Session,
+        tenant_id: str,
+        current_user: Account,
+    ):
+        accessible_agent_ids = None
+        if dify_config.RBAC_ENABLED:
+            permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+                tenant_id,
+                current_user.id,
+                session=session,
+            )
+            access_filter = resolve_agent_access_filter(
+                tenant_id,
+                current_user.id,
+                session=session,
+                permissions=permissions,
+            )
+            if access_filter.accessible_agent_ids is not None:
+                accessible_agent_ids = sorted(access_filter.accessible_agent_ids)
+
         return dump_response(
             AgentInviteOptionsResponse,
             _agent_roster_service(session).list_invite_options(
@@ -1067,6 +1127,7 @@ class AgentInviteOptionsApi(Resource):
                 limit=req_data.limit,
                 keyword=req_data.keyword,
                 app_id=req_data.app_id,
+                accessible_agent_ids=accessible_agent_ids,
             ),
         )
 
@@ -1078,7 +1139,7 @@ class AgentLogsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_LOG_MANAGE, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -1117,7 +1178,7 @@ class AgentLogMessagesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_LOG_MANAGE, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -1156,7 +1217,7 @@ class AgentLogSourcesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_LOG_MANAGE, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -1177,7 +1238,7 @@ class AgentStatisticsSummaryApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_MONITOR, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -1210,7 +1271,7 @@ class AgentRosterVersionsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_RELEASE_AND_VERSION, AgentId()))
     @with_current_tenant_id
     @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID):
@@ -1226,7 +1287,7 @@ class AgentRosterVersionDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_RELEASE_AND_VERSION, AgentId()))
     @with_current_tenant_id
     @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID, version_id: UUID):
@@ -1247,11 +1308,17 @@ class AgentRosterVersionRestoreApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_RELEASE_AND_VERSION, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
     def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID, version_id: UUID):
+        if (
+            dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD
+            and not FeatureService.get_workspace_plan(tenant_id).is_paid
+        ):
+            abort(403, description="This feature requires a paid plan.")
+
         return dump_response(
             AgentConfigSnapshotRestoreResponse,
             _agent_roster_service(session).restore_agent_version(

api/controllers/console/apikey.py

@@ -11,9 +11,9 @@ from sqlalchemy.orm import Session
 from werkzeug.exceptions import Forbidden
 
 from configs import dify_config
+from controllers.common.rbac import AgentBehindApp, DatasetId, PlainApp, RBACCheck
 from controllers.common.schema import register_response_schema_models
 from controllers.common.session import with_session
-from controllers.console.app.wraps import agent_manage_required_for_agent_app
 from fields.base import ResponseModel
 from libs.helper import dump_response, to_timestamp
 from libs.login import login_required
@@ -27,7 +27,6 @@ from services.app_service import AppService
 from . import console_ns
 from .wraps import (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
     rbac_permission_required,
@@ -242,8 +241,10 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
     @with_current_tenant_id
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_RELEASE_AND_VERSION, PlainApp("resource_id")),
+        RBACCheck(RBACPermission.AGENT_ACCESS_POINT_VIEW, AgentBehindApp("resource_id")),
+    )
     @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"""
@@ -259,8 +260,10 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.response(400, "Maximum keys exceeded")
     @with_current_tenant_id
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_RELEASE_AND_VERSION, PlainApp("resource_id")),
+        RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentBehindApp("resource_id")),
+    )
     @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"""
@@ -283,8 +286,10 @@ class AppApiKeyResource(BaseApiKeyResource):
     @console_ns.response(204, "API key deleted successfully")
     @with_current_user
     @with_current_tenant_id
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_RELEASE_AND_VERSION, PlainApp("resource_id")),
+        RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentBehindApp("resource_id")),
+    )
     @with_session
     def delete(
         self,
@@ -321,7 +326,7 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
     @with_current_tenant_id
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_API_KEY_MANAGE)
+    @rbac_permission_required(RBACCheck(RBACPermission.DATASET_API_KEY_MANAGE, DatasetId("resource_id")))
     @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"""
@@ -337,7 +342,7 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.response(400, "Maximum keys exceeded")
     @with_current_tenant_id
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_API_KEY_MANAGE)
+    @rbac_permission_required(RBACCheck(RBACPermission.DATASET_API_KEY_MANAGE, DatasetId("resource_id")))
     @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"""
@@ -360,7 +365,7 @@ class DatasetApiKeyResource(BaseApiKeyResource):
     @console_ns.response(204, "API key deleted successfully")
     @with_current_user
     @with_current_tenant_id
-    @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_API_KEY_MANAGE)
+    @rbac_permission_required(RBACCheck(RBACPermission.DATASET_API_KEY_MANAGE, DatasetId("resource_id")))
     @with_session
     def delete(
         self,

api/controllers/console/app/agent.py

@@ -4,13 +4,13 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy.orm import Session
 
+from controllers.common.rbac import PlainApp, RBACCheck
 from controllers.common.schema import query_params_from_model, register_response_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 (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     model_validate,
     rbac_permission_required,
@@ -84,7 +84,7 @@ class AgentLogApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @with_session(write=False)
     @get_app_model(mode=[AppMode.AGENT_CHAT])
     @model_validate(AgentLogQuery)

api/controllers/console/app/agent_app_access.py

@@ -11,11 +11,18 @@ from flask_restx import Resource
 from pydantic import Field
 from sqlalchemy.orm import Session
 
+from controllers.common.rbac import AgentId, RBACCheck
 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 controllers.console.wraps import (
+    RBACPermission,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+    with_current_tenant_id,
+)
 from fields.base import ResponseModel
 from libs.login import login_required
 from services.agent.roster_service import AgentRosterService
@@ -55,6 +62,7 @@ class AgentAppReferencingWorkflowsResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_tenant_id
     @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID):

api/controllers/console/app/agent_app_feature.py

@@ -16,13 +16,13 @@ from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
 from controllers.common.fields import SimpleResultResponse
+from controllers.common.rbac import AgentId, RBACCheck
 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 (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
     model_validate,
@@ -83,7 +83,7 @@ class AgentAppFeatureConfigResource(Resource):
     @setup_required
     @login_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @account_initialization_required
     @with_current_user
     @with_current_tenant_id

api/controllers/console/app/agent_app_sandbox.py

@@ -15,6 +15,7 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field
 
 from clients.agent_backend.errors import backend_error_detail, backend_reported_failure
+from controllers.common.rbac import AgentId, PlainApp, RBACCheck
 from controllers.common.schema import (
     query_params_from_model,
     query_params_from_request,
@@ -23,10 +24,9 @@ from controllers.common.schema import (
 )
 from controllers.console import console_ns
 from controllers.console.app.error import AppNotFoundError
-from controllers.console.app.wraps import agent_manage_required_for_agent_app, get_app_model
+from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     model_validate,
     rbac_permission_required,
@@ -153,7 +153,7 @@ class AgentAppSandboxInfoResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_tenant_id
     @with_current_user
     def get(self, current_user: Account, tenant_id: str, agent_id: UUID):
@@ -183,7 +183,7 @@ class AgentAppSandboxListResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_tenant_id
     @with_current_user
     def get(self, current_user: Account, tenant_id: str, agent_id: UUID):
@@ -214,7 +214,7 @@ class AgentAppSandboxReadResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_tenant_id
     @with_current_user
     def get(self, current_user: Account, tenant_id: str, agent_id: UUID):
@@ -245,7 +245,7 @@ class AgentAppSandboxDownloadResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_tenant_id
     @with_current_user
     @model_validate(AgentSandboxDownloadPayload)
@@ -289,7 +289,7 @@ class WorkflowAgentSandboxListResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @with_current_tenant_id
     def get(self, tenant_id: str, app_model: App, workflow_run_id: UUID, node_id: str):
@@ -327,7 +327,7 @@ class WorkflowAgentSandboxReadResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @with_current_tenant_id
     def get(self, tenant_id: str, app_model: App, workflow_run_id: UUID, node_id: str):
@@ -358,7 +358,7 @@ class WorkflowAgentSandboxDownloadResource(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @with_current_user
     @with_current_tenant_id
     @model_validate(WorkflowAgentSandboxDownloadPayload)

api/controllers/console/app/agent_config_inspector.py

@@ -15,6 +15,7 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
+from controllers.common.rbac import AgentId, PlainApp, RBACCheck
 from controllers.common.schema import (
     query_params_from_model,
     query_params_from_request,
@@ -27,7 +28,6 @@ from controllers.console.agent.app_helpers import resolve_agent_runtime_app_mode
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
     model_validate,
@@ -285,6 +285,7 @@ def _resolve_console_version(
     account_id: str,
     version_id: str | None,
     draft_type: str | None,
+    for_write: bool = False,
 ) -> tuple[str, AgentConfigVersionKind]:
     if version_id:
         return version_id, AgentConfigVersionKind.SNAPSHOT
@@ -301,15 +302,27 @@ def _resolve_console_version(
             if isinstance(draft_id, str) and draft_id:
                 return draft_id, AgentConfigVersionKind.BUILD_DRAFT
         else:
+            if for_write:
+                prepared_draft = AgentComposerService.prepare_agent_composer_draft(
+                    session=session, tenant_id=tenant_id, agent_id=agent_id, account_id=account_id
+                )
+                # Asset services open an independent session for the mutation.
+                draft_id = prepared_draft.id
+                session.commit()
+                return draft_id, AgentConfigVersionKind.DRAFT
             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.
-                session.commit()
+            snapshot_id = (state.get("active_config_snapshot") or {}).get("id")
+            stale_inline_draft = (
+                (state.get("agent") or {}).get("scope") == "workflow_only"
+                and isinstance(snapshot_id, str)
+                and draft.get("base_snapshot_id") != snapshot_id
+            )
+            if isinstance(draft_id, str) and draft_id and not stale_inline_draft:
                 return draft_id, AgentConfigVersionKind.DRAFT
+            if isinstance(snapshot_id, str) and snapshot_id:
+                return snapshot_id, AgentConfigVersionKind.SNAPSHOT
     except AgentVersionNotFoundError as exc:
         raise AgentConfigServiceError(
             "config_version_not_found",
@@ -339,6 +352,7 @@ def _resolve_target(
         account_id=account_id,
         version_id=version_id,
         draft_type=draft_type,
+        for_write=request.method in {"POST", "PUT", "PATCH", "DELETE"},
     )
     return _ResolvedConsoleTarget(
         tenant_id=tenant_id,
@@ -659,6 +673,7 @@ class AgentConfigManifestByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -704,6 +719,7 @@ class AgentConfigSkillUploadByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -733,7 +749,7 @@ class AgentConfigSkillUploadApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_current_user
     @with_session
     @get_app_model(mode=_WORKFLOW_APP_MODES)
@@ -751,6 +767,7 @@ class AgentConfigSkillsByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -789,6 +806,7 @@ class AgentConfigFilesByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -808,6 +826,7 @@ class AgentConfigFilesByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -853,7 +872,7 @@ class AgentConfigFilesApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_current_user
     @with_session
     @get_app_model(mode=_WORKFLOW_APP_MODES)
@@ -877,6 +896,7 @@ class AgentConfigSkillInspectByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -928,6 +948,7 @@ class AgentConfigSkillFilePreviewByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -988,6 +1009,7 @@ class AgentConfigSkillDownloadByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -1037,6 +1059,7 @@ class AgentConfigSkillFileDownloadByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -1106,6 +1129,7 @@ class AgentConfigSkillFileDownloadContentByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -1158,6 +1182,7 @@ class AgentConfigSkillByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -1182,7 +1207,7 @@ class AgentConfigSkillApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_current_user
     @with_session
     @get_app_model(mode=_WORKFLOW_APP_MODES)
@@ -1205,6 +1230,7 @@ class AgentConfigFilePreviewByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -1250,6 +1276,7 @@ class AgentConfigFileDownloadByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_PREVIEW, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -1295,6 +1322,7 @@ class AgentConfigFileByAgentApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_EDIT, AgentId()))
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -1319,7 +1347,7 @@ class AgentConfigFileApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_current_user
     @with_session
     @get_app_model(mode=_WORKFLOW_APP_MODES)

api/controllers/console/app/annotation.py

@@ -9,12 +9,12 @@ from sqlalchemy.orm import Session
 from werkzeug.exceptions import NotFound
 
 from controllers.common.errors import NoFileUploadedError, TooManyFilesError
+from controllers.common.rbac import PlainApp, RBACCheck
 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,
-    RBACResourceScope,
     account_initialization_required,
     annotation_import_concurrency_limit,
     annotation_import_rate_limit,
@@ -37,6 +37,7 @@ from fields.annotation_fields import (
 from fields.base import ResponseModel
 from libs.helper import dump_response, uuid_value
 from libs.login import current_account_with_tenant, login_required
+from libs.pagination import clamp_pagination
 from models.model import App
 from services.annotation_service import (
     AppAnnotationService,
@@ -180,7 +181,7 @@ class AnnotationReplyActionApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @model_validate(AnnotationReplyPayload)
     def post(self, req_data: AnnotationReplyPayload, app_id: UUID, action: Literal["enable", "disable"]):
         match action:
@@ -211,7 +212,7 @@ class AppAnnotationSettingDetailApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @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)
@@ -230,7 +231,7 @@ class AppAnnotationSettingUpdateApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_session
     @model_validate(AnnotationSettingUpdatePayload)
     def post(
@@ -263,7 +264,7 @@ class AnnotationReplyActionStatusApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     def get(self, app_id: UUID, job_id: UUID, action: str):
         job_id_str = str(job_id)
         app_annotation_job_key = f"{action}_app_annotation_job_{job_id_str}"
@@ -294,20 +295,25 @@ class AnnotationApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @with_session(write=False)
     @model_validate(AnnotationListQuery)
     def get(self, req_data: AnnotationListQuery, session: Session, app_id: UUID):
         page = req_data.page
         limit = req_data.limit
         keyword = req_data.keyword
+        effective_page, effective_limit = clamp_pagination(page, limit, 100)
 
         annotation_list, total = AppAnnotationService.get_annotation_list_by_app_id(
-            str(app_id), page, limit, keyword, session
+            str(app_id), effective_page, effective_limit, keyword, session
         )
         annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
         return AnnotationList(
-            data=annotation_models, has_more=len(annotation_list) == limit, limit=limit, total=total, page=page
+            data=annotation_models,
+            has_more=effective_page * effective_limit < total,
+            limit=effective_limit,
+            total=total,
+            page=effective_page,
         ).model_dump(mode="json"), 200
 
     @console_ns.doc("create_annotation")
@@ -321,7 +327,7 @@ class AnnotationApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_session
     @model_validate(CreateAnnotationPayload)
     def post(self, req_data: CreateAnnotationPayload, session: Session, app_id: UUID):
@@ -341,7 +347,7 @@ class AnnotationApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_CREATE_AND_MANAGEMENT, PlainApp()))
     @console_ns.response(204, "Annotations deleted successfully")
     @with_session
     def delete(self, session: Session, app_id: UUID):
@@ -382,7 +388,7 @@ class AnnotationExportApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @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)
@@ -411,7 +417,7 @@ class AnnotationUpdateDeleteApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_session
     @model_validate(UpdateAnnotationPayload)
     def post(self, req_data: UpdateAnnotationPayload, session: Session, app_id: UUID, annotation_id: UUID):
@@ -429,7 +435,7 @@ class AnnotationUpdateDeleteApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @console_ns.response(204, "Annotation deleted successfully")
     @with_session
     def delete(self, session: Session, app_id: UUID, annotation_id: UUID):
@@ -458,7 +464,7 @@ class AnnotationBatchImportApi(Resource):
     @annotation_import_rate_limit
     @annotation_import_concurrency_limit
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
     @with_session
     def post(self, session: Session, app_id: UUID):
         from configs import dify_config
@@ -513,7 +519,7 @@ class AnnotationBatchImportStatusApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     def get(self, app_id: UUID, job_id: UUID):
         indexing_cache_key = f"app_annotation_batch_import_{str(job_id)}"
         cache_result = redis_client.get(indexing_cache_key)
@@ -546,22 +552,29 @@ class AnnotationHitHistoryListApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @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)
+        # This route takes both straight off the query string with no bounds, so
+        # clamp them the way the query itself will.
+        effective_page, effective_limit = clamp_pagination(page, limit, 100)
         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,
+            effective_page,
+            effective_limit,
             session,
         )
         history_models = TypeAdapter(list[AnnotationHitHistory]).validate_python(
             annotation_hit_history_list, from_attributes=True
         )
         return AnnotationHitHistoryList(
-            data=history_models, has_more=len(annotation_hit_history_list) == limit, limit=limit, total=total, page=page
+            data=history_models,
+            has_more=effective_page * effective_limit < total,
+            limit=effective_limit,
+            total=total,
+            page=effective_page,
         ).model_dump(mode="json")

api/controllers/console/app/app.py

@@ -2,8 +2,9 @@ import logging
 import uuid
 from collections.abc import Sequence
 from datetime import datetime
-from typing import Any, Literal
+from typing import Any, Literal, Self
 
+from flask import send_file
 from flask_restx import Resource
 from pydantic import AliasChoices, BaseModel, Field, ValidationInfo, computed_field, field_validator, model_validator
 from sqlalchemy import select
@@ -13,7 +14,7 @@ from werkzeug.exceptions import BadRequest, Forbidden, NotFound
 from configs import dify_config
 from controllers.common.app_access import resolve_app_access_filter
 from controllers.common.fields import RedirectUrlResponse, SimpleResultResponse
-from controllers.common.helpers import FileInfo
+from controllers.common.rbac import AgentBehindApp, PlainApp, RBACCheck, Workspace
 from controllers.common.schema import (
     query_params_from_model,
     query_params_from_request,
@@ -22,11 +23,10 @@ from controllers.common.schema import (
     register_schema_models,
 )
 from controllers.console import console_ns
-from controllers.console.app.wraps import agent_manage_required_for_agent_app, get_app_model, with_session
+from controllers.console.app.wraps import get_app_model, with_session
 from controllers.console.workspace.models import LoadBalancingPayload
 from controllers.console.wraps import (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     cloud_edition_billing_resource_check,
     edit_permission_required,
@@ -39,19 +39,24 @@ from controllers.console.wraps import (
     with_current_user,
     with_current_user_id,
 )
+from core.file.remote_file_metadata import FileInfo
 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.trigger.constants import TRIGGER_NODE_TYPES
+from enums import DeploymentEdition
 from extensions.ext_application_services import application_services
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from graphon.enums import WorkflowExecutionStatus
+from libs.flask_restx_compat import BINARY_RESPONSE_MEDIA_TYPES_VENDOR_KEY
 from libs.helper import build_icon_url, dump_response, to_timestamp
 from libs.login import login_required
 from models import Account, App, DatasetPermissionEnum, Workflow
-from models.model import IconType
+from models.model import AppMode, IconType
+from services.agent.roster_package_exporter import RosterAgentPackageExporter
 from services.app_dsl_service import AppDslService
+from services.app_package_service import AppPackageService
 from services.app_service import (
     AppListParams,
     AppListSortBy,
@@ -63,7 +68,7 @@ from services.app_service import (
 )
 from services.enterprise import rbac_service as enterprise_rbac_service
 from services.enterprise.enterprise_service import EnterpriseService
-from services.entities.dsl_entities import DslImportWarning, ImportMode, ImportStatus
+from services.entities.dsl_entities import DslImportWarning, ImportStatus
 from services.entities.knowledge_entities.knowledge_entities import (
     DataSource,
     InfoList,
@@ -77,6 +82,7 @@ from services.entities.knowledge_entities.knowledge_entities import (
     WeightVectorSetting,
 )
 from services.errors.account import NoPermissionError
+from services.feature_service import FeatureService
 from services.system_feature_service import SystemFeatureService
 from tasks.initialize_created_app_rbac_access_task import initialize_created_app_rbac_access_task
 
@@ -180,8 +186,24 @@ class CopyAppPayload(BaseModel):
 
 
 class AppExportQuery(BaseModel):
+    format: Literal["yaml", "ifpkg"] | None = Field(
+        default=None, description="Export format; defaults to ifpkg for all Apps"
+    )
     include_secret: bool = Field(default=False, description="Include secrets in export")
     workflow_id: str | None = Field(default=None, description="Specific workflow ID to export")
+    version_id: uuid.UUID | None = Field(
+        default=None,
+        description=(
+            "Published Agent version ID to export; requires a paid plan on Cloud. "
+            "If omitted, exports the shared draft, falling back to the active snapshot when no draft exists."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_version_selectors(self) -> Self:
+        if self.version_id is not None and self.workflow_id is not None:
+            raise ValueError("version_id and workflow_id cannot be used together")
+        return self
 
 
 class AppNamePayload(BaseModel):
@@ -691,7 +713,7 @@ class AppListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_CREATE_AND_MANAGEMENT, Workspace()))
     @cloud_edition_billing_resource_check("apps")
     @edit_permission_required
     @with_current_user
@@ -868,7 +890,7 @@ class AppApi(Resource):
     @enterprise_license_required
     @with_current_user
     @with_current_tenant_id
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @with_session(write=False)
     @get_app_model(mode=None)
     def get(self, session: Session, current_tenant_id: str, current_user: Account, app_model: App):
@@ -907,8 +929,9 @@ class AppApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_EDIT, PlainApp()), RBACCheck(RBACPermission.AGENT_EDIT, AgentBehindApp())
+    )
     @with_session
     @get_app_model(mode=None)
     @model_validate(UpdateAppPayload)
@@ -942,8 +965,9 @@ class AppApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_DELETE)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_DELETE, PlainApp()), RBACCheck(RBACPermission.AGENT_DELETE, AgentBehindApp())
+    )
     @with_session
     @get_app_model
     def delete(self, session: Session, app_model: App):
@@ -967,70 +991,56 @@ class AppCopyApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_CREATE_AND_MANAGEMENT, PlainApp()))
     @with_current_user
     @with_current_tenant_id
+    @with_session
     @get_app_model(mode=None)
     @model_validate(CopyAppPayload)
-    def post(self, req_data: CopyAppPayload, current_tenant_id: str, current_user: Account, app_model: App):
+    def post(
+        self,
+        req_data: CopyAppPayload,
+        session: Session,
+        current_tenant_id: str,
+        current_user: Account,
+        app_model: App,
+    ):
         """Copy app"""
         # The role of the current user in the ta table must be admin, owner, or editor
 
-        with Session(db.engine, expire_on_commit=False) as session:
-            import_service = AppDslService(session)
-            yaml_content = import_service.export_dsl(app_model=app_model, session=session, include_secret=True)
-            try:
-                result = import_service.import_app(
-                    account=current_user,
-                    import_mode=ImportMode.YAML_CONTENT,
-                    yaml_content=yaml_content,
-                    name=req_data.name,
-                    description=req_data.description,
-                    icon_type=req_data.icon_type,
-                    icon=req_data.icon,
-                    icon_background=req_data.icon_background,
-                )
-            except NoPermissionError as e:
-                raise Forbidden(str(e))
-            if result.status == ImportStatus.FAILED:
-                session.rollback()
-                return dump_response(AppImportResponse, result), 400
-            if result.status == ImportStatus.PENDING:
-                session.rollback()
-                return dump_response(AppImportResponse, result), 202
-            session.commit()
-
-            # Inherit web app permission from original app
-            if result.app_id and SystemFeatureService.is_webapp_auth_enabled():
-                try:
-                    # Get the original app's access mode
-                    original_settings = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_model.id)
-                    access_mode = original_settings.access_mode
-                except Exception:
-                    # If original app has no settings (old app), default to public to match fallback behavior
-                    access_mode = "public"
-
-                # Apply the same access mode to the copied app
-                EnterpriseService.WebAppAuth.update_app_access_mode(result.app_id, access_mode)
-
-            stmt = select(App).where(App.id == result.app_id)
-            app = session.scalar(stmt)
-            if not app:
-                raise NotFound("App not found")
-
-            permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(
-                current_tenant_id,
-                current_user.id,
-                [str(app.id)],
-                session=session,
+        import_service = AppDslService(session)
+        try:
+            result, app = import_service.copy_app(
+                app_model=app_model,
+                account=current_user,
+                tenant_id=current_tenant_id,
+                name=req_data.name,
+                description=req_data.description,
+                icon_type=req_data.icon_type,
+                icon=req_data.icon,
+                icon_background=req_data.icon_background,
             )
-            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
+        except NoPermissionError as e:
+            raise Forbidden(str(e))
+        if result.status == ImportStatus.FAILED:
+            return dump_response(AppImportResponse, result), 400
+        if result.status == ImportStatus.PENDING:
+            return dump_response(AppImportResponse, result), 202
+        if not app:
+            raise NotFound("App not found")
+
+        permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(
+            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")
@@ -1039,25 +1049,65 @@ class AppExportApi(Resource):
     @console_ns.doc(description="Export application configuration as DSL")
     @console_ns.doc(params={"app_id": "Application ID to export"})
     @console_ns.doc(params=query_params_from_model(AppExportQuery))
+    @console_ns.doc(
+        produces=["application/json", "application/zip"],
+        vendor={BINARY_RESPONSE_MEDIA_TYPES_VENDOR_KEY: ["application/zip"]},
+    )
     @console_ns.response(200, "App exported successfully", console_ns.models[AppExportResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_IMPORT_EXPORT_DSL, PlainApp()),
+        RBACCheck(RBACPermission.AGENT_IMPORT_EXPORT_DSL, AgentBehindApp()),
+    )
     @get_app_model
     @model_validate(AppExportQuery)
     def get(self, req_data: AppExportQuery, app_model: App):
         """Export app"""
 
+        if req_data.version_id is not None:
+            if app_model.mode != AppMode.AGENT:
+                raise BadRequest("version_id is only available for Agent Apps")
+            if (
+                dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD
+                and not FeatureService.get_workspace_plan(app_model.tenant_id).is_paid
+            ):
+                raise Forbidden("This feature requires a paid plan.")
+
+        if req_data.format != "yaml":
+            if app_model.mode == AppMode.AGENT:
+                agent_id = app_model.bound_agent_id_with_session(session=db.session())
+                if agent_id is None:
+                    raise NotFound("Agent not found")
+                exported = RosterAgentPackageExporter().export(
+                    tenant_id=app_model.tenant_id, agent_id=agent_id, version_id=req_data.version_id
+                )
+            else:
+                exported = AppPackageService().export_app(
+                    app_model=app_model,
+                    include_secret=req_data.include_secret,
+                    workflow_id=req_data.workflow_id,
+                )
+            try:
+                archive_response = send_file(
+                    exported.archive, mimetype="application/zip", as_attachment=True, download_name=exported.filename
+                )
+            except Exception:
+                exported.close()
+                raise
+            archive_response.call_on_close(exported.close)
+            return archive_response
+
         response = AppExportResponse(
             data=AppDslService.export_dsl(
                 app_model=app_model,
                 session=db.session(),
                 include_secret=req_data.include_secret,
                 workflow_id=req_data.workflow_id,
+                version_id=req_data.version_id,
             )
         )
         return response.model_dump(mode="json")
@@ -1070,8 +1120,10 @@ class AppPublishToCreatorsPlatformApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_IMPORT_EXPORT_DSL, PlainApp()),
+        RBACCheck(RBACPermission.AGENT_RELEASE_AND_VERSION, AgentBehindApp()),
+    )
     @with_current_user_id
     @get_app_model(mode=None)
     def post(self, current_user_id: str, app_model: App):
@@ -1111,8 +1163,9 @@ class AppNameApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_EDIT, PlainApp()), RBACCheck(RBACPermission.AGENT_EDIT, AgentBehindApp())
+    )
     @with_session
     @get_app_model(mode=None)
     @model_validate(AppNamePayload)
@@ -1139,8 +1192,9 @@ class AppIconApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_EDIT, PlainApp()), RBACCheck(RBACPermission.AGENT_EDIT, AgentBehindApp())
+    )
     @with_session
     @get_app_model(mode=None)
     @model_validate(AppIconPayload)
@@ -1173,7 +1227,10 @@ class AppSiteStatus(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @agent_manage_required_for_agent_app(scene=RBACPermission.APP_RELEASE_AND_VERSION)
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_RELEASE_AND_VERSION, PlainApp()),
+        RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentBehindApp()),
+    )
     @with_session
     @get_app_model(mode=None)
     @model_validate(AppSiteStatusPayload)
@@ -1200,8 +1257,10 @@ class AppApiStatus(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_RELEASE_AND_VERSION, PlainApp()),
+        RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentBehindApp()),
+    )
     @with_session
     @get_app_model(mode=None)
     @model_validate(AppApiStatusPayload)
@@ -1230,7 +1289,7 @@ class AppTraceApi(Resource):
     @login_required
     @account_initialization_required
     @with_session
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     @get_app_model
     def get(self, session: Session, app_model: App):
         """Get app trace"""
@@ -1252,7 +1311,7 @@ class AppTraceApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TRACING_CONFIG)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_TRACING_CONFIG, PlainApp()))
     @get_app_model
     @model_validate(AppTracePayload)
     def post(self, req_data: AppTracePayload, app_model: App):

api/controllers/console/app/app_import.py

@@ -1,33 +1,43 @@
+from typing import BinaryIO, Literal, cast
+from uuid import uuid4
+
+from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 from werkzeug.exceptions import Forbidden
 
 from configs import dify_config
-from controllers.common.schema import register_enum_models, register_schema_models
+from controllers.common.rbac import PlainApp, RBACCheck, Workspace
+from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
     RBACPermission,
-    RBACResourceScope,
     account_initialization_required,
     cloud_edition_billing_resource_check,
     edit_permission_required,
-    model_validate,
     rbac_permission_required,
     setup_required,
+    validate_request,
     with_current_user,
 )
+from core.plugin.entities.plugin import PluginDependency
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
+from fields.base import ResponseModel
 from libs.login import current_account_with_tenant, login_required
 from models.account import Account
-from models.model import App
+from models.model import App, AppMode
+from services.agent.errors import InvalidRosterAgentPackageError
+from services.agent.roster_package_importer import RosterAgentPackageImporter
 from services.app_dsl_service import (
     IMPORT_INFO_REDIS_KEY_PREFIX,
     AppDslService,
     Import,
     PendingData,
 )
+from services.app_import_source import download_app_import_source, try_read_yaml
+from services.app_package_service import AppPackageService, PreparedAppPackage
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import CheckDependenciesResult, ImportStatus
 from services.errors.account import NoPermissionError
@@ -49,8 +59,16 @@ class AppImportPayload(BaseModel):
     app_id: str | None = Field(None)
 
 
+class RosterAgentPackageConflictResponse(ResponseModel):
+    code: str
+    message: str
+    status: Literal[409] = 409
+    leaked_dependencies: list[PluginDependency] = Field(default_factory=list)
+
+
 register_enum_models(console_ns, ImportStatus)
 register_schema_models(console_ns, AppImportPayload, Import, CheckDependenciesResult)
+register_response_schema_models(console_ns, RosterAgentPackageConflictResponse)
 
 
 def _current_user_and_tenant_id(current_user: Account | None) -> tuple[Account, str | None]:
@@ -73,19 +91,120 @@ def _current_user_and_tenant_id(current_user: Account | None) -> tuple[Account,
 
 @console_ns.route("/apps/imports")
 class AppImportApi(Resource):
-    @console_ns.expect(console_ns.models[AppImportPayload.__name__])
+    @console_ns.doc(
+        params={
+            "payload": {
+                "required": True,
+                "content": {
+                    "application/json": {"schema": {"$ref": "#/definitions/AppImportPayload"}},
+                    "multipart/form-data": {
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "file": {
+                                    "type": "string",
+                                    "format": "binary",
+                                    "description": "App .ifpkg archive",
+                                },
+                                "app_id": {"type": "string", "description": "App to overwrite"},
+                                "name": {"type": "string"},
+                                "description": {"type": "string"},
+                                "icon_type": {"type": "string"},
+                                "icon": {"type": "string"},
+                                "icon_background": {"type": "string"},
+                            },
+                            "required": ["file"],
+                        }
+                    },
+                },
+            }
+        },
+    )
     @console_ns.response(200, "Import completed", console_ns.models[Import.__name__])
     @console_ns.response(202, "Import pending confirmation", console_ns.models[Import.__name__])
     @console_ns.response(400, "Import failed", console_ns.models[Import.__name__])
+    @console_ns.response(403, "Insufficient import or plugin installation permissions")
+    @console_ns.response(
+        409, "Agent name conflict or missing plugins", console_ns.models[RosterAgentPackageConflictResponse.__name__]
+    )
+    @console_ns.response(413, "Roster Agent package exceeds the size limit")
     @setup_required
     @login_required
     @account_initialization_required
-    @cloud_edition_billing_resource_check("apps")
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL, resource_required=False)
     @with_current_user
-    @model_validate(AppImportPayload)
-    def post(self, req_data: AppImportPayload, current_user: Account | None = None):
+    def post(self, current_user: Account):
+        if request.mimetype == "multipart/form-data":
+            return self._import_package(current_user)
+        payload = validate_request(AppImportPayload)
+        if payload.mode == "yaml-url" and payload.yaml_url:
+            return self._import_url(payload, current_user)
+        return self._import_dsl(payload, current_user)
+
+    @rbac_permission_required(
+        RBACCheck(RBACPermission.APP_IMPORT_EXPORT_DSL, Workspace()),
+        RBACCheck(RBACPermission.AGENT_IMPORT_EXPORT_DSL, Workspace()),
+    )
+    def _import_url(self, payload: AppImportPayload, current_user: Account):
+        with download_app_import_source(payload.yaml_url or "") as source:
+            content = try_read_yaml(source)
+            if content is not None:
+                return self._import_dsl(
+                    payload.model_copy(update={"mode": "yaml-content", "yaml_content": content, "yaml_url": None}),
+                    current_user,
+                )
+            return self._import_package(current_user, payload, source)
+
+    def _import_package(
+        self, current_user: Account, payload: AppImportPayload | None = None, source: BinaryIO | None = None
+    ):
+        if source is None:
+            uploaded = request.files.get("file")
+            if uploaded is None or not uploaded.filename:
+                raise InvalidRosterAgentPackageError("App package file is required")
+            if not uploaded.filename.lower().endswith(".ifpkg"):
+                raise InvalidRosterAgentPackageError("App package file must use the .ifpkg extension")
+            source = cast(BinaryIO, uploaded.stream)
+        package = AppPackageService().read_package(source)
+        if package is not None:
+            with package:
+                if payload is None:
+                    payload = AppImportPayload.model_validate({**request.form.to_dict(), "mode": "yaml-content"})
+                return self._import_dsl(
+                    payload.model_copy(update={"mode": "yaml-content", "yaml_content": package.dsl, "yaml_url": None}),
+                    current_user,
+                    package=package,
+                )
+        return self._import_agent_package(current_user, source, payload)
+
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_CREATE, Workspace()))
+    @rbac_permission_required(RBACCheck(RBACPermission.AGENT_IMPORT_EXPORT_DSL, Workspace()))
+    def _import_agent_package(self, current_user: Account, source: BinaryIO, payload: AppImportPayload | None = None):
+        app_id = payload.app_id if payload is not None else request.form.get("app_id")
+        if app_id:
+            raise InvalidRosterAgentPackageError("Roster Agent package import does not support overwriting an App")
+        account, tenant_id = _current_user_and_tenant_id(current_user)
+        if tenant_id is None:
+            raise Forbidden("Current workspace is required")
+        importer = RosterAgentPackageImporter()
+        result = importer.import_package(source=source, tenant_id=tenant_id, account=account)
+        return Import(
+            id=str(uuid4()),
+            status=ImportStatus.COMPLETED_WITH_WARNINGS if result.warnings else ImportStatus.COMPLETED,
+            app_id=result.app_id,
+            app_mode=AppMode.AGENT,
+            warnings=result.warnings,
+        ).model_dump(mode="json"), 200
+
+    @cloud_edition_billing_resource_check("apps")
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_IMPORT_EXPORT_DSL, Workspace()))
+    def _import_dsl(
+        self,
+        req_data: AppImportPayload,
+        current_user: Account | None = None,
+        *,
+        package: PreparedAppPackage | None = None,
+    ):
         current_user = current_user if current_user is not None else _current_user_and_tenant_id(None)[0]
 
         # AppDslService performs internal commits for some creation paths, so use a plain
@@ -106,6 +225,7 @@ class AppImportApi(Resource):
                     icon=req_data.icon,
                     icon_background=req_data.icon_background,
                     app_id=req_data.app_id,
+                    package=package,
                 )
             except NoPermissionError as e:
                 raise Forbidden(str(e))
@@ -149,7 +269,7 @@ class AppImportConfirmApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL, resource_required=False)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_IMPORT_EXPORT_DSL, Workspace()))
     @with_current_user
     def post(self, current_user: Account | None = None, import_id: str = ""):
         current_user = current_user if current_user is not None else _current_user_and_tenant_id(None)[0]
@@ -208,7 +328,7 @@ class AppImportCheckDependenciesApi(Resource):
     @get_app_model
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
     def get(self, app_model: App):
         with Session(db.engine, expire_on_commit=False) as session:
             import_service = AppDslService(session)