Remove unused generated docs path type

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

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

@@ -1,73 +1,94 @@
 ---
 name: frontend-code-review
-description: "Trigger when the user requests a review of frontend files (e.g., `.tsx`, `.ts`, `.js`). Support both pending-change reviews and focused file reviews while applying the checklist rules."
+description: Review Dify frontend code for correctness, accessibility, component design, dify-ui usage, data/query boundaries, performance, and tests. Trigger for `.tsx`, `.ts`, `.js`, UI, React, Next.js, pending-change, or focused frontend review requests.
 ---
 
 # Frontend Code Review
 
-## Intent
-Use this skill whenever the user asks to review frontend code (especially `.tsx`, `.ts`, or `.js` files). Support two review modes:
+## When To Use
 
-1. **Pending-change review** – inspect staged/working-tree files slated for commit and flag checklist violations before submission.
-2. **File-targeted review** – review the specific file(s) the user names and report the relevant checklist findings.
+Use this skill when the user asks to review, audit, analyze, or sanity-check frontend code under `web/`, `packages/dify-ui/`, or frontend-adjacent TypeScript files.
 
-Stick to the checklist below for every applicable file and mode.
+Supported modes:
 
-## Checklist
-See [references/code-quality.md](references/code-quality.md), [references/performance.md](references/performance.md), [references/business-logic.md](references/business-logic.md) for the living checklist split by category—treat it as the canonical set of rules to follow.
+- **Pending-change review**: inspect staged and working-tree changes.
+- **File-focused review**: inspect explicitly named files or paths.
+- **Diff/snippet review**: review pasted diffs or snippets using best-effort references.
 
-Flag each rule violation with urgency metadata so future reviewers can prioritize fixes.
+Do not use this skill for backend-only code under `api/`; use `backend-code-review` instead.
+
+## Required Context
+
+Before reviewing, read the relevant local contracts:
+
+- `web/AGENTS.md` for Dify frontend workflow, overlays, design tokens, state, and tests.
+- `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md` when code uses or changes `@langgenius/dify-ui/*`.
+- `web/docs/overlay.md` when reviewing dialogs, drawers, popovers, tooltips, menus, selects, comboboxes, or other floating UI.
+- `web/docs/test.md` and the `frontend-testing` skill when reviewing tests or testability.
+- `karpathy-guidelines` for scope control and focused, verifiable changes.
+- `how-to-write-component` when reviewing React component structure, ownership, effects, query/mutation contracts, or memoization.
+
+For any UI, UX, or accessibility review, fetch the latest Web Interface Guidelines before finalizing findings. Treat them as a required baseline, not the complete source of accessibility truth:
+
+```text
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+If the review depends on a current framework, SDK, browser API, or accessibility behavior and local code does not settle it, check the current official docs first. For browser compatibility, deprecation, or behavior-sensitive frontend APIs, verify MDN or the relevant standard.
+
+## Rule Packs
+
+Apply every relevant rule pack:
+
+- [references/accessibility-ui.md](references/accessibility-ui.md) — accessibility, semantic HTML, focus, forms, keyboard, disabled states, copy, and long-content behavior. Combines Web Interface Guidelines with Dify UI, Base UI, MDN, and local primitive contracts.
+- [references/dify-ui.md](references/dify-ui.md) — Dify UI primitive usage, Base UI semantics, overlays, forms, tokens, radius mapping, and primitive boundaries.
+- [references/component-architecture.md](references/component-architecture.md) — component ownership, props, state, effects, exports, wrappers, and feature organization.
+- [references/data-query-contracts.md](references/data-query-contracts.md) — generated contracts, TanStack Query, mutations, workspace/auth/SSR boundaries, URL/local storage state.
+- [references/performance.md](references/performance.md) — React/Next performance review rules from Vercel guidance, scoped to real risk.
+- [references/testing.md](references/testing.md) — frontend test review rules.
+- [references/dify-invariants.md](references/dify-invariants.md) — stable Dify-specific runtime invariants that generic React/a11y rules will not catch.
+- [references/code-quality.md](references/code-quality.md) — general TypeScript, styling, naming, and maintainability rules.
 
 ## Review Process
-1. Open the relevant component/module. Gather lines that relate to class names, React Flow hooks, prop memoization, and styling.
-2. For each rule in the review point, note where the code deviates and capture a representative snippet.
-3. Compose the review section per the template below. Group violations first by **Urgent** flag, then by category order (Code Quality, Performance, Business Logic).
 
-## Required output
-When invoked, the response must exactly follow one of the two templates:
+1. Identify the review scope. For pending changes, inspect `git diff --stat`, `git diff`, and staged diff if relevant. For file-focused reviews, stay within the named files unless a referenced owner/contract must be read.
+2. Read code around the changed lines and the owning module. Do not review by isolated snippets when nearby ownership, labels, query inputs, or overlay structure decide correctness.
+3. Check user-visible regressions first: accessibility, broken interaction, auth/permission leaks, query/hydration errors, data loss, navigation mistakes, and impossible states.
+4. Then check maintainability and performance: ownership, effects, wrappers, memoization, bundle/waterfall risks, tests, and design-system drift.
+5. Report only actionable findings. Do not list speculative risks, style preferences, or broad refactors unless they are directly tied to a reproducible issue in scope.
 
-### Template A (any findings)
-```
-# Code review
-Found <N> urgent issues need to be fixed:
+## Severity
 
-## 1 <brief description of bug>
-FilePath: <path> line <line>
-<relevant code snippet or pointer>
+- **P0**: security/privacy/auth leak, data loss, production crash, inaccessible critical flow, or broken primary workflow.
+- **P1**: user-visible regression, hydration/SSR failure, invalid API/query contract, broken keyboard/focus behavior, or serious design-system/a11y violation.
+- **P2**: maintainability or performance issue likely to cause bugs, duplicated state, incorrect ownership, missing tests for risky behavior, or non-critical a11y issue.
+- **P3**: minor cleanup with clear value. Omit unless the user asked for a thorough audit.
 
+## Output Format
 
-### Suggested fix
-<brief description of suggested fix>
+Lead with findings, ordered by severity. Use this structure:
 
----
-... (repeat for each urgent issue) ...
+```markdown
+## Findings
 
-Found <M> suggestions for improvement:
+- [P1] Short issue title
+  File: `path/to/file.tsx:123`
+  Why it matters and how to reproduce or reason about it.
+  Suggested fix: concrete fix direction.
 
-## 1 <brief description of suggestion>
-FilePath: <path> line <line>
-<relevant code snippet or pointer>
+## Open Questions
 
+- Question or assumption, if any.
 
-### Suggested fix
-<brief description of suggested fix>
+## Summary
 
----
-
-... (repeat for each suggestion) ...
+Brief secondary context. Mention tests not run or residual risk.
 ```
 
-If there are no urgent issues, omit that section. If there are no suggestions, omit that section.
-
-If the issue number is more than 10, summarize as "10+ urgent issues" or "10+ suggestions" and just output the first 10 issues.
-
-Don't compress the blank lines between sections; keep them as-is for readability.
-
-If you use Template A (i.e., there are issues to fix) and at least one issue requires code changes, append a brief follow-up question after the structured output asking whether the user wants you to apply the suggested fix(es). For example: "Would you like me to use the Suggested fix section to address these issues?"
-
-### Template B (no issues)
-```
-## Code review
-No issues found.
-```
+Rules:
 
+- If there are no findings, say `No issues found.` and mention any test gaps or residual risk.
+- Always include file and line when available.
+- Keep findings concrete and reproducible.
+- Do not include praise sections by default.
+- Do not ask to apply fixes unless the user explicitly wants review plus implementation.

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

@@ -0,0 +1,109 @@
+# Accessibility And UI Rules
+
+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:
+
+```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:
+
+- `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.
+
+## 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`.
+- 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.
+
+## Keyboard And Focus
+
+Flag:
+
+- Interactive elements without visible `focus-visible` treatment.
+- `outline-none` / `outline-hidden` without an equivalent focus-visible ring or state.
+- Custom interactive elements missing keyboard handling.
+- Focus trapped, lost, or sent to the wrong surface after dialog/popover/menu close.
+- Focus ring applied to the wrong DOM node. Verify the actual focus target, especially with Base UI controls such as Slider.
+
+Use `focus-visible` for keyboard focus. Use `focus-within` or `has-[:focus-visible]` when the visual wrapper is not the focused element.
+
+## Forms
+
+Flag:
+
+- Inputs, selects, switches, checkboxes, radios, comboboxes, or sliders without a label relationship.
+- 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.
+- `onPaste` blocking paste.
+- 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`.
+
+## Disabled, Loading, And Async States
+
+Flag:
+
+- Loading state without `aria-busy`, `role="status"`, or another accessible update path when it changes user interaction.
+- 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.
+- 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.
+
+Use native `disabled` when the control must not be interactive. Use `aria-disabled` only when the element must remain focusable and the code handles all blocked interactions.
+
+For repeated shared disabled reasons, prefer a visible group message or badge plus native disabled controls. Use per-control popover/info only when the reason is item-specific.
+
+## Overlays And Popup Reachability
+
+Flag:
+
+- Tooltip used for long, structured, interactive, or unique information.
+- Tooltip content required to understand or complete a flow.
+- PreviewCard content that touch or screen-reader users cannot reach through the trigger's click destination.
+- Popover/dialog/menu triggers without accessible names.
+- Popup content without title/description where the primitive requires them.
+
+Use Popover for explanatory content, rich help, and infotips. Use Tooltip only as a short visual label for a trigger that already has an accessible name.
+
+## Long Content And Layout
+
+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`.
+- 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.
+
+The usual Dify layout chain is: container has width constraints, text region uses `min-w-0 flex-1 truncate`, adornments use `shrink-0`.
+
+## Motion, Images, And Copy
+
+Flag:
+
+- `transition-all`.
+- Animations that do not respect reduced motion.
+- Layout-affecting animation where transform/opacity would work.
+- Images without dimensions.
+- Loading copy using `...` instead of `…`.
+- Hardcoded dates, times, numbers, or currency formats instead of `Intl.*`.

.agents/skills/frontend-code-review/references/business-logic.md

@@ -1,15 +0,0 @@
-# Rule Catalog — Business Logic
-
-## Can't use workflowStore in Node components
-
-IsUrgent: True
-
-### Description
-
-File path pattern of node components: `web/app/components/workflow/nodes/[nodeName]/node.tsx`
-
-Node components are also used when creating a RAG Pipe from a template, but in that context there is no workflowStore Provider, which results in a blank screen. [This Issue](https://github.com/langgenius/dify/issues/29168) was caused by exactly this reason.
-
-### Suggested Fix
-
-Use `import { useNodes } from 'reactflow'` instead of `import useNodes from '@/app/components/workflow/store/workflow/use-nodes'`.

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

@@ -1,44 +1,68 @@
-# Rule Catalog — Code Quality
+# Code Quality Rules
 
-## Conditional class names use utility function
+## Scope Control
 
-IsUrgent: True
-Category: Code Quality
+Flag changes that expand beyond the requested feature or review scope:
 
-### Description
+- Repo-wide cleanup mixed into a targeted fix.
+- Compatibility exports, aliases, shims, or wrapper layers added without an explicit migration requirement.
+- Shared abstractions created before there is stable cross-feature reuse.
+- Business components moved into generic shared locations without a clear ownership boundary.
 
-Ensure conditional CSS is handled via the shared `classNames` instead of custom ternaries, string concatenation, or template strings. Centralizing class logic keeps components consistent and easier to maintain.
+## TypeScript
 
-### Suggested Fix
+Flag:
 
-```ts
-import { cn } from '@/utils/classnames'
-const classNames = cn(isActive ? 'text-primary-600' : 'text-gray-500')
-```
+- `any` or broad `Record<string, any>` where generated/API types or local domain types exist.
+- Re-declared API shapes instead of importing generated or returned types.
+- Weak route/query param typing that leaks `string | string[] | undefined` deep into components.
+- Runtime wrappers added only to satisfy TypeScript when a narrower type boundary would preserve the existing runtime shape.
 
-## Tailwind-first styling
+Prefer:
 
-IsUrgent: True
-Category: Code Quality
+- Explicit domain names that match the API contract.
+- Type narrowing at route/API boundaries.
+- Small conversion helpers colocated with the component that needs them.
 
-### Description
+## Styling
 
-Favor Tailwind CSS utility classes instead of adding new `.module.css` files unless a Tailwind combination cannot achieve the required styling. Keeping styles in Tailwind improves consistency and reduces maintenance overhead.
+Flag:
 
-Update this file when adding, editing, or removing Code Quality rules so the catalog remains accurate.
+- New CSS modules or ad hoc CSS when Tailwind utilities and Dify tokens cover the need.
+- Component-level plain `.css` files or component CSS imported through `globals.css`; use scoped `*.module.css` only when Tailwind and component variants cannot express the style.
+- Generic color utilities where Dify semantic tokens exist.
+- Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or documented radius mappings exist.
+- `!` important modifiers or important CSS overrides without a narrow, documented reason.
+- Manual string concatenation, template strings, array `.join(' ')`, or custom ternaries for conditional or multi-line classes.
+- JS conditional class branches for primitive visual states already exposed by Dify UI/Base UI `data-*` selectors.
+- Incoming `className` placed before default classes in `cn(...)`, preventing call-site overrides.
+- Arbitrary z-index or one-off layering fixes on overlays.
 
-## Classname ordering for easy overrides
+Use:
 
-### Description
+- `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.
 
-When writing components, always place the incoming `className` prop after the component’s own class values so that downstream consumers can override or extend the styling. This keeps your component’s defaults but still lets external callers change or remove specific styles.
+## Imports
 
-Example:
+Flag:
 
-```tsx
-import { cn } from '@/utils/classnames'
+- Barrel imports from `@langgenius/dify-ui`; consumers must use subpath exports.
+- New overlay imports from legacy `@/app/components/base/modal`, `dialog`, or `drawer`.
+- Cross-feature imports that bypass explicit top-level public files.
+- Direct imports from generated/internal implementation files when a feature contract already exposes the intended surface.
 
-const Button = ({ className }) => {
-  return <div className={cn('bg-primary-600', className)}></div>
-}
-```
+## Copy And i18n
+
+Flag:
+
+- User-facing hardcoded strings in `web/`.
+- Added or renamed i18n keys that are not present in every supported locale file for the touched namespace.
+- Translation namespace drift, especially using unrelated module namespaces for local feature copy.
+- Generic button labels like `Continue` where the action is specific.
+- Error messages that state only the failure and not the next step.
+
+Use feature-local translation keys by default. Alias only when crossing namespaces. `pnpm i18n:check --file <name>` should pass for any touched translation namespace.

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

@@ -0,0 +1,89 @@
+# Component Architecture Rules
+
+Use these rules for React component structure, ownership, state, props, effects, and module organization.
+
+## Ownership
+
+Flag:
+
+- 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.
+
+Accept repeated TanStack Query calls in siblings when each component independently consumes the data. Cache deduplication is not a reason to hoist by itself.
+
+## Component Boundaries
+
+Flag:
+
+- React component files over 300 lines when the file mixes multiple responsibilities that can be split into focused colocated components, hooks, or utilities.
+- Shallow wrappers that only rename props or hide the real primitive.
+- Extra DOM wrappers that do not provide layout, semantics, accessibility, state ownership, or library integration.
+- Dialog/dropdown/popover hidden surfaces that obscure the parent flow when they should be extracted into a small local component.
+- Business forms, menu bodies, or one-off helpers moved away from their owner without reuse or semantic value.
+
+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:
+
+- `React.FC` / `FC`.
+- Default exports outside framework-required files.
+- 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.
+
+Prefer top-level `function` declarations for components and module helpers. Use arrow functions for callbacks and local lambdas.
+
+## 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 state from props when a keyed reset, stable ID, or render-time derivation would work.
+- 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.
+- 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.
+
+Prefer render-time derivation. Keep true local state for user choices, transient input, controlled popups, and feature UI state that has no server source.
+
+## 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.

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

@@ -0,0 +1,74 @@
+# Data, Query, And Contract Rules
+
+Use these rules for generated contracts, TanStack Query, mutations, auth/SSR boundaries, URL state, and client persistence.
+
+## Generated Contracts
+
+Flag:
+
+- 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.
+
+Use `web/contract/*` as the API shape source of truth. Follow existing `{ params, query?, body? }` input shape.
+
+## Queries
+
+Flag:
+
+- `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.
+
+Use `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))` directly unless a feature hook performs real orchestration.
+
+## 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.

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

@@ -0,0 +1,22 @@
+# Dify Invariants
+
+Use these stable Dify-specific runtime rules in addition to the generic review packs.
+
+This file is not a place for active feature notes. Do not add rules for one branch, one PR, or a short-lived product decision such as a specific agent-v2, plugin, model-provider, or onboarding task. Keep a rule here only when all of these are true:
+
+- It is a stable Dify runtime invariant.
+- Generic React, TypeScript, accessibility, dify-ui, query, or performance rules would not catch it.
+- The failure mode is concrete enough to produce a file-line review finding.
+- The rule is likely to remain valid across normal feature work.
+
+## Workflow Nodes And RAG Pipe
+
+Flag:
+
+- Node components under `web/app/components/workflow/nodes/[nodeName]/node.tsx` importing workflow store hooks that are unavailable in RAG Pipe template rendering.
+- Node UI relying on provider context that is not mounted in every rendering surface.
+- Store reads in render where React Flow `useNodes` / `useEdges` provide the actual node/edge source.
+
+Known failure mode: workflow node components can also render while creating a RAG Pipe from a template. In that context there may be no workflowStore provider, causing a blank screen.
+
+Prefer React Flow hooks for node/edge UI consumption. Use store APIs only where the provider is guaranteed and the code path is workflow-only.

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

@@ -0,0 +1,134 @@
+# Dify UI Rules
+
+Use these rules whenever a review touches `packages/dify-ui/` or code consuming `@langgenius/dify-ui/*`.
+
+Before finalizing findings for those files, read the current local docs that apply:
+
+- `packages/dify-ui/README.md`
+- `packages/dify-ui/AGENTS.md`
+- `web/docs/overlay.md` for floating UI
+- `packages/dify-ui/src/<primitive>/index.tsx` for the primitive being changed or consumed
+
+## Package Boundary
+
+Flag in `packages/dify-ui`:
+
+- Imports from `web/`.
+- Dependencies on Next.js, i18n, ky, Jotai, Zustand, TanStack Query, oRPC, or business APIs.
+- Business-specific component behavior that belongs in `web/`.
+- Multiple unrelated primitives in one component folder.
+
+`packages/dify-ui` is a primitive layer: Base UI headless components + `cva` + `cn` + Dify design tokens.
+
+## Imports And Exports
+
+Flag:
+
+- Consumer imports from `@langgenius/dify-ui` without a subpath.
+- Missing `package.json#exports` entry for a new primitive.
+- Internal package imports using workspace subpaths instead of relative paths.
+- Exported props using internal-only types that consumers cannot import from the component subpath.
+
+Consumers use subpath exports such as `@langgenius/dify-ui/button`.
+
+## Props And State
+
+Flag:
+
+- Flattened props where related values need a discriminated union, such as `value` / `defaultValue`, `multiple` / `value`, or `clearable` / `onChange`.
+- React state used only to mirror Base UI state for class names.
+- JavaScript conditional class logic for visual states that the Dify UI/Base UI primitive already exposes through `data-*` attributes or CSS variables.
+- Controlled props added when uncontrolled DOM state or CSS variables would be enough.
+- Thin wrappers that rename Base UI parts without adding semantics.
+
+Prefer Base UI/Dify UI data attributes and CSS variables for visual state: `data-open`, `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`, `group-data-*`, `peer-data-*`, `has-[:focus-visible]`, and primitive CSS variables such as anchor width or transform origin. Use JS conditional classes for product/business state that the primitive does not expose.
+
+## Forms
+
+Flag:
+
+- Form-like UI using unrelated `Input` and `Button` pieces without a submit boundary.
+- Text-like fields not composed through `FieldRoot`, `FieldLabel`, and `FieldControl` when using Dify UI form semantics.
+- Select fields using `FieldLabel` instead of `SelectLabel`.
+- Slider fields using a generic label instead of `SliderLabel`.
+- Checkbox/radio groups missing `FieldsetRoot` and `FieldsetLegend`.
+- Field errors or descriptions rendered without `FieldDescription` / `FieldError` relationships.
+
+`Form` is the submit boundary. Dify UI form primitives are not a form state-management framework; business validation and schema-driven behavior belong in `web/`.
+
+## Overlay Contract
+
+Flag:
+
+- Legacy web overlay imports in new or modified code.
+- Manual portals around Dify UI overlay primitives.
+- Call-site `z-*` overrides on overlays.
+- Missing root `isolation: isolate` assumptions when debugging overlay stacking.
+- Repeated backdrop, z-index, or portal chrome at call sites.
+- Tooltip used for infotips, long text, or interactive content.
+
+All Dify UI body-portalled overlays use `z-50`. Toast uses `z-60`. DOM order handles stacking between overlays.
+
+## Primitive Selection
+
+Flag:
+
+- `Tabs` used for simple mode/filter/view selection where `SegmentedControl` is the semantic primitive.
+- `SegmentedControl` used where `tablist` / `tabpanel` semantics are required.
+- `Select` used for searchable or free-form input.
+- `Combobox` used for unrestricted search text where no selected option is remembered.
+- `Autocomplete` used for closed-list selection.
+- Tooltip or PreviewCard used for content that must be reachable on touch or by screen readers.
+
+Use:
+
+- `Autocomplete` for free-form text with optional suggestions.
+- `Combobox` for searchable selected values from a collection.
+- `Select` for closed, scannable option sets.
+- `Popover` for infotips, help text, rich content, or interactions.
+
+## Bad Usage Patterns To Flag
+
+Flag:
+
+- Manually recreating UI behavior or chrome already owned by `@langgenius/dify-ui/*` or `web/app/components/base/*`, such as buttons, inputs, toggle groups, popovers, dropdown menus, alert dialogs, switches, avatars, scroll areas, toasts, borders, focus states, disabled states, segmented controls, or existing feature components.
+- Styling a raw Base UI primitive directly in `web/` when a Dify UI primitive exists.
+- Wrapping a Dify UI primitive in a feature component that hides its label, error, disabled, or focus contract.
+- Replacing a semantic primitive with a generic `div` plus classes to match a screenshot.
+- Using `Tooltip` because it is visually convenient when the content is actually help text or needs touch access.
+- Adding a `z-*` override to make a child popup appear over a parent dialog.
+- Adding a new app-level wrapper around Dialog, Drawer, Popover, Select, or Combobox that repeats portal/backdrop/positioner logic.
+- Using dify-ui `Input` as a drop-in replacement for legacy inputs that include search, clear, copy, unit, localized placeholder, or number normalization behavior.
+- Building a form row from loose text and controls instead of the matching Field/Form primitives.
+- Adding component state only to style `data-open`, `data-checked`, `data-disabled`, or highlighted states that Base UI already exposes.
+- Passing booleans down only so children can toggle classes already expressible with primitive `data-*` selectors.
+
+## Tokens, Radius, And Styling
+
+Flag:
+
+- `radius-*` class names.
+- Custom Tailwind `borderRadius` extension for Figma radius values.
+- Generic colors where semantic Dify tokens exist.
+- Hardcoded design values where Dify tokens, component variants, or documented Figma radius mappings exist.
+- `!` important modifiers used to fight primitive styles instead of fixing the variant, selector, or component composition.
+- Manual class strings that duplicate primitive variants.
+- `min-w-(--anchor-width)` on picker popups when it defeats viewport clamping.
+
+Use the Figma radius mapping from `packages/dify-ui/AGENTS.md`; for example `--radius/sm` maps to `rounded-md`, and `--radius/md` maps to `rounded-lg`.
+
+Use `!` only for a tightly scoped compatibility override after confirming the primitive API, data attributes, and selector structure cannot express the state.
+
+## Focus Details
+
+Flag focus rings attached to the wrong element. For example, Base UI `Slider.Thumb` focuses an internal `input[type=range]`, so the visible thumb wrapper needs `has-[:focus-visible]` rather than direct wrapper `focus-visible`.
+
+## Custom SVG Icons
+
+Flag:
+
+- New generated React icon components or JSON files under `web/app/components/base/icons/src/...` for custom SVG icons.
+- Custom SVG icons consumed outside the Tailwind `i-custom-*` icon class pipeline.
+- Generated `packages/iconify-collections/custom-*/icons.json` diffs where unrelated existing icons lost or changed intrinsic `width` or `height`.
+
+New custom SVG icons belong in `packages/iconify-collections/assets/...`. Regenerate with `pnpm --filter @dify/iconify-collections generate`, validate with `pnpm --filter @dify/iconify-collections check:dimensions`, and consume the generated icon with Tailwind `i-custom-*` classes.

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

@@ -1,45 +1,78 @@
-# Rule Catalog — Performance
+# Performance Rules
 
-## React Flow data usage
+Review performance only where there is realistic impact. Do not request `memo`, `useMemo`, `useCallback`, virtualization, or caching as style preferences.
 
-IsUrgent: True
-Category: Performance
+## Async Waterfalls
 
-### Description
+Flag:
 
-When rendering React Flow, prefer `useNodes`/`useEdges` for UI consumption and rely on `useStoreApi` inside callbacks that mutate or read node/edge state. Avoid manually pulling Flow data outside of these hooks.
+- Awaiting remote feature flags or fetches before checking cheap synchronous conditions.
+- Sequential awaits for independent operations.
+- API routes or server components starting requests late when they could start early.
+- Nested per-item fetches running serially when each item can fetch in parallel.
+- Suspense boundaries that force the whole page to wait when a lower boundary could stream or isolate loading.
 
-## Complex prop stability
+Prefer `Promise.all` for independent work and branch-local awaits for conditionally needed data.
 
-IsUrgent: False
-Category: Performance
+## Bundle Size
 
-### Description
+Flag:
 
-Only require stable object, array, or map props when there is a clear reason: the child is memoized, the value participates in effect/query dependencies, the value is part of a stable-reference API contract, or profiling/local behavior shows avoidable re-renders. Do not request `useMemo` for every inline object by default; `how-to-write-component` treats memoization as a targeted optimization.
+- Barrel imports from heavy libraries or `@langgenius/dify-ui`.
+- Dynamic paths that prevent static trace analysis.
+- Heavy components loaded eagerly when hidden behind a dialog, tab, command, or feature activation.
+- Analytics, logging, editor, visualization, or third-party SDK code loaded before it is needed.
+- Feature-local optional modules imported at top level only for rare flows.
 
-Update this file when adding, editing, or removing Performance rules so the catalog remains accurate.
+Use direct imports and `next/dynamic` where the user-visible path benefits.
 
-Risky:
+## Server Rendering
 
-```tsx
-<HeavyComp
-    config={{
-        provider: ...,
-        detail: ...
-    }}
-/>
-```
+Flag:
 
-Better when stable identity matters:
+- Request-specific mutable state stored at module scope in SSR/RSC paths.
+- Large duplicate data serialized across RSC/client boundaries.
+- Static I/O repeated per request when it could be hoisted safely.
+- Cross-request cache without a bounded invalidation strategy.
+- Server actions lacking API-route-equivalent auth checks.
 
-```tsx
-const config = useMemo(() => ({
-    provider: ...,
-    detail: ...
-}), [provider, detail]);
+Use request-scoped deduplication such as `React.cache()` when repeated server reads in one request are the problem.
 
-<HeavyComp
-    config={config}
-/>
-```
+## Re-rendering
+
+Flag:
+
+- Effects or subscriptions reading broad state when a derived boolean or narrower selector is enough.
+- Components defined inside components.
+- Derived rendering state stored in state/effects.
+- Non-primitive default props recreated for memoized children.
+- Expensive work recalculated on every render where it affects real interaction cost.
+- High-frequency transient values stored in state when refs or CSS variables would avoid render loops.
+
+Do not flag simple primitive expressions wrapped or not wrapped in `useMemo`; prefer no memo for simple work.
+
+Require stable object/array/function identity only when:
+
+- The child is memoized and identity affects renders.
+- The value is an effect/query dependency.
+- A library API requires stable references.
+- Profiling or local behavior shows avoidable re-rendering.
+
+## DOM, Lists, And Rendering
+
+Flag:
+
+- Layout reads in render (`getBoundingClientRect`, `offset*`, `scrollTop`).
+- Interleaved DOM reads/writes that can cause layout thrashing.
+- Large lists rendering without virtualization, pagination, or `content-visibility`.
+- SVG/animation code animating expensive properties when transform/opacity would work.
+- `transition-all`.
+- Long-running non-critical browser work performed immediately instead of idle/deferred scheduling.
+
+## React Flow
+
+For workflow React Flow components, keep this Dify-specific rule:
+
+- 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.

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

@@ -0,0 +1,72 @@
+# Testing Review Rules
+
+Use these rules when reviewing test files, testability of changed code, or risky frontend changes that should have tests.
+
+## Missing Coverage
+
+Flag missing tests when the change affects:
+
+- User-visible behavior, navigation, form submission, validation, permissions, or loading/error/empty states.
+- Query/mutation cache behavior.
+- Accessibility-critical behavior such as labels, keyboard flow, focus, disabled state, or popup reachability.
+- URL state parsing/serialization.
+- Storage persistence or one-shot signals.
+- Regression-prone workflow or generated contract migration paths.
+
+Do not request tests for purely mechanical renames or styling-only changes unless the styling affects layout, focus, or interaction.
+
+## Selectors
+
+Flag:
+
+- `getByTestId` used where role, label, text, placeholder, landmark, or scoped dialog/menu queries are available.
+- Production `data-testid` added only to satisfy tests.
+- Assertions against decorative icons rather than the named control.
+- Tests that cannot find controls semantically but leave broken markup unchanged.
+
+Prefer `getByRole` with accessible name, then `getByLabelText`, `getByPlaceholderText`, `getByText`, and `within(...)`.
+
+## Mocking
+
+Flag:
+
+- Mocking `@langgenius/dify-ui/*` primitives.
+- Mocking `@/app/components/base/*` components when the real component is practical.
+- Mocking sibling or child components in the same directory for integration behavior.
+- Mocks that do not match the real component's conditional rendering.
+- Module-level mock state not reset in `beforeEach`.
+- `vi.clearAllMocks()` in `afterEach` instead of `beforeEach`.
+
+Use real project components for integration behavior. Mock APIs, `next/navigation`, browser shims, or complex providers only when setup would dominate the test.
+
+## Behavior
+
+Flag:
+
+- Tests inspecting implementation details instead of user-observable behavior.
+- Assertions that hardcode brittle copy when pattern matching or semantic roles would express behavior better.
+- Fake timers used without real timing behavior.
+- Async assertions missing `await`, `findBy*`, or `waitFor`.
+- Test data missing required fields because inline partial objects bypass real types.
+
+Use typed factory functions with complete defaults and partial overrides.
+
+## URL State
+
+For `nuqs` or query-state hooks, flag tests that:
+
+- Mock URL state when URL synchronization is the behavior under review.
+- Do not test parser serialize/parse round trips for custom parsers.
+- Do not assert default-clearing behavior when defaults should be removed from the URL.
+
+Prefer shared `NuqsTestingAdapter` helpers when available.
+
+## Organization
+
+Flag:
+
+- Component/hook/util tests outside sibling `__tests__/` directories.
+- Directory-level reviews that test only `index.tsx` while other files in scope contain behavior.
+- Large test files with repeated setup that should use local builders.
+
+When a component is very complex, prefer a refactor finding before asking for exhaustive tests.

.agents/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: karpathy-guidelines
+description: Lightweight coding guardrails for making focused, simple, and verifiable changes in this repo. Use for all coding work.
+---
+
+# Karpathy Guidelines
+
+Use this skill whenever you touch code in this repository.
+
+## Principles
+
+- Keep the change small and directly tied to the user request.
+- Prefer the simplest implementation that fits the existing codebase.
+- Read the nearby code first, then match its patterns.
+- Avoid unrelated refactors, broad rewrites, or style churn.
+- Preserve existing behavior unless the user explicitly asked to change it.
+- Treat regressions as a signal to narrow the change, not to add workaround layers.
+
+## Workflow
+
+1. Inspect the current implementation and tests around the change.
+2. Make the smallest coherent edit.
+3. Add or update focused tests when the behavior changes or the risk is non-trivial.
+4. Run the narrowest relevant verification first.
+5. Report exactly what was verified and anything left unverified.
+
+## Review Checklist
+
+- Does this change solve the stated problem without expanding scope?
+- Did it preserve existing route/component/data-flow semantics?
+- Are new abstractions justified by real complexity?
+- Are tests focused on the behavior that could regress?
+- Are unrelated files and generated artifacts left alone?

.claude/skills/karpathy-guidelines

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

.github/CODEOWNERS

@@ -15,12 +15,16 @@
 # Agents
 /.agents/skills/ @hyoban
 
+# Packages
+/packages/ @lyzno1
+/packages/contracts/ @crazywoola @laipz8200
+
 # Docs
 /docs/ @crazywoola
 
 # CLI
-/cli/ @langgenius/maintainers
-/.github/workflows/cli-tests.yml @langgenius/maintainers
+/cli/ @GareArc
+/.github/workflows/cli-tests.yml @GareArc
 
 # Backend (default owner, more specific rules below will override)
 /api/ @QuantumGhost
@@ -143,6 +147,14 @@
 # Frontend
 /web/ @iamjoel
 
+# Frontend - Platform and Features
+/web/config/ @lyzno1
+/web/contract/ @lyzno1
+/web/env.ts @lyzno1
+/web/features/ @lyzno1
+/web/hooks/ @lyzno1
+/web/scripts/gen-icons.mjs @lyzno1
+
 # Frontend - Web Tests
 /.github/workflows/web-tests.yml @iamjoel
 
@@ -253,7 +265,6 @@
 /web/utils/time.ts @iamjoel @zxhlyh
 /web/utils/format.ts @iamjoel @zxhlyh
 /web/utils/clipboard.ts @iamjoel @zxhlyh
-/web/hooks/use-document-title.ts @iamjoel @zxhlyh
 
 # Frontend - Billing and Education
 /web/app/components/billing/ @iamjoel @zxhlyh

.github/workflows/cli-edge.yml

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

.github/workflows/cli-release.yml

@@ -2,87 +2,165 @@ name: CLI Release
 
 on:
   workflow_dispatch:
-  push:
-    tags:
-      - 'difyctl-v*'
+    inputs:
+      release_tag:
+        description: Dify release tag to attach difyctl assets to (blank = latest stable)
+        required: false
+        type: string
+  workflow_call:
+    inputs:
+      release_tag:
+        description: Dify release tag to attach difyctl assets to (blank = latest stable)
+        required: false
+        type: string
+  release:
+    types: [released]
 
 concurrency:
-  group: cli-release-${{ github.ref }}
-  cancel-in-progress: true
+  group: difyctl-release
+  cancel-in-progress: false
 
 jobs:
-  release:
-    name: build standalone binaries (all targets)
+  validate:
+    name: validate manifest + resolve target Dify release
     runs-on: depot-ubuntu-24.04
     if: github.repository == 'langgenius/dify'
+    permissions:
+      contents: read
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./cli
+    outputs:
+      dify_tag: ${{ steps.resolve.outputs.dify_tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Export manifest to env
+        run: node scripts/release-naming.mjs github-env >> "$GITHUB_ENV"
+
+      - name: Validate manifest
+        run: scripts/release-validate-manifest.sh
+
+      - name: Resolve target Dify release
+        id: resolve
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_TAG: ${{ github.event.release.tag_name }}
+          INPUT_TAG: ${{ inputs.release_tag }}
+        run: |
+          if [ -n "$EVENT_TAG" ]; then
+              tag="$EVENT_TAG"
+          elif [ -n "$INPUT_TAG" ]; then
+              tag="$INPUT_TAG"
+          else
+              tag="$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq .tag_name)"
+          fi
+          if [ -z "$tag" ]; then
+              echo "::error::could not resolve a target Dify release tag"
+              exit 1
+          fi
+          if ! gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+              echo "::error::target Dify release ${tag} not found"
+              exit 1
+          fi
+          echo "dify_tag=${tag}" >> "$GITHUB_OUTPUT"
+          echo "::notice::target Dify release ${tag}"
+
+      - name: Compatibility check
+        env:
+          DIFY_TAG: ${{ steps.resolve.outputs.dify_tag }}
+        run: node scripts/release-naming.mjs compat-check "$DIFY_TAG"
+
+      - name: Reject duplicate difyctl version
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${difyctlTag}" >/dev/null 2>&1; then
+              echo "::error::difyctl ${version} already released (tag ${difyctlTag} exists); bump cli/package.json version"
+              exit 1
+          fi
+
+  release:
+    name: build + attach standalone binaries (all targets)
+    needs: validate
+    runs-on: depot-ubuntu-24.04
     permissions:
       contents: write
     defaults:
       run:
         shell: bash
         working-directory: ./cli
-
+    env:
+      DIFY_TAG: ${{ needs.validate.outputs.dify_tag }}
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
-          fetch-depth: 0
+          fetch-depth: 1
+
+      - name: Enable cross-arch native prebuilds
+        working-directory: ./
+        run: cat cli/scripts/cross-arch.pnpm.yaml >> pnpm-workspace.yaml
 
       - name: Setup web environment
         uses: ./.github/actions/setup-web
 
+      - name: Export manifest to env
+        run: node scripts/release-naming.mjs github-env >> "$GITHUB_ENV"
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5 # v2.0.2
         with:
-          bun-version: latest
-
-      - name: Read cli/package.json
-        id: manifest
-        run: |
-          version=$(node -p "require('./package.json').version")
-          channel=$(node -p "require('./package.json').difyctl.channel")
-          minDify=$(node -p "require('./package.json').difyctl.compat.minDify")
-          maxDify=$(node -p "require('./package.json').difyctl.compat.maxDify")
-          {
-              echo "version=$version"
-              echo "channel=$channel"
-              echo "minDify=$minDify"
-              echo "maxDify=$maxDify"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Validate manifest
-        run: scripts/release-validate-manifest.sh
-
-      - name: Install cross-arch native prebuilds
-        # Re-installs node_modules with every @napi-rs/keyring platform variant
-        # so `bun build --compile` can embed the right .node into each target.
-        working-directory: ./
-        run: NPM_CONFIG_USERCONFIG="$PWD/cli/scripts/cross-arch.npmrc" pnpm install --frozen-lockfile
+          bun-version-file: cli/.bun-version
 
       - name: Compile standalone binaries (all targets)
-        env:
-          CLI_VERSION: ${{ steps.manifest.outputs.version }}
-          DIFYCTL_CHANNEL: ${{ steps.manifest.outputs.channel }}
-          DIFYCTL_MIN_DIFY: ${{ steps.manifest.outputs.minDify }}
-          DIFYCTL_MAX_DIFY: ${{ steps.manifest.outputs.maxDify }}
         run: |
           DIFYCTL_COMMIT="$(git rev-parse HEAD)" \
           DIFYCTL_BUILD_DATE="$(git log -1 --format=%cI HEAD)" \
             pnpm build:bin
 
       - name: Generate sha256 checksum file
-        env:
-          CLI_VERSION: ${{ steps.manifest.outputs.version }}
         run: scripts/release-write-checksums.sh
 
-      - name: Publish GitHub Release
-        uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8 # v2.3.2
-        with:
-          tag_name: difyctl-v${{ steps.manifest.outputs.version }}
-          name: difyctl ${{ steps.manifest.outputs.version }}
-          prerelease: ${{ steps.manifest.outputs.channel != 'stable' }}
-          generate_release_notes: true
-          fail_on_unmatched_files: true
-          files: |
-            cli/dist/bin/difyctl-v*
+      - name: Attach difyctl assets to Dify release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload "$DIFY_TAG" dist/bin/${tagPrefix}* \
+              --repo "$GITHUB_REPOSITORY" --clobber
+
+      - name: Prune stale difyctl assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          new_set="$(cd dist/bin && ls ${tagPrefix}*)"
+          gh release view "$DIFY_TAG" --repo "$GITHUB_REPOSITORY" \
+              --json assets --jq '.assets[].name' \
+            | { grep -E "^${tagPrefix}" || true; } \
+            | while IFS= read -r name; do
+                if ! printf '%s\n' "$new_set" | grep -qxF -- "$name"; then
+                    echo "::notice::pruning stale asset ${name}"
+                    gh release delete-asset "$DIFY_TAG" "$name" \
+                        --repo "$GITHUB_REPOSITORY" --yes
+                fi
+              done
+
+      - name: Create provenance tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ref="refs/tags/${difyctlTag}"
+          sha="$(git rev-parse HEAD)"
+          status="$(gh api -X POST "repos/${GITHUB_REPOSITORY}/git/refs" \
+                -f ref="$ref" -f sha="$sha" --silent --include 2>/dev/null \
+                | awk 'NR==1 {print $2; exit}' || true)"
+          case "$status" in
+              201) echo "::notice::created ${ref}" ;;
+              422) echo "::notice::tag ${ref} already exists; skipping (immutable)" ;;
+              *)   echo "::error::provenance tag ${ref} not created (HTTP ${status:-unknown})"; exit 1 ;;
+          esac

.github/workflows/cli-tests.yml

@@ -37,8 +37,17 @@ jobs:
       - name: Setup web environment
         uses: ./.github/actions/setup-web
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Validate release manifest
+        if: matrix.os == 'depot-ubuntu-24.04'
+        run: scripts/release-validate-manifest.sh
+
       - name: CI pipeline (typecheck, lint, coverage, build)
-        run: pnpm ci
+        run: pnpm run ci
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' && matrix.os == 'depot-ubuntu-24.04' }}

.github/workflows/deploy-agent.yml

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

.github/workflows/web-tests.yml

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

Makefile

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

api/.env.example

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

api/Dockerfile.dockerignore

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

api/app.py

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

api/app_factory.py

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

api/celery_entrypoint.py

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

api/clients/agent_backend/__init__.py

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

api/clients/agent_backend/event_adapter.py

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

api/clients/agent_backend/fake_client.py

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

api/clients/agent_backend/request_builder.py

@@ -11,13 +11,15 @@ composition-driven.
 
 from __future__ import annotations
 
-from typing import ClassVar, cast
+from collections.abc import Mapping
+from typing import ClassVar
 
 from agenton.compositor import CompositorSessionSnapshot
 from agenton.compositor.schemas import LayerSessionSnapshot
 from agenton.layers import ExitIntent
 from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
 from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
+from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
 from dify_agent.layers.dify_plugin import (
     DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
     DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
@@ -25,6 +27,7 @@ from dify_agent.layers.dify_plugin import (
     DifyPluginLLMLayerConfig,
     DifyPluginToolsLayerConfig,
 )
+from dify_agent.layers.drive import DIFY_DRIVE_LAYER_TYPE_ID, DifyDriveLayerConfig
 from dify_agent.layers.execution_context import (
     DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
     DifyExecutionContextLayerConfig,
@@ -36,10 +39,12 @@ from dify_agent.protocol import (
     DIFY_AGENT_MODEL_LAYER_ID,
     DIFY_AGENT_OUTPUT_LAYER_ID,
     CreateRunRequest,
+    DeferredToolResultsPayload,
     LayerExitSignals,
     RunComposition,
     RunLayerSpec,
     RunPurpose,
+    RuntimeLayerSpec,
 )
 from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator
 
@@ -48,74 +53,15 @@ WORKFLOW_NODE_JOB_PROMPT_LAYER_ID = "workflow_node_job_prompt"
 WORKFLOW_USER_PROMPT_LAYER_ID = "workflow_user_prompt"
 AGENT_APP_USER_PROMPT_LAYER_ID = "agent_app_user_prompt"
 DIFY_EXECUTION_CONTEXT_LAYER_ID = "execution_context"
+DIFY_DRIVE_LAYER_ID = "drive"
 DIFY_PLUGIN_TOOLS_LAYER_ID = "tools"
+DIFY_ASK_HUMAN_LAYER_ID = "ask_human"
 DIFY_SHELL_LAYER_ID = "shell"
 
-# Layer types that hold credentials in their per-run config. These are excluded
-# from the cleanup-replay composition (and from the snapshot that is sent with
-# the cleanup request) because we deliberately do not persist plaintext
-# credentials between runs.
-_CLEANUP_EXCLUDED_LAYER_TYPES: tuple[str, ...] = (
-    DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
-    DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
-)
-
-
-class CleanupLayerSpec(BaseModel):
-    """One layer node replayed by an Agent backend cleanup-only run.
-
-    Cleanup composition cannot include credential-bearing plugin layers, so we
-    persist only the non-plugin layer specs together with the original config.
-    Storing the config (rather than just ``name``/``type``) means cleanup does
-    not depend on the original build-time inputs being re-derivable.
-    """
-
-    name: str
-    type: str
-    deps: dict[str, str] = Field(default_factory=dict)
-    metadata: dict[str, JsonValue] = Field(default_factory=dict)
-    config: JsonValue = None
-
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
-
-def extract_cleanup_layer_specs(composition: RunComposition) -> list[CleanupLayerSpec]:
-    """Project the in-flight composition into the persistable cleanup spec list.
-
-    Plugin layers are intentionally dropped (their configs hold credentials and
-    the lifecycle contract says "do not include an LLM layer" during cleanup).
-    The filtered names must later drive snapshot filtering so the agenton
-    compositor's name-order check still passes for the cleanup run.
-    """
-    excluded = set(_CLEANUP_EXCLUDED_LAYER_TYPES)
-    specs: list[CleanupLayerSpec] = []
-    for layer in composition.layers:
-        if layer.type in excluded:
-            continue
-        config_value: JsonValue = None
-        if isinstance(layer.config, BaseModel):
-            config_value = layer.config.model_dump(mode="json", warnings=False)
-        else:
-            # ``RunLayerSpec.config`` is typed as ``LayerConfigInput`` which
-            # includes ``Mapping[str, object] | bytes``. In the cleanup-replay
-            # pipeline our builder only emits BaseModel-derived configs or
-            # ``None``, so the wider input alias narrows safely here.
-            config_value = cast(JsonValue, layer.config)
-        specs.append(
-            CleanupLayerSpec(
-                name=layer.name,
-                type=layer.type,
-                deps=dict(layer.deps),
-                metadata=dict(layer.metadata),
-                config=config_value,
-            )
-        )
-    return specs
-
 
 def _filter_snapshot_to_specs(
     snapshot: CompositorSessionSnapshot,
-    specs: list[CleanupLayerSpec],
+    specs: list[RuntimeLayerSpec],
 ) -> CompositorSessionSnapshot:
     """Keep only snapshot layers whose names appear in the cleanup spec list.
 
@@ -142,6 +88,30 @@ class AgentBackendModelConfig(BaseModel):
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
 
 
+# ``DifyPluginLLMLayerConfig.model_settings`` is pydantic_ai's ``ModelSettings``
+# TypedDict (closed: unknown keys are rejected, explicit ``None`` values fail the
+# per-field type checks). Agent Soul model settings carry a wider, nullable shape
+# (``stop`` / ``response_format`` plus null-padded fields), so the layer config
+# only receives the keys the runtime contract accepts.
+_AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS = (
+    "temperature",
+    "top_p",
+    "presence_penalty",
+    "frequency_penalty",
+    "max_tokens",
+)
+
+
+def _agent_model_settings(settings: Mapping[str, JsonValue]) -> dict[str, JsonValue] | None:
+    sanitized: dict[str, JsonValue] = {
+        key: settings[key] for key in _AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS if settings.get(key) is not None
+    }
+    stop = settings.get("stop")
+    if isinstance(stop, list) and stop:
+        sanitized["stop_sequences"] = stop
+    return sanitized or None
+
+
 class AgentBackendOutputConfig(BaseModel):
     """API-side structured output declaration for the conventional output layer.
 
@@ -169,11 +139,21 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
     idempotency_key: str | None = None
     output: AgentBackendOutputConfig | None = None
     tools: DifyPluginToolsLayerConfig | None = None
+    # Drive Skills & Files declaration (dify.drive) — an index the agent pulls
+    # through the back proxy, never inline content; see AGENT_DRIVE_MANIFEST_ENABLED.
+    drive_config: DifyDriveLayerConfig | None = None
+    # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
+    # the Agent Soul configures human involvement; a deferred call ends the run and
+    # the workflow pauses via the existing HITL form mechanism (ENG-635).
+    ask_human_config: DifyAskHumanLayerConfig | None = None
     # Inject the sandboxed shell layer (dify.shell). Requires the agent backend
     # to be wired with a shellctl entrypoint; see configs AGENT_SHELL_ENABLED.
     include_shell: bool = False
     shell_config: DifyShellLayerConfig | None = None
     session_snapshot: CompositorSessionSnapshot | None = None
+    # Human tool results fed back into a continuation run after a HITL submission
+    # (ENG-638). Keyed by the original deferred tool_call_id.
+    deferred_tool_results: DeferredToolResultsPayload | None = None
     include_history: bool = True
     suspend_on_exit: bool = True
     metadata: dict[str, JsonValue] = Field(default_factory=dict)
@@ -205,11 +185,20 @@ class AgentBackendAgentAppRunInput(BaseModel):
     idempotency_key: str | None = None
     output: AgentBackendOutputConfig | None = None
     tools: DifyPluginToolsLayerConfig | None = None
+    # Drive Skills & Files declaration (dify.drive) — an index the agent pulls
+    # through the back proxy, never inline content; see AGENT_DRIVE_MANIFEST_ENABLED.
+    drive_config: DifyDriveLayerConfig | None = None
+    # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
+    # the Agent Soul configures human involvement (ENG-635).
+    ask_human_config: DifyAskHumanLayerConfig | None = None
     # Inject the sandboxed shell layer (dify.shell). Requires the agent backend
     # to be wired with a shellctl entrypoint; see configs AGENT_SHELL_ENABLED.
     include_shell: bool = False
     shell_config: DifyShellLayerConfig | None = None
     session_snapshot: CompositorSessionSnapshot | None = None
+    # Human tool results fed back into a continuation run after a HITL submission
+    # (ENG-638). Keyed by the original deferred tool_call_id.
+    deferred_tool_results: DeferredToolResultsPayload | None = None
     include_history: bool = True
     suspend_on_exit: bool = True
     metadata: dict[str, JsonValue] = Field(default_factory=dict)
@@ -263,6 +252,18 @@ class AgentBackendRunRequestBuilder:
             ]
         )
 
+        if run_input.drive_config is not None:
+            # Drive Skills & Files declaration (dify.drive): a config-only index;
+            # the agent pulls listed entries through the back proxy by drive_ref.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_DRIVE_LAYER_ID,
+                    type=DIFY_DRIVE_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.drive_config,
+                )
+            )
+
         if run_input.include_history:
             layers.append(
                 RunLayerSpec(
@@ -283,7 +284,7 @@ class AgentBackendRunRequestBuilder:
                     model_provider=run_input.model.model_provider,
                     model=run_input.model.model,
                     credentials=run_input.model.credentials,
-                    model_settings=run_input.model.model_settings or None,
+                    model_settings=_agent_model_settings(run_input.model.model_settings),
                 ),
             )
         )
@@ -299,13 +300,28 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.ask_human_config is not None:
+            # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends
+            # the run with a deferred_tool_call; the caller pauses (workflow HITL) and
+            # later resumes with deferred_tool_results. Needs the history layer above.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_ASK_HUMAN_LAYER_ID,
+                    type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.ask_human_config,
+                )
+            )
+
         if run_input.include_shell:
-            # Sandboxed bash workspace (dify.shell). The layer declares NoLayerDeps,
-            # so the spec carries no deps; shellctl connection is server-injected.
+            # Sandboxed bash workspace (dify.shell). Depends on execution_context so
+            # the agent server can mint per-command Agent Stub env (back proxy);
+            # shellctl connection itself is server-injected.
             layers.append(
                 RunLayerSpec(
                     name=DIFY_SHELL_LAYER_ID,
                     type=DIFY_SHELL_LAYER_TYPE_ID,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
                     metadata=run_input.metadata,
                     config=run_input.shell_config or DifyShellLayerConfig(),
                 )
@@ -331,6 +347,7 @@ class AgentBackendRunRequestBuilder:
             idempotency_key=run_input.idempotency_key,
             metadata=run_input.metadata,
             session_snapshot=run_input.session_snapshot,
+            deferred_tool_results=run_input.deferred_tool_results,
             on_exit=LayerExitSignals(
                 default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
             ),
@@ -340,7 +357,7 @@ class AgentBackendRunRequestBuilder:
         self,
         *,
         session_snapshot: CompositorSessionSnapshot,
-        composition_layer_specs: list[CleanupLayerSpec],
+        runtime_layer_specs: list[RuntimeLayerSpec],
         idempotency_key: str | None = None,
         metadata: dict[str, JsonValue] | None = None,
     ) -> CreateRunRequest:
@@ -353,9 +370,9 @@ class AgentBackendRunRequestBuilder:
         composition and the snapshot before submission because their configs
         require credentials that are not persisted between runs.
         """
-        if not composition_layer_specs:
+        if not runtime_layer_specs:
             raise ValueError(
-                "build_cleanup_request requires composition_layer_specs; an empty "
+                "build_cleanup_request requires runtime_layer_specs; an empty "
                 "composition would fail the agent backend's snapshot validation."
             )
         request_metadata = dict(metadata or {})
@@ -368,9 +385,9 @@ class AgentBackendRunRequestBuilder:
                 metadata=dict(spec.metadata),
                 config=spec.config,
             )
-            for spec in composition_layer_specs
+            for spec in runtime_layer_specs
         ]
-        filtered_snapshot = _filter_snapshot_to_specs(session_snapshot, composition_layer_specs)
+        filtered_snapshot = _filter_snapshot_to_specs(session_snapshot, runtime_layer_specs)
         return CreateRunRequest(
             composition=RunComposition(layers=layers),
             purpose="workflow_node",
@@ -416,6 +433,18 @@ class AgentBackendRunRequestBuilder:
             ]
         )
 
+        if run_input.drive_config is not None:
+            # Drive Skills & Files declaration (dify.drive): a config-only index;
+            # the agent pulls listed entries through the back proxy by drive_ref.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_DRIVE_LAYER_ID,
+                    type=DIFY_DRIVE_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.drive_config,
+                )
+            )
+
         if run_input.include_history:
             layers.append(
                 RunLayerSpec(
@@ -437,7 +466,7 @@ class AgentBackendRunRequestBuilder:
                         model_provider=run_input.model.model_provider,
                         model=run_input.model.model,
                         credentials=run_input.model.credentials,
-                        model_settings=run_input.model.model_settings or None,
+                        model_settings=_agent_model_settings(run_input.model.model_settings),
                     ),
                 ),
             ]
@@ -454,13 +483,28 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.ask_human_config is not None:
+            # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends
+            # the run with a deferred_tool_call; the caller pauses (workflow HITL) and
+            # later resumes with deferred_tool_results. Needs the history layer above.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_ASK_HUMAN_LAYER_ID,
+                    type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.ask_human_config,
+                )
+            )
+
         if run_input.include_shell:
-            # Sandboxed bash workspace (dify.shell). The layer declares NoLayerDeps,
-            # so the spec carries no deps; shellctl connection is server-injected.
+            # Sandboxed bash workspace (dify.shell). Depends on execution_context so
+            # the agent server can mint per-command Agent Stub env (back proxy);
+            # shellctl connection itself is server-injected.
             layers.append(
                 RunLayerSpec(
                     name=DIFY_SHELL_LAYER_ID,
                     type=DIFY_SHELL_LAYER_TYPE_ID,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
                     metadata=run_input.metadata,
                     config=run_input.shell_config or DifyShellLayerConfig(),
                 )
@@ -486,6 +530,7 @@ class AgentBackendRunRequestBuilder:
             idempotency_key=run_input.idempotency_key,
             metadata=run_input.metadata,
             session_snapshot=run_input.session_snapshot,
+            deferred_tool_results=run_input.deferred_tool_results,
             on_exit=LayerExitSignals(
                 default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
             ),

api/clients/agent_backend/workspace_files_client.py

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

api/commands/__init__.py

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

api/commands/data_migrate.py

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

api/commands/plugin.py

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

api/configs/enterprise/__init__.py

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

api/configs/extra/agent_backend_config.py

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

api/configs/feature/__init__.py

@@ -943,12 +943,18 @@ class AuthConfig(BaseSettings):
         default=True,
     )
 
-    OPENAPI_RATE_LIMIT_PER_TOKEN: PositiveInt = Field(
+    OPENAPI_RATE_LIMIT_PER_TOKEN: NonNegativeInt = Field(
         description="Per-token rate limit on /openapi/v1/* (requests per minute). "
-        "Bucket keyed on sha256(token), shared across api replicas via Redis.",
+        "Bucket keyed on sha256(token), shared across api replicas via Redis. "
+        "Set to 0 to disable the per-token limit entirely.",
         default=60,
     )
 
+    DEVICE_FLOW_APPROVE_RATE_LIMIT_PER_HOUR: PositiveInt = Field(
+        description="Max device-flow approve requests per session per hour on /openapi/oauth/device/approve.",
+        default=10,
+    )
+
 
 class ModerationConfig(BaseSettings):
     """

api/configs/remote_settings_sources/nacos/http_request.py

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

api/context/execution_context.py

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

api/controllers/common/controller_schemas.py

@@ -62,7 +62,7 @@ class WorkflowListQuery(BaseModel):
 
 class WorkflowRunPayload(BaseModel):
     inputs: dict[str, Any]
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
 
 
 class WorkflowUpdatePayload(BaseModel):

api/controllers/common/errors.py

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

api/controllers/common/fields.py

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

api/controllers/common/schema.py

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

api/controllers/common/wraps.py

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

api/controllers/console/__init__.py

@@ -53,7 +53,8 @@ from .app import (
     agent,
     agent_app_access,
     agent_app_feature,
-    agent_app_workspace,
+    agent_app_sandbox,
+    agent_drive_inspector,
     annotation,
     app,
     audio,
@@ -122,6 +123,7 @@ from .explore import (
     saved_message,
     trial,
 )
+from .snippets import snippet_workflow, snippet_workflow_draft_variable
 from .socketio import workflow as socketio_workflow
 
 # Import tag controllers
@@ -137,6 +139,7 @@ from .workspace import (
     model_providers,
     models,
     plugin,
+    snippets,
     tool_providers,
     trigger_providers,
     workspace,
@@ -151,8 +154,9 @@ __all__ = [
     "agent",
     "agent_app_access",
     "agent_app_feature",
-    "agent_app_workspace",
+    "agent_app_sandbox",
     "agent_composer",
+    "agent_drive_inspector",
     "agent_providers",
     "agent_roster",
     "annotation",
@@ -212,6 +216,9 @@ __all__ = [
     "saved_message",
     "setup",
     "site",
+    "snippet_workflow",
+    "snippet_workflow_draft_variable",
+    "snippets",
     "socketio_workflow",
     "spec",
     "statistic",

api/controllers/console/agent/app_helpers.py

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

api/controllers/console/agent/composer.py

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

api/controllers/console/agent/roster.py

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

api/controllers/console/app/advanced_prompt_template.py

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

api/controllers/console/app/agent.py

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

api/controllers/console/app/agent_app_access.py

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

api/controllers/console/app/agent_app_feature.py

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

api/controllers/console/app/agent_app_sandbox.py

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

api/controllers/console/app/agent_app_workspace.py

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

api/controllers/console/app/agent_drive_inspector.py

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

api/controllers/console/app/annotation.py

@@ -6,7 +6,7 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, TypeAdapter, field_validator
 
 from controllers.common.errors import NoFileUploadedError, TooManyFilesError
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -24,6 +24,7 @@ from fields.annotation_fields import (
     AnnotationHitHistoryList,
     AnnotationList,
 )
+from fields.base import ResponseModel
 from libs.helper import uuid_value
 from libs.login import login_required
 from services.annotation_service import (
@@ -56,7 +57,10 @@ class CreateAnnotationPayload(BaseModel):
     question: str | None = Field(default=None, description="Question text")
     answer: str | None = Field(default=None, description="Answer text")
     content: str | None = Field(default=None, description="Content text")
-    annotation_reply: dict[str, Any] | None = Field(default=None, description="Annotation reply data")
+    annotation_reply: dict[str, Any] | None = Field(
+        default=None,
+        description="Annotation reply data",
+    )
 
     @field_validator("message_id")
     @classmethod
@@ -70,13 +74,18 @@ class UpdateAnnotationPayload(BaseModel):
     question: str | None = None
     answer: str | None = None
     content: str | None = None
-    annotation_reply: dict[str, Any] | None = None
+    annotation_reply: dict[str, Any] | None = Field(default=None)
 
 
 class AnnotationReplyStatusQuery(BaseModel):
     action: Literal["enable", "disable"]
 
 
+class AnnotationHitHistoryListQuery(BaseModel):
+    page: int = Field(default=1, ge=1, description="Page number")
+    limit: int = Field(default=20, ge=1, description="Page size")
+
+
 class AnnotationFilePayload(BaseModel):
     message_id: str = Field(..., description="Message ID")
 
@@ -86,6 +95,25 @@ class AnnotationFilePayload(BaseModel):
         return uuid_value(value)
 
 
+class AnnotationJobStatusResponse(ResponseModel):
+    job_id: str | None = None
+    job_status: str | None = None
+    error_msg: str | None = None
+    record_count: int | None = None
+
+
+class AnnotationEmbeddingModelResponse(ResponseModel):
+    embedding_provider_name: str | None = None
+    embedding_model_name: str | None = None
+
+
+class AnnotationSettingResponse(ResponseModel):
+    id: str | None = None
+    enabled: bool
+    score_threshold: float | None = None
+    embedding_model: AnnotationEmbeddingModelResponse | None = None
+
+
 register_schema_models(
     console_ns,
     Annotation,
@@ -99,8 +127,19 @@ register_schema_models(
     CreateAnnotationPayload,
     UpdateAnnotationPayload,
     AnnotationReplyStatusQuery,
+    AnnotationHitHistoryListQuery,
     AnnotationFilePayload,
 )
+register_response_schema_models(
+    console_ns,
+    Annotation,
+    AnnotationList,
+    AnnotationExportList,
+    AnnotationHitHistory,
+    AnnotationHitHistoryList,
+    AnnotationJobStatusResponse,
+    AnnotationSettingResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotation-reply/<string:action>")
@@ -109,7 +148,7 @@ class AnnotationReplyActionApi(Resource):
     @console_ns.doc(description="Enable or disable annotation reply for an app")
     @console_ns.doc(params={"app_id": "Application ID", "action": "Action to perform (enable/disable)"})
     @console_ns.expect(console_ns.models[AnnotationReplyPayload.__name__])
-    @console_ns.response(200, "Action completed successfully")
+    @console_ns.response(200, "Action completed successfully", console_ns.models[AnnotationJobStatusResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -136,7 +175,11 @@ class AppAnnotationSettingDetailApi(Resource):
     @console_ns.doc("get_annotation_setting")
     @console_ns.doc(description="Get annotation settings for an app")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Annotation settings retrieved successfully")
+    @console_ns.response(
+        200,
+        "Annotation settings retrieved successfully",
+        console_ns.models[AnnotationSettingResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -153,7 +196,7 @@ class AppAnnotationSettingUpdateApi(Resource):
     @console_ns.doc(description="Update annotation settings for an app")
     @console_ns.doc(params={"app_id": "Application ID", "annotation_setting_id": "Annotation setting ID"})
     @console_ns.expect(console_ns.models[AnnotationSettingUpdatePayload.__name__])
-    @console_ns.response(200, "Settings updated successfully")
+    @console_ns.response(200, "Settings updated successfully", console_ns.models[AnnotationSettingResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -176,7 +219,11 @@ class AnnotationReplyActionStatusApi(Resource):
     @console_ns.doc("get_annotation_reply_action_status")
     @console_ns.doc(description="Get status of annotation reply action job")
     @console_ns.doc(params={"app_id": "Application ID", "job_id": "Job ID", "action": "Action type"})
-    @console_ns.response(200, "Job status retrieved successfully")
+    @console_ns.response(
+        200,
+        "Job status retrieved successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -204,8 +251,8 @@ class AnnotationApi(Resource):
     @console_ns.doc("list_annotations")
     @console_ns.doc(description="Get annotations for an app with pagination")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[AnnotationListQuery.__name__])
-    @console_ns.response(200, "Annotations retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(AnnotationListQuery))
+    @console_ns.response(200, "Annotations retrieved successfully", console_ns.models[AnnotationList.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -257,6 +304,7 @@ class AnnotationApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @console_ns.response(204, "Annotations deleted successfully")
     def delete(self, app_id: UUID):
 
         # Use request.args.getlist to get annotation_ids array directly
@@ -335,6 +383,7 @@ class AnnotationUpdateDeleteApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @console_ns.response(204, "Annotation deleted successfully")
     def delete(self, app_id: UUID, annotation_id: UUID):
         AppAnnotationService.delete_app_annotation(str(app_id), str(annotation_id))
         return "", 204
@@ -345,7 +394,11 @@ class AnnotationBatchImportApi(Resource):
     @console_ns.doc("batch_import_annotations")
     @console_ns.doc(description="Batch import annotations from CSV file with rate limiting and security checks")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Batch import started successfully")
+    @console_ns.response(
+        200,
+        "Batch import started successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(400, "No file uploaded or too many files")
     @console_ns.response(413, "File too large")
@@ -398,7 +451,11 @@ class AnnotationBatchImportStatusApi(Resource):
     @console_ns.doc("get_batch_import_status")
     @console_ns.doc(description="Get status of batch import job")
     @console_ns.doc(params={"app_id": "Application ID", "job_id": "Job ID"})
-    @console_ns.response(200, "Job status retrieved successfully")
+    @console_ns.response(
+        200,
+        "Job status retrieved successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -424,11 +481,7 @@ class AnnotationHitHistoryListApi(Resource):
     @console_ns.doc("list_annotation_hit_histories")
     @console_ns.doc(description="Get hit histories for an annotation")
     @console_ns.doc(params={"app_id": "Application ID", "annotation_id": "Annotation ID"})
-    @console_ns.expect(
-        console_ns.parser()
-        .add_argument("page", type=int, location="args", default=1, help="Page number")
-        .add_argument("limit", type=int, location="args", default=20, help="Page size")
-    )
+    @console_ns.doc(params=query_params_from_model(AnnotationHitHistoryListQuery))
     @console_ns.response(
         200,
         "Hit histories retrieved successfully",

api/controllers/console/app/app.py

@@ -1,8 +1,9 @@
 import logging
 import re
 import uuid
+from collections.abc import Sequence
 from datetime import datetime
-from typing import Any, Literal
+from typing import Any, Literal, cast
 
 from flask import request
 from flask_restx import Resource
@@ -14,7 +15,12 @@ from werkzeug.exceptions import BadRequest
 
 from controllers.common.fields import RedirectUrlResponse, SimpleResultResponse
 from controllers.common.helpers import FileInfo
-from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
+from controllers.common.schema import (
+    query_params_from_model,
+    register_enum_models,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model, with_session
 from controllers.console.workspace.models import LoadBalancingPayload
@@ -36,12 +42,12 @@ from core.trigger.constants import TRIGGER_NODE_TYPES
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from graphon.enums import WorkflowExecutionStatus
-from libs.helper import build_icon_url, to_timestamp
+from libs.helper import build_icon_url, dump_response, to_timestamp
 from libs.login import login_required
 from models import Account, App, DatasetPermissionEnum, Workflow
 from models.model import IconType
 from services.app_dsl_service import AppDslService
-from services.app_service import AppListParams, AppService, CreateAppParams
+from services.app_service import AppListParams, AppListSortBy, AppService, CreateAppParams, StarredAppListParams
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import ImportMode, ImportStatus
 from services.entities.knowledge_entities.knowledge_entities import (
@@ -58,22 +64,27 @@ from services.entities.knowledge_entities.knowledge_entities import (
 )
 from services.feature_service import FeatureService
 
-ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"]
+ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "advanced-chat", "workflow", "completion"]
 
 register_enum_models(console_ns, IconType)
 
 _logger = logging.getLogger(__name__)
 _TAG_IDS_BRACKET_PATTERN = re.compile(r"^tag_ids\[(\d+)\]$")
+_CREATOR_IDS_BRACKET_PATTERN = re.compile(r"^creator_ids\[(\d+)\]$")
+AppListMode = Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"]
 
 
-class AppListQuery(BaseModel):
+class AppListBaseQuery(BaseModel):
     page: int = Field(default=1, ge=1, le=99999, description="Page number (1-99999)")
     limit: int = Field(default=20, ge=1, le=100, description="Page size (1-100)")
-    mode: Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"] = Field(
-        default="all", description="App mode filter"
+    mode: AppListMode = Field(default=cast(AppListMode, "all"), description="App mode filter")
+    sort_by: AppListSortBy = Field(
+        default="last_modified",
+        description="Sort apps by last modified, recently created, or earliest created",
     )
     name: str | None = Field(default=None, description="Filter by app name")
     tag_ids: list[str] | None = Field(default=None, description="Filter by tag IDs")
+    creator_ids: list[str] | None = Field(default=None, description="Filter by creator account IDs")
     is_created_by_me: bool | None = Field(default=None, description="Filter by creator")
 
     @field_validator("tag_ids", mode="before")
@@ -94,10 +105,37 @@ class AppListQuery(BaseModel):
         except ValueError as exc:
             raise ValueError("Invalid UUID format in tag_ids.") from exc
 
+    @field_validator("creator_ids", mode="before")
+    @classmethod
+    def validate_creator_ids(cls, value: list[str] | None) -> list[str] | None:
+        if not value:
+            return None
+
+        if not isinstance(value, list):
+            raise ValueError("Unsupported creator_ids type.")
+
+        items = [str(item).strip() for item in value if item and str(item).strip()]
+        if not items:
+            return None
+
+        try:
+            return [str(uuid.UUID(item)) for item in items]
+        except ValueError as exc:
+            raise ValueError("Invalid UUID format in creator_ids.") from exc
+
+
+class AppListQuery(AppListBaseQuery):
+    pass
+
+
+class StarredAppListQuery(AppListBaseQuery):
+    pass
+
 
 def _normalize_app_list_query_args(query_args: MultiDict[str, str]) -> dict[str, str | list[str]]:
     normalized: dict[str, str | list[str]] = {}
     indexed_tag_ids: list[tuple[int, str]] = []
+    indexed_creator_ids: list[tuple[int, str]] = []
 
     for key in query_args:
         match = _TAG_IDS_BRACKET_PATTERN.fullmatch(key)
@@ -105,12 +143,19 @@ def _normalize_app_list_query_args(query_args: MultiDict[str, str]) -> dict[str,
             indexed_tag_ids.extend((int(match.group(1)), value) for value in query_args.getlist(key))
             continue
 
+        match = _CREATOR_IDS_BRACKET_PATTERN.fullmatch(key)
+        if match:
+            indexed_creator_ids.extend((int(match.group(1)), value) for value in query_args.getlist(key))
+            continue
+
         value = query_args.get(key)
         if value is not None:
             normalized[key] = value
 
     if indexed_tag_ids:
         normalized["tag_ids"] = [value for _, value in sorted(indexed_tag_ids)]
+    if indexed_creator_ids:
+        normalized["creator_ids"] = [value for _, value in sorted(indexed_creator_ids)]
 
     return normalized
 
@@ -118,9 +163,7 @@ def _normalize_app_list_query_args(query_args: MultiDict[str, str]) -> dict[str,
 class CreateAppPayload(BaseModel):
     name: str = Field(..., min_length=1, description="App name")
     description: str | None = Field(default=None, description="App description (max 400 chars)", max_length=400)
-    mode: Literal["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"] = Field(
-        ..., description="App mode"
-    )
+    mode: Literal["chat", "agent-chat", "advanced-chat", "workflow", "completion"] = Field(..., description="App mode")
     icon_type: IconType | None = Field(default=None, description="Icon type")
     icon: str | None = Field(default=None, description="Icon")
     icon_background: str | None = Field(default=None, description="Icon background color")
@@ -179,6 +222,11 @@ class AppTracePayload(BaseModel):
         return value
 
 
+class AppTraceResponse(ResponseModel):
+    enabled: bool
+    tracing_provider: str | None = None
+
+
 type JSONValue = Any
 
 
@@ -350,6 +398,13 @@ class AppPartial(ResponseModel):
     create_user_name: str | None = None
     author_name: str | None = None
     has_draft_trigger: bool | None = None
+    # For Agent App type: the roster Agent backing this app (None otherwise).
+    bound_agent_id: str | None = None
+    # For Agent App responses exposed through /agent.
+    app_id: str | None = None
+    role: str | None = None
+    active_config_is_published: bool = False
+    is_starred: bool = False
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -400,6 +455,10 @@ class AppDetailWithSite(AppDetail):
     site: Site | None = None
     # For Agent App type: the roster Agent backing this app (None otherwise).
     bound_agent_id: str | None = None
+    # For Agent App responses exposed through /agent.
+    app_id: str | None = None
+    role: str | None = None
+    active_config_is_published: bool = False
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -419,12 +478,54 @@ class AppExportResponse(ResponseModel):
     data: str
 
 
+def _enrich_app_list_items(session: Session, *, apps: Sequence[App], tenant_id: str) -> None:
+    if FeatureService.get_system_features().webapp_auth.enabled:
+        app_ids = [str(app.id) for app in apps]
+        res = EnterpriseService.WebAppAuth.batch_get_app_access_mode_by_id(app_ids=app_ids)
+        if len(res) != len(app_ids):
+            raise BadRequest("Invalid app id in webapp auth")
+
+        for app in apps:
+            if str(app.id) in res:
+                app.access_mode = res[str(app.id)].access_mode
+
+    workflow_capable_app_ids = [str(app.id) for app in apps if app.mode in {"workflow", "advanced-chat"}]
+    draft_trigger_app_ids: set[str] = set()
+    if workflow_capable_app_ids:
+        draft_workflows = (
+            session.execute(
+                select(Workflow).where(
+                    Workflow.version == Workflow.VERSION_DRAFT,
+                    Workflow.app_id.in_(workflow_capable_app_ids),
+                    Workflow.tenant_id == tenant_id,
+                )
+            )
+            .scalars()
+            .all()
+        )
+        trigger_node_types = TRIGGER_NODE_TYPES
+        for workflow in draft_workflows:
+            node_id = None
+            try:
+                for node_id, node_data in workflow.walk_nodes():
+                    if node_data.get("type") in trigger_node_types:
+                        draft_trigger_app_ids.add(str(workflow.app_id))
+                        break
+            except Exception:
+                _logger.exception("error while walking nodes, workflow_id=%s, node_id=%s", workflow.id, node_id)
+                continue
+
+    for app in apps:
+        app.has_draft_trigger = str(app.id) in draft_trigger_app_ids
+
+
 register_enum_models(console_ns, RetrievalMethod, WorkflowExecutionStatus, DatasetPermissionEnum)
-register_response_schema_models(console_ns, RedirectUrlResponse, SimpleResultResponse)
+register_response_schema_models(console_ns, AppTraceResponse, RedirectUrlResponse, SimpleResultResponse)
 
 register_schema_models(
     console_ns,
     AppListQuery,
+    StarredAppListQuery,
     CreateAppPayload,
     UpdateAppPayload,
     CopyAppPayload,
@@ -468,7 +569,7 @@ register_schema_models(
 class AppListApi(Resource):
     @console_ns.doc("list_apps")
     @console_ns.doc(description="Get list of applications with pagination and filtering")
-    @console_ns.expect(console_ns.models[AppListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(AppListQuery))
     @console_ns.response(200, "Success", console_ns.models[AppPagination.__name__])
     @setup_required
     @login_required
@@ -484,8 +585,10 @@ class AppListApi(Resource):
             page=args.page,
             limit=args.limit,
             mode=args.mode,
+            sort_by=args.sort_by,
             name=args.name,
             tag_ids=args.tag_ids,
+            creator_ids=args.creator_ids,
             is_created_by_me=args.is_created_by_me,
         )
 
@@ -496,46 +599,7 @@ class AppListApi(Resource):
             empty = AppPagination(page=args.page, limit=args.limit, total=0, has_more=False, data=[])
             return empty.model_dump(mode="json"), 200
 
-        if FeatureService.get_system_features().webapp_auth.enabled:
-            app_ids = [str(app.id) for app in app_pagination.items]
-            res = EnterpriseService.WebAppAuth.batch_get_app_access_mode_by_id(app_ids=app_ids)
-            if len(res) != len(app_ids):
-                raise BadRequest("Invalid app id in webapp auth")
-
-            for app in app_pagination.items:
-                if str(app.id) in res:
-                    app.access_mode = res[str(app.id)].access_mode
-
-        workflow_capable_app_ids = [
-            str(app.id) for app in app_pagination.items if app.mode in {"workflow", "advanced-chat"}
-        ]
-        draft_trigger_app_ids: set[str] = set()
-        if workflow_capable_app_ids:
-            draft_workflows = (
-                session.execute(
-                    select(Workflow).where(
-                        Workflow.version == Workflow.VERSION_DRAFT,
-                        Workflow.app_id.in_(workflow_capable_app_ids),
-                        Workflow.tenant_id == current_tenant_id,
-                    )
-                )
-                .scalars()
-                .all()
-            )
-            trigger_node_types = TRIGGER_NODE_TYPES
-            for workflow in draft_workflows:
-                node_id = None
-                try:
-                    for node_id, node_data in workflow.walk_nodes():
-                        if node_data.get("type") in trigger_node_types:
-                            draft_trigger_app_ids.add(str(workflow.app_id))
-                            break
-                except Exception:
-                    _logger.exception("error while walking nodes, workflow_id=%s, node_id=%s", workflow.id, node_id)
-                    continue
-
-        for app in app_pagination.items:
-            app.has_draft_trigger = str(app.id) in draft_trigger_app_ids
+        _enrich_app_list_items(session, apps=app_pagination.items, tenant_id=current_tenant_id)
 
         pagination_model = AppPagination.model_validate(app_pagination, from_attributes=True)
         return pagination_model.model_dump(mode="json"), 200
@@ -543,7 +607,7 @@ class AppListApi(Resource):
     @console_ns.doc("create_app")
     @console_ns.doc(description="Create a new application")
     @console_ns.expect(console_ns.models[CreateAppPayload.__name__])
-    @console_ns.response(201, "App created successfully", console_ns.models[AppDetail.__name__])
+    @console_ns.response(201, "App created successfully", console_ns.models[AppDetailWithSite.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
@@ -567,10 +631,82 @@ class AppListApi(Resource):
 
         app_service = AppService()
         app = app_service.create_app(current_tenant_id, params, current_user)
-        app_detail = AppDetail.model_validate(app, from_attributes=True)
+        app_detail = AppDetailWithSite.model_validate(app, from_attributes=True)
         return app_detail.model_dump(mode="json"), 201
 
 
+@console_ns.route("/apps/starred")
+class StarredAppListApi(Resource):
+    @console_ns.doc("list_starred_apps")
+    @console_ns.doc(description="Get applications starred by the current account")
+    @console_ns.doc(params=query_params_from_model(StarredAppListQuery))
+    @console_ns.response(200, "Success", console_ns.models[AppPagination.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_session(write=False)
+    @with_current_user_id
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user_id: str, session: Session):
+        args = StarredAppListQuery.model_validate(_normalize_app_list_query_args(request.args))
+        params = StarredAppListParams(
+            page=args.page,
+            limit=args.limit,
+            mode=args.mode,
+            sort_by=args.sort_by,
+            name=args.name,
+            tag_ids=args.tag_ids,
+            creator_ids=args.creator_ids,
+            is_created_by_me=args.is_created_by_me,
+        )
+
+        app_pagination = AppService().get_paginate_starred_apps(current_user_id, current_tenant_id, params)
+        if not app_pagination:
+            empty = AppPagination(page=args.page, limit=args.limit, total=0, has_more=False, data=[])
+            return empty.model_dump(mode="json"), 200
+
+        _enrich_app_list_items(session, apps=app_pagination.items, tenant_id=current_tenant_id)
+
+        pagination_model = AppPagination.model_validate(app_pagination, from_attributes=True)
+        return pagination_model.model_dump(mode="json"), 200
+
+
+@console_ns.route("/apps/<uuid:app_id>/star")
+class AppStarApi(Resource):
+    @console_ns.doc("star_app")
+    @console_ns.doc(description="Star an application for the current account")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
+    @console_ns.response(404, "App not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_current_user_id
+    @with_session
+    @get_app_model(mode=None)
+    def post(self, session: Session, current_user_id: str, app_model: App):
+        AppService.star_app(session, app=app_model, account_id=current_user_id)
+        return dump_response(SimpleResultResponse, {"result": "success"})
+
+    @console_ns.doc("unstar_app")
+    @console_ns.doc(description="Remove the current account's star from an application")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
+    @console_ns.response(404, "App not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_current_user_id
+    @with_session
+    @get_app_model(mode=None)
+    def delete(self, session: Session, current_user_id: str, app_model: App):
+        AppService.unstar_app(session, app=app_model, account_id=current_user_id)
+        return dump_response(SimpleResultResponse, {"result": "success"})
+
+
 @console_ns.route("/apps/<uuid:app_id>")
 class AppApi(Resource):
     @console_ns.doc("get_app_detail")
@@ -590,7 +726,7 @@ class AppApi(Resource):
 
         if FeatureService.get_system_features().webapp_auth.enabled:
             app_setting = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_id=str(app_model.id))
-            app_model.access_mode = app_setting.access_mode  # type: ignore[attr-defined]
+            app_model.access_mode = app_setting.access_mode
 
         response_model = AppDetailWithSite.model_validate(app_model, from_attributes=True)
         return response_model.model_dump(mode="json")
@@ -709,7 +845,7 @@ class AppExportApi(Resource):
     @console_ns.doc("export_app")
     @console_ns.doc(description="Export application configuration as DSL")
     @console_ns.doc(params={"app_id": "Application ID to export"})
-    @console_ns.expect(console_ns.models[AppExportQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(AppExportQuery))
     @console_ns.response(200, "App exported successfully", console_ns.models[AppExportResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @get_app_model
@@ -784,7 +920,7 @@ class AppIconApi(Resource):
     @console_ns.doc(description="Update application icon")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AppIconPayload.__name__])
-    @console_ns.response(200, "Icon updated successfully")
+    @console_ns.response(200, "Icon updated successfully", console_ns.models[AppDetail.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -854,7 +990,11 @@ class AppTraceApi(Resource):
     @console_ns.doc("get_app_trace")
     @console_ns.doc(description="Get app tracing configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Trace configuration retrieved successfully")
+    @console_ns.response(
+        200,
+        "Trace configuration retrieved successfully",
+        console_ns.models[AppTraceResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/app/audio.py

@@ -1,12 +1,14 @@
 import logging
+from typing import Any
 
 from flask import request
-from flask_restx import Resource, fields
-from pydantic import BaseModel, Field
+from flask_restx import Resource
+from pydantic import BaseModel, Field, RootModel
 from werkzeug.exceptions import InternalServerError
 
 import services
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import AudioBinaryResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     AppUnavailableError,
@@ -51,7 +53,12 @@ class AudioTranscriptResponse(BaseModel):
     text: str = Field(description="Transcribed text from audio")
 
 
+class TextToSpeechVoiceListResponse(RootModel[list[dict[str, Any]]]):
+    root: list[dict[str, Any]]
+
+
 register_schema_models(console_ns, AudioTranscriptResponse, TextToSpeechPayload, TextToSpeechVoiceQuery)
+register_response_schema_models(console_ns, AudioBinaryResponse, TextToSpeechVoiceListResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/audio-to-text")
@@ -113,7 +120,11 @@ class ChatMessageTextApi(Resource):
     @console_ns.doc(description="Convert text to speech for chat messages")
     @console_ns.doc(params={"app_id": "App ID"})
     @console_ns.expect(console_ns.models[TextToSpeechPayload.__name__])
-    @console_ns.response(200, "Text to speech conversion successful")
+    @console_ns.response(
+        200,
+        "Text to speech conversion successful",
+        console_ns.models[AudioBinaryResponse.__name__],
+    )
     @console_ns.response(400, "Bad request - Invalid parameters")
     @get_app_model
     @setup_required
@@ -162,9 +173,11 @@ class TextModesApi(Resource):
     @console_ns.doc("get_text_to_speech_voices")
     @console_ns.doc(description="Get available TTS voices for a specific language")
     @console_ns.doc(params={"app_id": "App ID"})
-    @console_ns.expect(console_ns.models[TextToSpeechVoiceQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TextToSpeechVoiceQuery))
     @console_ns.response(
-        200, "TTS voices retrieved successfully", fields.List(fields.Raw(description="Available voices"))
+        200,
+        "TTS voices retrieved successfully",
+        console_ns.models[TextToSpeechVoiceListResponse.__name__],
     )
     @console_ns.response(400, "Invalid language parameter")
     @get_app_model

api/controllers/console/app/completion.py

@@ -1,5 +1,6 @@
 import logging
 from typing import Any, Literal
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -7,9 +8,10 @@ from pydantic import BaseModel, Field, field_validator
 from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
 
 import services
-from controllers.common.fields import SimpleResultResponse
+from controllers.common.fields import GeneratedAppResponse, SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.error import (
     AppUnavailableError,
     CompletionRequestError,
@@ -23,6 +25,8 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
     with_current_user_id,
 )
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
@@ -36,7 +40,7 @@ from core.helper.trace_id_helper import get_external_trace_id
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs import helper
 from libs.helper import uuid_value
-from libs.login import current_user, login_required
+from libs.login import login_required
 from models import Account
 from models.model import App, AppMode
 from services.app_generate_service import AppGenerateService
@@ -63,8 +67,14 @@ class BaseMessagePayload(BaseModel):
     # Soul, so no override ``model_config`` is sent; chat / agent-chat / completion
     # debugging still pass it. Optional here, required in practice by those modes
     # downstream when their config is built from args.
-    model_config_data: dict[str, Any] = Field(default_factory=dict, alias="model_config")
-    files: list[Any] | None = Field(default=None, description="Uploaded files")
+    model_config_data: dict[str, Any] = Field(
+        default_factory=dict,
+        alias="model_config",
+    )
+    files: list[Any] | None = Field(
+        default=None,
+        description="Uploaded files",
+    )
     response_mode: Literal["blocking", "streaming"] = Field(default="blocking", description="Response mode")
     retriever_from: str = Field(default="dev", description="Retriever source")
 
@@ -87,7 +97,7 @@ class ChatMessagePayload(BaseMessagePayload):
 
 
 register_schema_models(console_ns, CompletionMessagePayload, ChatMessagePayload)
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(console_ns, GeneratedAppResponse, SimpleResultResponse)
 
 
 # define completion message api for user
@@ -97,14 +107,15 @@ class CompletionMessageApi(Resource):
     @console_ns.doc(description="Generate completion message for debugging")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[CompletionMessagePayload.__name__])
-    @console_ns.response(200, "Completion generated successfully")
+    @console_ns.response(200, "Completion generated successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(404, "App not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=AppMode.COMPLETION)
-    def post(self, app_model: App):
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
         args_model = CompletionMessagePayload.model_validate(console_ns.payload)
         args = args_model.model_dump(exclude_none=True, by_alias=True)
 
@@ -112,8 +123,6 @@ class CompletionMessageApi(Resource):
         args["auto_generate_name"] = False
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account or EndUser instance")
             response = AppGenerateService.generate(
                 app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.DEBUGGER, streaming=streaming
             )
@@ -170,7 +179,7 @@ class ChatMessageApi(Resource):
     @console_ns.doc(description="Generate chat message for debugging")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[ChatMessagePayload.__name__])
-    @console_ns.response(200, "Chat message generated successfully")
+    @console_ns.response(200, "Chat message generated successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(404, "App or conversation not found")
     @setup_required
@@ -178,54 +187,29 @@ class ChatMessageApi(Resource):
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.AGENT])
     @edit_permission_required
-    def post(self, app_model: App):
-        raw_payload = console_ns.payload or {}
-        args_model = ChatMessagePayload.model_validate(raw_payload)
-        args = args_model.model_dump(exclude_none=True, by_alias=True)
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        return _create_chat_message(current_user=current_user, app_model=app_model)
 
-        streaming = _resolve_debugger_chat_streaming(
-            app_mode=AppMode.value_of(app_model.mode),
-            response_mode=args_model.response_mode,
-            response_mode_provided=isinstance(raw_payload, dict) and "response_mode" in raw_payload,
-        )
-        if AppMode.value_of(app_model.mode) == AppMode.AGENT:
-            args["response_mode"] = "streaming"
-        args["auto_generate_name"] = False
 
-        external_trace_id = get_external_trace_id(request)
-        if external_trace_id:
-            args["external_trace_id"] = external_trace_id
-
-        try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account or EndUser instance")
-            response = AppGenerateService.generate(
-                app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.DEBUGGER, streaming=streaming
-            )
-
-            return helper.compact_generate_response(response)
-        except services.errors.conversation.ConversationNotExistsError:
-            raise NotFound("Conversation Not Exists.")
-        except services.errors.conversation.ConversationCompletedError:
-            raise ConversationCompletedError()
-        except services.errors.app_model_config.AppModelConfigBrokenError:
-            logger.exception("App model config broken.")
-            raise AppUnavailableError()
-        except ProviderTokenNotInitError as ex:
-            raise ProviderNotInitializeError(ex.description)
-        except QuotaExceededError:
-            raise ProviderQuotaExceededError()
-        except ModelCurrentlyNotSupportError:
-            raise ProviderModelCurrentlyNotSupportError()
-        except InvokeRateLimitError as ex:
-            raise InvokeRateLimitHttpError(ex.description)
-        except InvokeError as e:
-            raise CompletionRequestError(e.description)
-        except ValueError as e:
-            raise e
-        except Exception as e:
-            logger.exception("internal server error.")
-            raise InternalServerError()
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages")
+class AgentChatMessageApi(Resource):
+    @console_ns.doc("create_agent_chat_message")
+    @console_ns.doc(description="Generate an Agent App chat message for debugging")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.expect(console_ns.models[ChatMessagePayload.__name__])
+    @console_ns.response(200, "Chat message generated successfully", console_ns.models[GeneratedAppResponse.__name__])
+    @console_ns.response(400, "Invalid request parameters")
+    @console_ns.response(404, "Agent or conversation not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _create_chat_message(current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/chat-messages/<string:task_id>/stop")
@@ -240,12 +224,79 @@ class ChatMessageStopApi(Resource):
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user_id
     def post(self, current_user_id: str, app_model: App, task_id: str):
+        return _stop_chat_message(current_user_id=current_user_id, app_model=app_model, task_id=task_id)
 
-        AppTaskService.stop_task(
-            task_id=task_id,
-            invoke_from=InvokeFrom.DEBUGGER,
-            user_id=current_user_id,
-            app_mode=AppMode.value_of(app_model.mode),
+
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages/<string:task_id>/stop")
+class AgentChatMessageStopApi(Resource):
+    @console_ns.doc("stop_agent_chat_message")
+    @console_ns.doc(description="Stop a running Agent App chat message generation")
+    @console_ns.doc(params={"agent_id": "Agent ID", "task_id": "Task ID to stop"})
+    @console_ns.response(200, "Task stopped successfully", console_ns.models[SimpleResultResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user_id
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user_id: str, agent_id: UUID, task_id: str):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _stop_chat_message(current_user_id=current_user_id, app_model=app_model, task_id=task_id)
+
+
+def _create_chat_message(*, current_user: Account, app_model: App):
+    raw_payload = console_ns.payload or {}
+    args_model = ChatMessagePayload.model_validate(raw_payload)
+    args = args_model.model_dump(exclude_none=True, by_alias=True)
+
+    streaming = _resolve_debugger_chat_streaming(
+        app_mode=AppMode.value_of(app_model.mode),
+        response_mode=args_model.response_mode,
+        response_mode_provided=isinstance(raw_payload, dict) and "response_mode" in raw_payload,
+    )
+    if AppMode.value_of(app_model.mode) == AppMode.AGENT:
+        args["response_mode"] = "streaming"
+    args["auto_generate_name"] = False
+
+    external_trace_id = get_external_trace_id(request)
+    if external_trace_id:
+        args["external_trace_id"] = external_trace_id
+
+    try:
+        response = AppGenerateService.generate(
+            app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.DEBUGGER, streaming=streaming
         )
 
-        return {"result": "success"}, 200
+        return helper.compact_generate_response(response)
+    except services.errors.conversation.ConversationNotExistsError:
+        raise NotFound("Conversation Not Exists.")
+    except services.errors.conversation.ConversationCompletedError:
+        raise ConversationCompletedError()
+    except services.errors.app_model_config.AppModelConfigBrokenError:
+        logger.exception("App model config broken.")
+        raise AppUnavailableError()
+    except ProviderTokenNotInitError as ex:
+        raise ProviderNotInitializeError(ex.description)
+    except QuotaExceededError:
+        raise ProviderQuotaExceededError()
+    except ModelCurrentlyNotSupportError:
+        raise ProviderModelCurrentlyNotSupportError()
+    except InvokeRateLimitError as ex:
+        raise InvokeRateLimitHttpError(ex.description)
+    except InvokeError as e:
+        raise CompletionRequestError(e.description)
+    except ValueError as e:
+        raise e
+    except Exception as e:
+        logger.exception("internal server error.")
+        raise InternalServerError()
+
+
+def _stop_chat_message(*, current_user_id: str, app_model: App, task_id: str):
+    AppTaskService.stop_task(
+        task_id=task_id,
+        invoke_from=InvokeFrom.DEBUGGER,
+        user_id=current_user_id,
+        app_mode=AppMode.value_of(app_model.mode),
+    )
+
+    return {"result": "success"}, 200

api/controllers/console/app/conversation.py

@@ -9,7 +9,7 @@ from sqlalchemy import func, or_
 from sqlalchemy.orm import selectinload
 from werkzeug.exceptions import NotFound
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -91,7 +91,7 @@ class CompletionConversationApi(Resource):
     @console_ns.doc("list_completion_conversations")
     @console_ns.doc(description="Get completion conversations with pagination and filtering")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[CompletionConversationQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(CompletionConversationQuery))
     @console_ns.response(200, "Success", console_ns.models[ConversationPaginationResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
@@ -206,7 +206,7 @@ class ChatConversationApi(Resource):
     @console_ns.doc("list_chat_conversations")
     @console_ns.doc(description="Get chat conversations with pagination, filtering and summary")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[ChatConversationQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ChatConversationQuery))
     @console_ns.response(200, "Success", console_ns.models[ConversationWithSummaryPaginationResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required

api/controllers/console/app/conversation_variables.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required
@@ -84,7 +84,7 @@ class ConversationVariablesApi(Resource):
     @console_ns.doc("get_conversation_variables")
     @console_ns.doc(description="Get conversation variables for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[ConversationVariablesQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ConversationVariablesQuery))
     @console_ns.response(
         200,
         "Conversation variables retrieved successfully",

api/controllers/console/app/generator.py

@@ -1,10 +1,12 @@
 from collections.abc import Sequence
+from typing import Any, Literal
 
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from sqlalchemy.orm import Session
 
-from controllers.common.schema import register_enum_models, register_schema_models
+from controllers.common.fields import SimpleDataResponse
+from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     CompletionRequestError,
@@ -25,6 +27,7 @@ from graphon.model_runtime.entities.llm_entities import LLMMode
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs.login import login_required
 from models import App
+from services.workflow_generator_service import WorkflowGeneratorService
 from services.workflow_service import WorkflowService
 
 
@@ -34,7 +37,11 @@ class InstructionGeneratePayload(BaseModel):
     current: str = Field(default="", description="Current instruction text")
     language: str = Field(default="javascript", description="Programming language (javascript/python)")
     instruction: str = Field(..., description="Instruction for generation")
-    model_config_data: ModelConfig = Field(..., alias="model_config", description="Model configuration")
+    model_config_data: ModelConfig = Field(
+        ...,
+        alias="model_config",
+        description="Model configuration",
+    )
     ideal_output: str = Field(default="", description="Expected ideal output")
 
 
@@ -42,6 +49,39 @@ class InstructionTemplatePayload(BaseModel):
     type: str = Field(..., description="Instruction template type")
 
 
+# Upper bound for the generator's free-text inputs. Generous for prose (a
+# detailed instruction rarely passes 2k chars) while keeping the
+# planner+builder prompts well inside every mainstream context window.
+# Mirrored by the ``maxLength`` on the frontend generator textarea.
+_MAX_INSTRUCTION_LENGTH = 10_000
+
+
+class WorkflowGeneratePayload(BaseModel):
+    """Payload for the cmd+k `/create` and `/refine` workflow generator endpoint.
+
+    See ``services/workflow_generator_service.py`` for behaviour. Errors are
+    surfaced through the same envelope as ``/rule-generate`` so the frontend
+    can reuse its existing handler.
+    """
+
+    mode: Literal["workflow", "advanced-chat"] = Field(..., description="Target app mode for the generated graph")
+    instruction: str = Field(..., description="Natural-language workflow description")
+    ideal_output: str = Field(default="", description="Optional sample output for grounding")
+    model_config_data: ModelConfig = Field(
+        ...,
+        alias="model_config",
+        description="Model configuration",
+    )
+    current_graph: dict | None = Field(
+        default=None,
+        description="Existing draft graph to refine (cmd+k `/refine`); omit for create-from-scratch",
+    )
+
+
+class GeneratorResponse(RootModel[Any]):
+    root: Any
+
+
 register_enum_models(console_ns, LLMMode)
 register_schema_models(
     console_ns,
@@ -50,8 +90,10 @@ register_schema_models(
     RuleStructuredOutputPayload,
     InstructionGeneratePayload,
     InstructionTemplatePayload,
+    WorkflowGeneratePayload,
     ModelConfig,
 )
+register_response_schema_models(console_ns, GeneratorResponse, SimpleDataResponse)
 
 
 @console_ns.route("/rule-generate")
@@ -59,7 +101,11 @@ class RuleGenerateApi(Resource):
     @console_ns.doc("generate_rule_config")
     @console_ns.doc(description="Generate rule configuration using LLM")
     @console_ns.expect(console_ns.models[RuleGeneratePayload.__name__])
-    @console_ns.response(200, "Rule configuration generated successfully")
+    @console_ns.response(
+        200,
+        "Rule configuration generated successfully",
+        console_ns.models[GeneratorResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -88,7 +134,7 @@ class RuleCodeGenerateApi(Resource):
     @console_ns.doc("generate_rule_code")
     @console_ns.doc(description="Generate code rules using LLM")
     @console_ns.expect(console_ns.models[RuleCodeGeneratePayload.__name__])
-    @console_ns.response(200, "Code rules generated successfully")
+    @console_ns.response(200, "Code rules generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -120,7 +166,7 @@ class RuleStructuredOutputGenerateApi(Resource):
     @console_ns.doc("generate_structured_output")
     @console_ns.doc(description="Generate structured output rules using LLM")
     @console_ns.expect(console_ns.models[RuleStructuredOutputPayload.__name__])
-    @console_ns.response(200, "Structured output generated successfully")
+    @console_ns.response(200, "Structured output generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -152,7 +198,7 @@ class InstructionGenerateApi(Resource):
     @console_ns.doc("generate_instruction")
     @console_ns.doc(description="Generate instruction for workflow nodes or general use")
     @console_ns.expect(console_ns.models[InstructionGeneratePayload.__name__])
-    @console_ns.response(200, "Instruction generated successfully")
+    @console_ns.response(200, "Instruction generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters or flow/workflow not found")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -247,7 +293,7 @@ class InstructionGenerationTemplateApi(Resource):
     @console_ns.doc("get_instruction_template")
     @console_ns.doc(description="Get instruction generation template")
     @console_ns.expect(console_ns.models[InstructionTemplatePayload.__name__])
-    @console_ns.response(200, "Template retrieved successfully")
+    @console_ns.response(200, "Template retrieved successfully", console_ns.models[SimpleDataResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
@@ -265,3 +311,72 @@ class InstructionGenerationTemplateApi(Resource):
                 return {"data": INSTRUCTION_GENERATE_TEMPLATE_CODE}
             case _:
                 raise ValueError(f"Invalid type: {args.type}")
+
+
+@console_ns.route("/workflow-generate")
+class WorkflowGenerateApi(Resource):
+    """Generate a Workflow / Chatflow draft graph from a natural-language description.
+
+    Triggered by the cmd+k `/create` slash command. Returns a graph payload
+    shaped exactly like ``WorkflowService.sync_draft_workflow``'s input, so the
+    frontend can hand it straight to ``/apps/{id}/workflows/draft``.
+    """
+
+    @console_ns.doc("generate_workflow_graph")
+    @console_ns.doc(description="Generate a Dify workflow graph from natural language")
+    @console_ns.expect(console_ns.models[WorkflowGeneratePayload.__name__])
+    @console_ns.response(200, "Workflow graph generated successfully", console_ns.models[GeneratorResponse.__name__])
+    @console_ns.response(400, "Invalid request parameters")
+    @console_ns.response(402, "Provider quota exceeded")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
+        args = WorkflowGeneratePayload.model_validate(console_ns.payload)
+
+        # Reject obviously-empty instructions at the boundary — Pydantic only
+        # validates ``instruction`` is a str, but a whitespace-only string
+        # would still hit the LLM and waste a planner+builder roundtrip on a
+        # response that the postprocess validator would reject anyway.
+        if not args.instruction.strip():
+            return {
+                "error": "Instruction is required",
+                "errors": [{"code": "EMPTY_INSTRUCTION", "detail": "Instruction is required"}],
+            }, 400
+
+        # Bound the prompt at the boundary too: an arbitrarily long
+        # instruction (or pasted document) blows the planner/builder context
+        # window and fails with an opaque provider error after two slow LLM
+        # calls. The cap matches the frontend textarea's maxLength.
+        if len(args.instruction) > _MAX_INSTRUCTION_LENGTH or len(args.ideal_output) > _MAX_INSTRUCTION_LENGTH:
+            return {
+                "error": "Instruction is too long",
+                "errors": [
+                    {
+                        "code": "INSTRUCTION_TOO_LONG",
+                        "detail": f"Instruction and ideal output must each be at most "
+                        f"{_MAX_INSTRUCTION_LENGTH} characters",
+                    }
+                ],
+            }, 400
+
+        try:
+            result = WorkflowGeneratorService.generate_workflow_graph(
+                tenant_id=current_tenant_id,
+                mode=args.mode,
+                instruction=args.instruction,
+                model_config=args.model_config_data,
+                ideal_output=args.ideal_output,
+                current_graph=args.current_graph,
+            )
+        except ProviderTokenNotInitError as ex:
+            raise ProviderNotInitializeError(ex.description)
+        except QuotaExceededError:
+            raise ProviderQuotaExceededError()
+        except ModelCurrentlyNotSupportError:
+            raise ProviderModelCurrentlyNotSupportError()
+        except InvokeError as e:
+            raise CompletionRequestError(e.description)
+
+        return result

api/controllers/console/app/mcp_server.py

@@ -27,13 +27,19 @@ from models.model import App, AppMCPServer
 
 class MCPServerCreatePayload(BaseModel):
     description: str | None = Field(default=None, description="Server description")
-    parameters: dict[str, Any] = Field(..., description="Server parameters configuration")
+    parameters: dict[str, Any] = Field(
+        ...,
+        description="Server parameters configuration",
+    )
 
 
 class MCPServerUpdatePayload(BaseModel):
     id: str = Field(..., description="Server ID")
     description: str | None = Field(default=None, description="Server description")
-    parameters: dict[str, Any] = Field(..., description="Server parameters configuration")
+    parameters: dict[str, Any] = Field(
+        ...,
+        description="Server parameters configuration",
+    )
     status: str | None = Field(default=None, description="Server status")
 
 

api/controllers/console/app/message.py

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

api/controllers/console/app/model_config.py

@@ -5,7 +5,8 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import SimpleResultResponse
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -29,19 +30,44 @@ from services.app_model_config_service import AppModelConfigService
 class ModelConfigRequest(BaseModel):
     provider: str | None = Field(default=None, description="Model provider")
     model: str | None = Field(default=None, description="Model name")
-    configs: dict[str, Any] | None = Field(default=None, description="Model configuration parameters")
+    configs: dict[str, Any] | None = Field(
+        default=None,
+        description="Model configuration parameters",
+    )
     opening_statement: str | None = Field(default=None, description="Opening statement")
     suggested_questions: list[str] | None = Field(default=None, description="Suggested questions")
-    more_like_this: dict[str, Any] | None = Field(default=None, description="More like this configuration")
-    speech_to_text: dict[str, Any] | None = Field(default=None, description="Speech to text configuration")
-    text_to_speech: dict[str, Any] | None = Field(default=None, description="Text to speech configuration")
-    retrieval_model: dict[str, Any] | None = Field(default=None, description="Retrieval model configuration")
-    tools: list[dict[str, Any]] | None = Field(default=None, description="Available tools")
-    dataset_configs: dict[str, Any] | None = Field(default=None, description="Dataset configurations")
-    agent_mode: dict[str, Any] | None = Field(default=None, description="Agent mode configuration")
+    more_like_this: dict[str, Any] | None = Field(
+        default=None,
+        description="More like this configuration",
+    )
+    speech_to_text: dict[str, Any] | None = Field(
+        default=None,
+        description="Speech to text configuration",
+    )
+    text_to_speech: dict[str, Any] | None = Field(
+        default=None,
+        description="Text to speech configuration",
+    )
+    retrieval_model: dict[str, Any] | None = Field(
+        default=None,
+        description="Retrieval model configuration",
+    )
+    tools: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Available tools",
+    )
+    dataset_configs: dict[str, Any] | None = Field(
+        default=None,
+        description="Dataset configurations",
+    )
+    agent_mode: dict[str, Any] | None = Field(
+        default=None,
+        description="Agent mode configuration",
+    )
 
 
 register_schema_models(console_ns, ModelConfigRequest)
+register_response_schema_models(console_ns, SimpleResultResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/model-config")
@@ -50,7 +76,11 @@ class ModelConfigResource(Resource):
     @console_ns.doc(description="Update application model configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[ModelConfigRequest.__name__])
-    @console_ns.response(200, "Model configuration updated successfully")
+    @console_ns.response(
+        200,
+        "Model configuration updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @console_ns.response(400, "Invalid configuration")
     @console_ns.response(404, "App not found")
     @setup_required

api/controllers/console/app/ops_trace.py

@@ -1,15 +1,16 @@
 from typing import Any
 
 from flask import request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field
 from werkzeug.exceptions import BadRequest
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import TracingConfigCheckError, TracingConfigIsExist, TracingConfigNotExist
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required
+from fields.base import ResponseModel
 from libs.login import login_required
 from models import App
 from services.ops_service import OpsService
@@ -21,10 +22,27 @@ class TraceProviderQuery(BaseModel):
 
 class TraceConfigPayload(BaseModel):
     tracing_provider: str = Field(..., description="Tracing provider name")
-    tracing_config: dict[str, Any] = Field(..., description="Tracing configuration data")
+    tracing_config: dict[str, Any] = Field(
+        ...,
+        description="Tracing configuration data",
+    )
+
+
+class TraceAppConfigResponse(ResponseModel):
+    result: str | None = None
+    error: str | None = None
+    has_not_configured: bool | None = None
+    id: str | None = None
+    app_id: str | None = None
+    tracing_provider: str | None = None
+    tracing_config: dict[str, Any] | None = Field(default=None)
+    is_active: bool | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
 
 
 register_schema_models(console_ns, TraceProviderQuery, TraceConfigPayload)
+register_response_schema_models(console_ns, TraceAppConfigResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/trace-config")
@@ -36,9 +54,11 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc("get_trace_app_config")
     @console_ns.doc(description="Get tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[TraceProviderQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TraceProviderQuery))
     @console_ns.response(
-        200, "Tracing configuration retrieved successfully", fields.Raw(description="Tracing configuration data")
+        200,
+        "Tracing configuration retrieved successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
     )
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
@@ -63,7 +83,9 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[TraceConfigPayload.__name__])
     @console_ns.response(
-        201, "Tracing configuration created successfully", fields.Raw(description="Created configuration data")
+        201,
+        "Tracing configuration created successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
     )
     @console_ns.response(400, "Invalid request parameters or configuration already exists")
     @setup_required
@@ -90,7 +112,11 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc(description="Update an existing tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[TraceConfigPayload.__name__])
-    @console_ns.response(200, "Tracing configuration updated successfully", fields.Raw(description="Success response"))
+    @console_ns.response(
+        200,
+        "Tracing configuration updated successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters or configuration not found")
     @setup_required
     @login_required
@@ -113,7 +139,7 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc("delete_trace_app_config")
     @console_ns.doc(description="Delete an existing tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[TraceProviderQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TraceProviderQuery))
     @console_ns.response(204, "Tracing configuration deleted successfully")
     @console_ns.response(400, "Invalid request parameters or configuration not found")
     @setup_required

api/controllers/console/app/statistic.py

@@ -2,15 +2,16 @@ from decimal import Decimal
 
 import sqlalchemy as sa
 from flask import abort, jsonify, request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from core.app.entities.app_invoke_entities import InvokeFrom
 from extensions.ext_database import db
+from fields.base import ResponseModel
 from libs.datetime_utils import parse_time_range
 from libs.helper import convert_datetime_to_date
 from libs.login import login_required
@@ -31,7 +32,92 @@ class StatisticTimeRangeQuery(BaseModel):
         return value
 
 
+class DailyMessageStatisticItem(ResponseModel):
+    date: str
+    message_count: int
+
+
+class DailyMessageStatisticResponse(ResponseModel):
+    data: list[DailyMessageStatisticItem]
+
+
+class DailyConversationStatisticItem(ResponseModel):
+    date: str
+    conversation_count: int
+
+
+class DailyConversationStatisticResponse(ResponseModel):
+    data: list[DailyConversationStatisticItem]
+
+
+class DailyTerminalStatisticItem(ResponseModel):
+    date: str
+    terminal_count: int
+
+
+class DailyTerminalStatisticResponse(ResponseModel):
+    data: list[DailyTerminalStatisticItem]
+
+
+class DailyTokenCostStatisticItem(ResponseModel):
+    date: str
+    token_count: int
+    total_price: str | float
+    currency: str
+
+
+class DailyTokenCostStatisticResponse(ResponseModel):
+    data: list[DailyTokenCostStatisticItem]
+
+
+class AverageSessionInteractionStatisticItem(ResponseModel):
+    date: str
+    interactions: float
+
+
+class AverageSessionInteractionStatisticResponse(ResponseModel):
+    data: list[AverageSessionInteractionStatisticItem]
+
+
+class UserSatisfactionRateStatisticItem(ResponseModel):
+    date: str
+    rate: float
+
+
+class UserSatisfactionRateStatisticResponse(ResponseModel):
+    data: list[UserSatisfactionRateStatisticItem]
+
+
+class AverageResponseTimeStatisticItem(ResponseModel):
+    date: str
+    latency: float
+
+
+class AverageResponseTimeStatisticResponse(ResponseModel):
+    data: list[AverageResponseTimeStatisticItem]
+
+
+class TokensPerSecondStatisticItem(ResponseModel):
+    date: str
+    tps: float
+
+
+class TokensPerSecondStatisticResponse(ResponseModel):
+    data: list[TokensPerSecondStatisticItem]
+
+
 register_schema_models(console_ns, StatisticTimeRangeQuery)
+register_response_schema_models(
+    console_ns,
+    DailyMessageStatisticResponse,
+    DailyConversationStatisticResponse,
+    DailyTerminalStatisticResponse,
+    DailyTokenCostStatisticResponse,
+    AverageSessionInteractionStatisticResponse,
+    UserSatisfactionRateStatisticResponse,
+    AverageResponseTimeStatisticResponse,
+    TokensPerSecondStatisticResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/statistics/daily-messages")
@@ -39,11 +125,11 @@ class DailyMessageStatistic(Resource):
     @console_ns.doc("get_daily_message_statistics")
     @console_ns.doc(description="Get daily message statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily message statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily message count data")),
+        console_ns.models[DailyMessageStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -99,11 +185,11 @@ class DailyConversationStatistic(Resource):
     @console_ns.doc("get_daily_conversation_statistics")
     @console_ns.doc(description="Get daily conversation statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily conversation statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily conversation count data")),
+        console_ns.models[DailyConversationStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -158,11 +244,11 @@ class DailyTerminalsStatistic(Resource):
     @console_ns.doc("get_daily_terminals_statistics")
     @console_ns.doc(description="Get daily terminal/end-user statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily terminal statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily terminal count data")),
+        console_ns.models[DailyTerminalStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -218,11 +304,11 @@ class DailyTokenCostStatistic(Resource):
     @console_ns.doc("get_daily_token_cost_statistics")
     @console_ns.doc(description="Get daily token cost statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily token cost statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily token cost data")),
+        console_ns.models[DailyTokenCostStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -281,11 +367,11 @@ class AverageSessionInteractionStatistic(Resource):
     @console_ns.doc("get_average_session_interaction_statistics")
     @console_ns.doc(description="Get average session interaction statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Average session interaction statistics retrieved successfully",
-        fields.List(fields.Raw(description="Average session interaction data")),
+        console_ns.models[AverageSessionInteractionStatisticResponse.__name__],
     )
     @setup_required
     @login_required
@@ -360,11 +446,11 @@ class UserSatisfactionRateStatistic(Resource):
     @console_ns.doc("get_user_satisfaction_rate_statistics")
     @console_ns.doc(description="Get user satisfaction rate statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "User satisfaction rate statistics retrieved successfully",
-        fields.List(fields.Raw(description="User satisfaction rate data")),
+        console_ns.models[UserSatisfactionRateStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -429,11 +515,11 @@ class AverageResponseTimeStatistic(Resource):
     @console_ns.doc("get_average_response_time_statistics")
     @console_ns.doc(description="Get average response time statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Average response time statistics retrieved successfully",
-        fields.List(fields.Raw(description="Average response time data")),
+        console_ns.models[AverageResponseTimeStatisticResponse.__name__],
     )
     @setup_required
     @login_required
@@ -489,11 +575,11 @@ class TokensPerSecondStatistic(Resource):
     @console_ns.doc("get_tokens_per_second_statistics")
     @console_ns.doc(description="Get tokens per second statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Tokens per second statistics retrieved successfully",
-        fields.List(fields.Raw(description="Tokens per second data")),
+        console_ns.models[TokensPerSecondStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required

api/controllers/console/app/workflow.py

@@ -2,26 +2,38 @@ import json
 import logging
 from collections.abc import Sequence
 from datetime import datetime
-from typing import Any, NotRequired, TypedDict
+from typing import Any, NotRequired, TypedDict, cast
 
 from flask import abort, request
 from flask_restx import Resource, fields
-from pydantic import AliasChoices, BaseModel, Field, ValidationError, field_validator
-from sqlalchemy.orm import sessionmaker
+from pydantic import AliasChoices, BaseModel, Field, RootModel, ValidationError, field_validator
+from sqlalchemy.orm import Session, sessionmaker
 from werkzeug.exceptions import BadRequest, Forbidden, InternalServerError, NotFound
 
 import services
 from controllers.common.controller_schemas import DefaultBlockConfigQuery, WorkflowListQuery, WorkflowUpdatePayload
-from controllers.common.fields import NewAppResponse, SimpleResultResponse
+from controllers.common.errors import InvalidArgumentError
+from controllers.common.fields import GeneratedAppResponse, NewAppResponse, SimpleResultResponse
 from controllers.common.schema import (
+    query_params_from_model,
     register_response_schema_model,
     register_response_schema_models,
     register_schema_models,
 )
 from controllers.console import console_ns
-from controllers.console.app.error import ConversationCompletedError, DraftWorkflowNotExist, DraftWorkflowNotSync
+from controllers.console.app.error import (
+    ConversationCompletedError,
+    DraftWorkflowNotExist,
+    DraftWorkflowNotSync,
+)
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+    with_current_tenant_id,
+    with_current_user,
+)
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.app_config.features.file_upload.manager import FileUploadConfigManager
 from core.app.apps.base_app_queue_manager import AppQueueManager
@@ -50,11 +62,12 @@ from graphon.file import helpers as file_helpers
 from graphon.graph_engine.manager import GraphEngineManager
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from graphon.variables import SecretVariable, SegmentType, VariableBase
+from graphon.variables.exc import VariableError
 from libs import helper
 from libs.datetime_utils import naive_utc_now
 from libs.helper import TimestampField, dump_response, to_timestamp, uuid_value
-from libs.login import current_account_with_tenant, login_required
-from models import App
+from libs.login import login_required
+from models import Account, App
 from models.model import AppMode
 from models.workflow import Workflow
 from repositories.workflow_collaboration_repository import WORKFLOW_ONLINE_USERS_PREFIX
@@ -86,16 +99,20 @@ class SyncDraftWorkflowPayload(BaseModel):
     graph: dict[str, Any]
     features: dict[str, Any]
     hash: str | None = None
-    environment_variables: list[dict[str, Any]] = Field(default_factory=list)
-    conversation_variables: list[dict[str, Any]] = Field(default_factory=list)
+    environment_variables: list[dict[str, Any]] = Field(
+        default_factory=list,
+    )
+    conversation_variables: list[dict[str, Any]] = Field(
+        default_factory=list,
+    )
 
 
 class BaseWorkflowRunPayload(BaseModel):
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
 
 
 class AdvancedChatWorkflowRunPayload(BaseWorkflowRunPayload):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
     query: str = ""
     conversation_id: str | None = None
     parent_message_id: str | None = None
@@ -109,11 +126,11 @@ class AdvancedChatWorkflowRunPayload(BaseWorkflowRunPayload):
 
 
 class IterationNodeRunPayload(BaseModel):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class LoopNodeRunPayload(BaseModel):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class DraftWorkflowRunPayload(BaseWorkflowRunPayload):
@@ -138,7 +155,10 @@ class ConvertToWorkflowPayload(BaseModel):
 
 
 class WorkflowFeaturesPayload(BaseModel):
-    features: dict[str, Any] = Field(..., description="Workflow feature configuration")
+    features: dict[str, Any] = Field(
+        ...,
+        description="Workflow feature configuration",
+    )
 
 
 class WorkflowOnlineUsersPayload(BaseModel):
@@ -154,7 +174,7 @@ class WorkflowConversationVariableResponse(ResponseModel):
     id: str
     name: str
     value_type: str
-    value: Any = Field(json_schema_extra={"type": "object"})
+    value: Any
     description: str
 
     @field_validator("value_type", mode="before")
@@ -173,7 +193,7 @@ class PipelineVariableResponse(ResponseModel):
     max_length: int | None = None
     required: bool
     unit: str | None = None
-    default_value: Any = Field(default=None, json_schema_extra={"type": "object"})
+    default_value: Any = Field(default=None)
     options: list[str] | None = None
     placeholder: str | None = None
     tooltips: str | None = None
@@ -190,14 +210,18 @@ class WorkflowEnvironmentVariableResponse(ResponseModel):
     value_type: str
     id: str
     name: str
-    value: Any = Field(json_schema_extra={"type": "object"})
+    value: Any
     description: str
 
 
 class WorkflowResponse(ResponseModel):
     id: str
-    graph: dict[str, Any] = Field(validation_alias=AliasChoices("graph_dict", "graph"))
-    features: dict[str, Any] = Field(validation_alias=AliasChoices("features_dict", "features"))
+    graph: dict[str, Any] = Field(
+        validation_alias=AliasChoices("graph_dict", "graph"),
+    )
+    features: dict[str, Any] = Field(
+        validation_alias=AliasChoices("features_dict", "features"),
+    )
     hash: str = Field(validation_alias=AliasChoices("unique_hash", "hash"))
     version: str
     marked_name: str
@@ -254,6 +278,46 @@ class WorkflowOnlineUsersResponse(ResponseModel):
     data: list[WorkflowOnlineUsersByApp]
 
 
+class WorkflowPublishResponse(ResponseModel):
+    result: str
+    created_at: int
+
+
+class WorkflowRestoreResponse(ResponseModel):
+    result: str
+    hash: str
+    updated_at: int
+
+
+class DefaultBlockConfigsResponse(RootModel[list[dict[str, Any]]]):
+    root: list[dict[str, Any]]
+
+
+class DefaultBlockConfigResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class HumanInputFormPreviewResponse(ResponseModel):
+    form_id: str
+    node_id: str
+    node_title: str
+    form_content: str
+    inputs: list[dict[str, Any]] = Field(default_factory=list)
+    actions: list[dict[str, Any]] = Field(default_factory=list)
+    display_in_ui: bool | None = None
+    form_token: str | None = None
+    resolved_default_values: dict[str, Any] = Field(default_factory=dict)
+    expiration_time: int | None = None
+
+
+class HumanInputFormSubmitResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class EmptyObjectResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 class DraftWorkflowTriggerRunPayload(BaseModel):
     node_id: str
 
@@ -291,6 +355,14 @@ register_response_schema_models(
     WorkflowOnlineUser,
     WorkflowOnlineUsersByApp,
     WorkflowOnlineUsersResponse,
+    WorkflowPublishResponse,
+    WorkflowRestoreResponse,
+    DefaultBlockConfigsResponse,
+    DefaultBlockConfigResponse,
+    HumanInputFormPreviewResponse,
+    HumanInputFormSubmitResponse,
+    EmptyObjectResponse,
+    GeneratedAppResponse,
     NewAppResponse,
     SimpleResultResponse,
 )
@@ -377,8 +449,16 @@ class DraftWorkflowApi(Resource):
         if not workflow:
             raise DraftWorkflowNotExist()
 
-        # return workflow, if not found, return 404
-        return dump_response(WorkflowResponse, workflow)
+        from services.agent.workflow_publish_service import WorkflowAgentPublishService
+
+        # Return workflow with response-only Agent node job projection so the
+        # front-end can treat draft graph node data as the editing source.
+        response = WorkflowResponse.model_validate(workflow, from_attributes=True).model_dump(mode="json")
+        response["graph"] = WorkflowAgentPublishService.project_draft_bindings_to_graph(
+            session=cast(Session, db.session),
+            draft_workflow=workflow,
+        )
+        return response
 
     @setup_required
     @login_required
@@ -401,13 +481,12 @@ class DraftWorkflowApi(Resource):
     )
     @console_ns.response(400, "Invalid workflow configuration")
     @console_ns.response(403, "Permission denied")
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Sync draft workflow
         """
-        current_user, _ = current_account_with_tenant()
-
         content_type = request.headers.get("Content-Type", "")
 
         if "application/json" in content_type:
@@ -447,6 +526,8 @@ class DraftWorkflowApi(Resource):
             )
         except WorkflowHashNotEqualError:
             raise DraftWorkflowNotSync()
+        except VariableError as e:
+            raise InvalidArgumentError(description=str(e))
 
         return {
             "result": "success",
@@ -461,20 +542,19 @@ class AdvancedChatDraftWorkflowRunApi(Resource):
     @console_ns.doc(description="Run draft workflow for advanced chat application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AdvancedChatWorkflowRunPayload.__name__])
-    @console_ns.response(200, "Workflow run started successfully")
+    @console_ns.response(200, "Workflow run started successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Run draft workflow
         """
-        current_user, _ = current_account_with_tenant()
-
         args_model = AdvancedChatWorkflowRunPayload.model_validate(console_ns.payload or {})
         args = args_model.model_dump(exclude_none=True)
 
@@ -507,19 +587,23 @@ class AdvancedChatDraftRunIterationNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow iteration node for advanced chat")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[IterationNodeRunPayload.__name__])
-    @console_ns.response(200, "Iteration node run started successfully")
+    @console_ns.response(
+        200,
+        "Iteration node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow iteration node
         """
-        current_user, _ = current_account_with_tenant()
         args = IterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         try:
@@ -545,19 +629,23 @@ class WorkflowDraftRunIterationNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow iteration node")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[IterationNodeRunPayload.__name__])
-    @console_ns.response(200, "Workflow iteration node run started successfully")
+    @console_ns.response(
+        200,
+        "Workflow iteration node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow iteration node
         """
-        current_user, _ = current_account_with_tenant()
         args = IterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         try:
@@ -583,19 +671,19 @@ class AdvancedChatDraftRunLoopNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow loop node for advanced chat")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[LoopNodeRunPayload.__name__])
-    @console_ns.response(200, "Loop node run started successfully")
+    @console_ns.response(200, "Loop node run started successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow loop node
         """
-        current_user, _ = current_account_with_tenant()
         args = LoopNodeRunPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -621,19 +709,23 @@ class WorkflowDraftRunLoopNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow loop node")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[LoopNodeRunPayload.__name__])
-    @console_ns.response(200, "Workflow loop node run started successfully")
+    @console_ns.response(
+        200,
+        "Workflow loop node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow loop node
         """
-        current_user, _ = current_account_with_tenant()
         args = LoopNodeRunPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -661,7 +753,10 @@ class HumanInputFormPreviewPayload(BaseModel):
 
 
 class HumanInputFormSubmitPayload(BaseModel):
-    form_inputs: dict[str, Any] = Field(..., description="Values the user provides for the form's own fields")
+    form_inputs: dict[str, Any] = Field(
+        ...,
+        description="Values the user provides for the form's own fields",
+    )
     inputs: dict[str, Any] = Field(
         ...,
         description="Values used to fill missing upstream variables referenced in form_content",
@@ -691,16 +786,17 @@ class AdvancedChatDraftHumanInputFormPreviewApi(Resource):
     @console_ns.doc(description="Get human input form preview for advanced chat workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormPreviewPayload.__name__])
+    @console_ns.response(200, "Human input form preview", console_ns.models[HumanInputFormPreviewResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Preview human input form content and placeholders
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormPreviewPayload.model_validate(console_ns.payload or {})
         inputs = args.inputs
 
@@ -720,16 +816,21 @@ class AdvancedChatDraftHumanInputFormRunApi(Resource):
     @console_ns.doc(description="Submit human input form preview for advanced chat workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormSubmitPayload.__name__])
+    @console_ns.response(
+        200,
+        "Human input form submission result",
+        console_ns.models[HumanInputFormSubmitResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Submit human input form preview
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormSubmitPayload.model_validate(console_ns.payload or {})
         workflow_service = WorkflowService()
         result = workflow_service.submit_human_input_form_preview(
@@ -749,16 +850,17 @@ class WorkflowDraftHumanInputFormPreviewApi(Resource):
     @console_ns.doc(description="Get human input form preview for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormPreviewPayload.__name__])
+    @console_ns.response(200, "Human input form preview", console_ns.models[HumanInputFormPreviewResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Preview human input form content and placeholders
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormPreviewPayload.model_validate(console_ns.payload or {})
         inputs = args.inputs
 
@@ -778,16 +880,21 @@ class WorkflowDraftHumanInputFormRunApi(Resource):
     @console_ns.doc(description="Submit human input form preview for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormSubmitPayload.__name__])
+    @console_ns.response(
+        200,
+        "Human input form submission result",
+        console_ns.models[HumanInputFormSubmitResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Submit human input form preview
         """
-        current_user, _ = current_account_with_tenant()
         workflow_service = WorkflowService()
         args = HumanInputFormSubmitPayload.model_validate(console_ns.payload or {})
         result = workflow_service.submit_human_input_form_preview(
@@ -807,16 +914,17 @@ class WorkflowDraftHumanInputDeliveryTestApi(Resource):
     @console_ns.doc(description="Test human input delivery for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputDeliveryTestPayload.__name__])
+    @console_ns.response(200, "Human input delivery test result", console_ns.models[EmptyObjectResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Test human input delivery
         """
-        current_user, _ = current_account_with_tenant()
         workflow_service = WorkflowService()
         args = HumanInputDeliveryTestPayload.model_validate(console_ns.payload or {})
         workflow_service.test_human_input_delivery(
@@ -835,18 +943,22 @@ class DraftWorkflowRunApi(Resource):
     @console_ns.doc(description="Run draft workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[DraftWorkflowRunPayload.__name__])
-    @console_ns.response(200, "Draft workflow run started successfully")
+    @console_ns.response(
+        200,
+        "Draft workflow run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Run draft workflow
         """
-        current_user, _ = current_account_with_tenant()
         args = DraftWorkflowRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         external_trace_id = get_external_trace_id(request)
@@ -911,12 +1023,12 @@ class DraftWorkflowNodeRunApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow node
         """
-        current_user, _ = current_account_with_tenant()
         args_model = DraftWorkflowNodeRunPayload.model_validate(console_ns.payload or {})
         args = args_model.model_dump(exclude_none=True)
 
@@ -977,16 +1089,17 @@ class PublishedWorkflowApi(Resource):
         return dump_response(WorkflowResponse, workflow)
 
     @console_ns.expect(console_ns.models[PublishWorkflowPayload.__name__])
+    @console_ns.response(200, "Workflow published successfully", console_ns.models[WorkflowPublishResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Publish workflow
         """
-        current_user, _ = current_account_with_tenant()
 
         args = PublishWorkflowPayload.model_validate(console_ns.payload or {})
 
@@ -1020,7 +1133,11 @@ class DefaultBlockConfigsApi(Resource):
     @console_ns.doc("get_default_block_configs")
     @console_ns.doc(description="Get default block configurations for workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Default block configurations retrieved successfully")
+    @console_ns.response(
+        200,
+        "Default block configurations retrieved successfully",
+        console_ns.models[DefaultBlockConfigsResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -1040,9 +1157,13 @@ class DefaultBlockConfigApi(Resource):
     @console_ns.doc("get_default_block_config")
     @console_ns.doc(description="Get default block configuration by type")
     @console_ns.doc(params={"app_id": "Application ID", "block_type": "Block type"})
-    @console_ns.response(200, "Default block configuration retrieved successfully")
+    @console_ns.response(
+        200,
+        "Default block configuration retrieved successfully",
+        console_ns.models[DefaultBlockConfigResponse.__name__],
+    )
     @console_ns.response(404, "Block type not found")
-    @console_ns.expect(console_ns.models[DefaultBlockConfigQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(DefaultBlockConfigQuery))
     @setup_required
     @login_required
     @account_initialization_required
@@ -1083,14 +1204,14 @@ class ConvertToWorkflowApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.COMPLETION])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Convert basic mode of chatbot app to workflow mode
         Convert expert mode of chatbot app to workflow mode
         Convert Completion App to Workflow App
         """
-        current_user, _ = current_account_with_tenant()
 
         payload = console_ns.payload or {}
         args = ConvertToWorkflowPayload.model_validate(payload).model_dump(exclude_none=True)
@@ -1122,9 +1243,9 @@ class WorkflowFeaturesApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
-        current_user, _ = current_account_with_tenant()
+    def post(self, current_user: Account, app_model: App):
 
         args = WorkflowFeaturesPayload.model_validate(console_ns.payload or {})
         features = args.features
@@ -1137,7 +1258,7 @@ class WorkflowFeaturesApi(Resource):
 
 @console_ns.route("/apps/<uuid:app_id>/workflows")
 class PublishedAllWorkflowApi(Resource):
-    @console_ns.expect(console_ns.models[WorkflowListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowListQuery))
     @console_ns.doc("get_all_published_workflows")
     @console_ns.doc(description="Get all published workflows for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
@@ -1150,12 +1271,12 @@ class PublishedAllWorkflowApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def get(self, app_model: App):
+    def get(self, current_user: Account, app_model: App):
         """
         Get published workflows
         """
-        current_user, _ = current_account_with_tenant()
 
         args = WorkflowListQuery.model_validate(request.args.to_dict(flat=True))
         page = args.page
@@ -1192,16 +1313,16 @@ class DraftWorkflowRestoreApi(Resource):
     @console_ns.doc("restore_workflow_to_draft")
     @console_ns.doc(description="Restore a published workflow version into the draft workflow")
     @console_ns.doc(params={"app_id": "Application ID", "workflow_id": "Published workflow ID"})
-    @console_ns.response(200, "Workflow restored successfully")
+    @console_ns.response(200, "Workflow restored successfully", console_ns.models[WorkflowRestoreResponse.__name__])
     @console_ns.response(400, "Source workflow must be published")
     @console_ns.response(404, "Workflow not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, workflow_id: str):
-        current_user, _ = current_account_with_tenant()
+    def post(self, current_user: Account, app_model: App, workflow_id: str):
         workflow_service = WorkflowService()
 
         try:
@@ -1237,12 +1358,12 @@ class WorkflowByIdApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def patch(self, app_model: App, workflow_id: str):
+    def patch(self, current_user: Account, app_model: App, workflow_id: str):
         """
         Update workflow attributes
         """
-        current_user, _ = current_account_with_tenant()
         args = WorkflowUpdatePayload.model_validate(console_ns.payload or {})
 
         # Prepare update data
@@ -1277,6 +1398,7 @@ class WorkflowByIdApi(Resource):
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @edit_permission_required
+    @console_ns.response(204, "Workflow deleted successfully")
     def delete(self, app_model: App, workflow_id: str):
         """
         Delete workflow
@@ -1348,19 +1470,23 @@ class DraftWorkflowTriggerRunApi(Resource):
             },
         )
     )
-    @console_ns.response(200, "Trigger event received and workflow executed successfully")
+    @console_ns.response(
+        200,
+        "Trigger event received and workflow executed successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Poll for trigger events and execute full workflow when event arrives
         """
-        current_user, _ = current_account_with_tenant()
         args = DraftWorkflowTriggerRunPayload.model_validate(console_ns.payload or {})
         node_id = args.node_id
         workflow_service = WorkflowService()
@@ -1412,19 +1538,23 @@ class DraftWorkflowTriggerNodeApi(Resource):
     @console_ns.doc("poll_draft_workflow_trigger_node")
     @console_ns.doc(description="Poll for trigger events and execute single node when event arrives")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
-    @console_ns.response(200, "Trigger event received and node executed successfully")
+    @console_ns.response(
+        200,
+        "Trigger event received and node executed successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Poll for trigger events and execute single node when event arrives
         """
-        current_user, _ = current_account_with_tenant()
 
         workflow_service = WorkflowService()
         draft_workflow = workflow_service.get_draft_workflow(app_model)
@@ -1492,19 +1622,19 @@ class DraftWorkflowTriggerRunAllApi(Resource):
     @console_ns.doc(description="Full workflow debug when the start node is a trigger")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[DraftWorkflowTriggerRunAllPayload.__name__])
-    @console_ns.response(200, "Workflow executed successfully")
+    @console_ns.response(200, "Workflow executed successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Full workflow debug when the start node is a trigger
         """
-        current_user, _ = current_account_with_tenant()
 
         args = DraftWorkflowTriggerRunAllPayload.model_validate(console_ns.payload or {})
         node_ids = args.node_ids
@@ -1565,7 +1695,8 @@ class WorkflowOnlineUsersApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
         args = WorkflowOnlineUsersPayload.model_validate(console_ns.payload or {})
 
         app_ids = args.app_ids
@@ -1575,7 +1706,6 @@ class WorkflowOnlineUsersApi(Resource):
         if not app_ids:
             return {"data": []}
 
-        _, current_tenant_id = current_account_with_tenant()
         workflow_service = WorkflowService()
         accessible_app_ids = workflow_service.get_accessible_app_ids(app_ids, current_tenant_id)
         ordered_accessible_app_ids = [app_id for app_id in app_ids if app_id in accessible_app_ids]

api/controllers/console/app/workflow_app_log.py

@@ -7,7 +7,7 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required
@@ -166,7 +166,7 @@ class WorkflowAppLogApi(Resource):
     @console_ns.doc("get_workflow_app_logs")
     @console_ns.doc(description="Get workflow application execution logs")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowAppLogQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowAppLogQuery))
     @console_ns.response(
         200,
         "Workflow app logs retrieved successfully",
@@ -209,7 +209,7 @@ class WorkflowArchivedLogApi(Resource):
     @console_ns.doc("get_workflow_archived_logs")
     @console_ns.doc(description="Get workflow archived execution logs")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowAppLogQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowAppLogQuery))
     @console_ns.response(
         200,
         "Workflow archived logs retrieved successfully",

api/controllers/console/app/workflow_comment.py

@@ -7,12 +7,18 @@ from pydantic import BaseModel, Field, TypeAdapter, computed_field, field_valida
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+    with_current_tenant_id,
+    with_current_user,
+)
 from fields.base import ResponseModel
 from fields.member_fields import AccountWithRole
 from libs.helper import build_avatar_url, dump_response, to_timestamp
-from libs.login import current_user, login_required
-from models import App
+from libs.login import login_required
+from models import Account, App
 from services.account_service import TenantService
 from services.workflow_comment_service import WorkflowCommentService
 
@@ -213,9 +219,10 @@ class WorkflowCommentListApi(Resource):
     @setup_required
     @account_initialization_required
     @get_app_model()
-    def get(self, app_model: App):
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, app_model: App):
         """Get all comments for a workflow."""
-        comments = WorkflowCommentService.get_comments(tenant_id=current_user.current_tenant_id, app_id=app_model.id)
+        comments = WorkflowCommentService.get_comments(tenant_id=current_tenant_id, app_id=app_model.id)
 
         return WorkflowCommentBasicList.model_validate({"data": comments}).model_dump(mode="json")
 
@@ -229,12 +236,14 @@ class WorkflowCommentListApi(Resource):
     @account_initialization_required
     @get_app_model()
     @edit_permission_required
-    def post(self, app_model: App):
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, app_model: App):
         """Create a new workflow comment."""
         payload = WorkflowCommentCreatePayload.model_validate(console_ns.payload or {})
 
         result = WorkflowCommentService.create_comment(
-            tenant_id=current_user.current_tenant_id,
+            tenant_id=current_tenant_id,
             app_id=app_model.id,
             created_by=current_user.id,
             content=payload.content,
@@ -258,10 +267,11 @@ class WorkflowCommentDetailApi(Resource):
     @setup_required
     @account_initialization_required
     @get_app_model()
-    def get(self, app_model: App, comment_id: str):
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, app_model: App, comment_id: str):
         """Get a specific workflow comment."""
         comment = WorkflowCommentService.get_comment(
-            tenant_id=current_user.current_tenant_id, app_id=app_model.id, comment_id=comment_id
+            tenant_id=current_tenant_id, app_id=app_model.id, comment_id=comment_id
         )
 
         return dump_response(WorkflowCommentDetail, comment)
@@ -276,12 +286,14 @@ class WorkflowCommentDetailApi(Resource):
     @account_initialization_required
     @get_app_model()
     @edit_permission_required
-    def put(self, app_model: App, comment_id: str):
+    @with_current_user
+    @with_current_tenant_id
+    def put(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str):
         """Update a workflow comment."""
         payload = WorkflowCommentUpdatePayload.model_validate(console_ns.payload or {})
 
         result = WorkflowCommentService.update_comment(
-            tenant_id=current_user.current_tenant_id,
+            tenant_id=current_tenant_id,
             app_id=app_model.id,
             comment_id=comment_id,
             user_id=current_user.id,
@@ -302,10 +314,12 @@ class WorkflowCommentDetailApi(Resource):
     @account_initialization_required
     @get_app_model()
     @edit_permission_required
-    def delete(self, app_model: App, comment_id: str):
+    @with_current_user
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str):
         """Delete a workflow comment."""
         WorkflowCommentService.delete_comment(
-            tenant_id=current_user.current_tenant_id,
+            tenant_id=current_tenant_id,
             app_id=app_model.id,
             comment_id=comment_id,
             user_id=current_user.id,
@@ -327,10 +341,12 @@ class WorkflowCommentResolveApi(Resource):
     @account_initialization_required
     @get_app_model()
     @edit_permission_required
-    def post(self, app_model: App, comment_id: str):
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str):
         """Resolve a workflow comment."""
         comment = WorkflowCommentService.resolve_comment(
-            tenant_id=current_user.current_tenant_id,
+            tenant_id=current_tenant_id,
             app_id=app_model.id,
             comment_id=comment_id,
             user_id=current_user.id,
@@ -353,11 +369,13 @@ class WorkflowCommentReplyApi(Resource):
     @account_initialization_required
     @get_app_model()
     @edit_permission_required
-    def post(self, app_model: App, comment_id: str):
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str):
         """Add a reply to a workflow comment."""
         # Validate comment access first
         WorkflowCommentService.validate_comment_access(
-            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+            comment_id=comment_id, tenant_id=current_tenant_id, app_id=app_model.id
         )
 
         payload = WorkflowCommentReplyPayload.model_validate(console_ns.payload or {})
@@ -386,17 +404,19 @@ class WorkflowCommentReplyDetailApi(Resource):
     @account_initialization_required
     @get_app_model()
     @edit_permission_required
-    def put(self, app_model: App, comment_id: str, reply_id: str):
+    @with_current_user
+    @with_current_tenant_id
+    def put(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str, reply_id: str):
         """Update a comment reply."""
         # Validate comment access first
         WorkflowCommentService.validate_comment_access(
-            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+            comment_id=comment_id, tenant_id=current_tenant_id, app_id=app_model.id
         )
 
         payload = WorkflowCommentReplyPayload.model_validate(console_ns.payload or {})
 
         reply = WorkflowCommentService.update_reply(
-            tenant_id=current_user.current_tenant_id,
+            tenant_id=current_tenant_id,
             app_id=app_model.id,
             comment_id=comment_id,
             reply_id=reply_id,
@@ -416,15 +436,17 @@ class WorkflowCommentReplyDetailApi(Resource):
     @account_initialization_required
     @get_app_model()
     @edit_permission_required
-    def delete(self, app_model: App, comment_id: str, reply_id: str):
+    @with_current_user
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str, current_user: Account, app_model: App, comment_id: str, reply_id: str):
         """Delete a comment reply."""
         # Validate comment access first
         WorkflowCommentService.validate_comment_access(
-            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+            comment_id=comment_id, tenant_id=current_tenant_id, app_id=app_model.id
         )
 
         WorkflowCommentService.delete_reply(
-            tenant_id=current_user.current_tenant_id,
+            tenant_id=current_tenant_id,
             app_id=app_model.id,
             comment_id=comment_id,
             reply_id=reply_id,
@@ -448,9 +470,13 @@ class WorkflowCommentMentionUsersApi(Resource):
     @setup_required
     @account_initialization_required
     @get_app_model()
-    def get(self, app_model: App):
+    @with_current_user
+    def get(self, current_user: Account, app_model: App):
         """Get all users in current tenant for mentions."""
-        members = TenantService.get_tenant_members(current_user.current_tenant)
+        current_tenant = current_user.current_tenant  # need the tenant object here
+        if current_tenant is None:
+            raise ValueError("current tenant is required")
+        members = TenantService.get_tenant_members(current_tenant)
         users = TypeAdapter(list[AccountWithRole]).validate_python(members, from_attributes=True)
         response = WorkflowCommentMentionUsersPayload(users=users)
         return response.model_dump(mode="json"), 200

api/controllers/console/app/workflow_draft_variable.py

@@ -1,7 +1,7 @@
 import logging
 from collections.abc import Callable
 from functools import wraps
-from typing import Any, Concatenate, TypedDict
+from typing import Any, Concatenate, TypedDict, override
 from uuid import UUID
 
 from flask import Response, request
@@ -9,26 +9,33 @@ from flask_restx import Resource, fields, marshal, marshal_with
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.errors import InvalidArgumentError, NotFoundError
+from controllers.common.fields import SimpleResultResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     DraftWorkflowNotExist,
 )
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
-from controllers.web.error import InvalidArgumentError, NotFoundError
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+    with_current_user,
+)
 from core.app.file_access import DatabaseFileAccessController
 from core.workflow.variable_prefixes import CONVERSATION_VARIABLE_NODE_ID, SYSTEM_VARIABLE_NODE_ID
 from extensions.ext_database import db
 from factories import variable_factory
 from factories.file_factory import build_from_mapping, build_from_mappings
 from factories.variable_factory import build_segment_with_type
+from fields.base import ResponseModel
 from graphon.file import helpers as file_helpers
 from graphon.variables.segment_group import SegmentGroup
 from graphon.variables.segments import ArrayFileSegment, FileSegment, Segment
 from graphon.variables.types import SegmentType
-from libs.login import current_user, login_required
-from models import App, AppMode
+from libs.login import login_required
+from models import Account, App, AppMode
 from models.workflow import WorkflowDraftVariable
 from services.workflow_draft_variable_service import WorkflowDraftVariableList, WorkflowDraftVariableService
 from services.workflow_service import WorkflowService
@@ -37,6 +44,28 @@ logger = logging.getLogger(__name__)
 _file_access_controller = DatabaseFileAccessController()
 
 
+class OpaqueRawField(fields.Raw):
+    @override
+    def schema(self) -> dict[str, object]:
+        return {"type": "object"}
+
+
+class JsonValueRawField(fields.Raw):
+    @override
+    def schema(self) -> dict[str, object]:
+        return {
+            "anyOf": [
+                {"type": "string"},
+                {"type": "integer"},
+                {"type": "number"},
+                {"type": "boolean"},
+                {"type": "object", "additionalProperties": True},
+                {"type": "array", "items": {}},
+                {"type": "null"},
+            ]
+        }
+
+
 class WorkflowDraftVariableListQuery(BaseModel):
     page: int = Field(default=1, ge=1, le=100_000, description="Page number")
     limit: int = Field(default=20, ge=1, le=100, description="Items per page")
@@ -49,12 +78,33 @@ class WorkflowDraftVariableUpdatePayload(BaseModel):
 
 class ConversationVariableUpdatePayload(BaseModel):
     conversation_variables: list[dict[str, Any]] = Field(
-        ..., description="Conversation variables for the draft workflow"
+        ...,
+        description="Conversation variables for the draft workflow",
     )
 
 
 class EnvironmentVariableUpdatePayload(BaseModel):
-    environment_variables: list[dict[str, Any]] = Field(..., description="Environment variables for the draft workflow")
+    environment_variables: list[dict[str, Any]] = Field(
+        ...,
+        description="Environment variables for the draft workflow",
+    )
+
+
+class EnvironmentVariableItemResponse(ResponseModel):
+    id: str
+    type: str
+    name: str
+    description: str | None = None
+    selector: list[str]
+    value_type: str
+    value: Any
+    edited: bool
+    visible: bool
+    editable: bool
+
+
+class EnvironmentVariableListResponse(ResponseModel):
+    items: list[EnvironmentVariableItemResponse]
 
 
 register_schema_models(
@@ -64,6 +114,7 @@ register_schema_models(
     ConversationVariableUpdatePayload,
     EnvironmentVariableUpdatePayload,
 )
+register_response_schema_models(console_ns, SimpleResultResponse, EnvironmentVariableListResponse)
 
 
 def _convert_values_to_json_serializable_object(value: Segment):
@@ -123,14 +174,15 @@ def _serialize_full_content(variable: WorkflowDraftVariable) -> FullContentDict
     return result
 
 
-def _ensure_variable_access(
+def ensure_variable_access(
     variable: WorkflowDraftVariable | None,
     app_id: str,
     variable_id: str,
+    current_user_id: str,
 ) -> WorkflowDraftVariable:
     if variable is None:
         raise NotFoundError(description=f"variable not found, id={variable_id}")
-    if variable.app_id != app_id or variable.user_id != current_user.id:
+    if variable.app_id != app_id or variable.user_id != current_user_id:
         raise NotFoundError(description=f"variable not found, id={variable_id}")
     return variable
 
@@ -149,8 +201,8 @@ _WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS = {
 
 _WORKFLOW_DRAFT_VARIABLE_FIELDS = {
     **_WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS,
-    "value": fields.Raw(attribute=_serialize_var_value),
-    "full_content": fields.Raw(attribute=_serialize_full_content),
+    "value": JsonValueRawField(attribute=_serialize_var_value),
+    "full_content": OpaqueRawField(attribute=_serialize_full_content),
 }
 
 _WORKFLOW_DRAFT_ENV_VARIABLE_FIELDS = {
@@ -175,7 +227,7 @@ def _get_items(var_list: WorkflowDraftVariableList) -> list[WorkflowDraftVariabl
 
 _WORKFLOW_DRAFT_VARIABLE_LIST_WITHOUT_VALUE_FIELDS = {
     "items": fields.List(fields.Nested(_WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS), attribute=_get_items),
-    "total": fields.Raw(),
+    "total": fields.Integer,
 }
 
 _WORKFLOW_DRAFT_VARIABLE_LIST_FIELDS = {
@@ -215,7 +267,7 @@ workflow_draft_variable_list_model = console_ns.model(
 
 
 def _api_prerequisite[T, **P, R](
-    f: Callable[Concatenate[T, P], R],
+    f: Callable[Concatenate[T, Account, P], R],
 ) -> Callable[Concatenate[T, P], R | Response]:
     """Common prerequisites for all draft workflow variable APIs.
 
@@ -232,16 +284,17 @@ def _api_prerequisite[T, **P, R](
     @account_initialization_required
     @edit_permission_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @wraps(f)
-    def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R | Response:
-        return f(self, *args, **kwargs)
+    def wrapper(self: T, current_user: Account, *args: P.args, **kwargs: P.kwargs) -> R | Response:
+        return f(self, current_user, *args, **kwargs)
 
     return wrapper
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/variables")
 class WorkflowVariableCollectionApi(Resource):
-    @console_ns.expect(console_ns.models[WorkflowDraftVariableListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowDraftVariableListQuery))
     @console_ns.doc("get_workflow_variables")
     @console_ns.doc(description="Get draft workflow variables")
     @console_ns.doc(params={"app_id": "Application ID"})
@@ -251,7 +304,7 @@ class WorkflowVariableCollectionApi(Resource):
     )
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_without_value_model)
-    def get(self, app_model: App):
+    def get(self, current_user: Account, app_model: App):
         """
         Get draft workflow
         """
@@ -281,7 +334,7 @@ class WorkflowVariableCollectionApi(Resource):
     @console_ns.doc(description="Delete all draft workflow variables")
     @console_ns.response(204, "Workflow variables deleted successfully")
     @_api_prerequisite
-    def delete(self, app_model: App):
+    def delete(self, current_user: Account, app_model: App):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
@@ -315,7 +368,7 @@ class NodeVariableCollectionApi(Resource):
     @console_ns.response(200, "Node variables retrieved successfully", workflow_draft_variable_list_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
-    def get(self, app_model: App, node_id: str):
+    def get(self, current_user: Account, app_model: App, node_id: str):
         validate_node_id(node_id)
         with sessionmaker(bind=db.engine, expire_on_commit=False).begin() as session:
             draft_var_srv = WorkflowDraftVariableService(
@@ -329,7 +382,7 @@ class NodeVariableCollectionApi(Resource):
     @console_ns.doc(description="Delete all variables for a specific node")
     @console_ns.response(204, "Node variables deleted successfully")
     @_api_prerequisite
-    def delete(self, app_model: App, node_id: str):
+    def delete(self, current_user: Account, app_model: App, node_id: str):
         validate_node_id(node_id)
         srv = WorkflowDraftVariableService(db.session())
         srv.delete_node_variables(app_model.id, node_id, user_id=current_user.id)
@@ -349,15 +402,16 @@ class VariableApi(Resource):
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
-    def get(self, app_model: App, variable_id: UUID):
+    def get(self, current_user: Account, app_model: App, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
         variable_id_str = str(variable_id)
-        variable = _ensure_variable_access(
+        variable = ensure_variable_access(
             variable=draft_var_srv.get_variable(variable_id=variable_id_str),
             app_id=app_model.id,
             variable_id=variable_id_str,
+            current_user_id=current_user.id,
         )
         return variable
 
@@ -368,7 +422,7 @@ class VariableApi(Resource):
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
-    def patch(self, app_model: App, variable_id: UUID):
+    def patch(self, current_user: Account, app_model: App, variable_id: UUID):
         # Request payload for file types:
         #
         # Local File:
@@ -396,10 +450,11 @@ class VariableApi(Resource):
         args_model = WorkflowDraftVariableUpdatePayload.model_validate(console_ns.payload or {})
 
         variable_id_str = str(variable_id)
-        variable = _ensure_variable_access(
+        variable = ensure_variable_access(
             variable=draft_var_srv.get_variable(variable_id=variable_id_str),
             app_id=app_model.id,
             variable_id=variable_id_str,
+            current_user_id=current_user.id,
         )
 
         new_name = args_model.name
@@ -440,15 +495,16 @@ class VariableApi(Resource):
     @console_ns.response(204, "Variable deleted successfully")
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
-    def delete(self, app_model: App, variable_id: UUID):
+    def delete(self, current_user: Account, app_model: App, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
         variable_id_str = str(variable_id)
-        variable = _ensure_variable_access(
+        variable = ensure_variable_access(
             variable=draft_var_srv.get_variable(variable_id=variable_id_str),
             app_id=app_model.id,
             variable_id=variable_id_str,
+            current_user_id=current_user.id,
         )
         draft_var_srv.delete_variable(variable)
         db.session.commit()
@@ -464,7 +520,7 @@ class VariableResetApi(Resource):
     @console_ns.response(204, "Variable reset (no content)")
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
-    def put(self, app_model: App, variable_id: UUID):
+    def put(self, current_user: Account, app_model: App, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
@@ -476,10 +532,11 @@ class VariableResetApi(Resource):
                 f"Draft workflow not found, app_id={app_model.id}",
             )
         variable_id_str = str(variable_id)
-        variable = _ensure_variable_access(
+        variable = ensure_variable_access(
             variable=draft_var_srv.get_variable(variable_id=variable_id_str),
             app_id=app_model.id,
             variable_id=variable_id_str,
+            current_user_id=current_user.id,
         )
 
         resetted = draft_var_srv.reset_variable(draft_workflow, variable)
@@ -490,20 +547,20 @@ class VariableResetApi(Resource):
             return marshal(resetted, workflow_draft_variable_model)
 
 
-def _get_variable_list(app_model: App, node_id) -> WorkflowDraftVariableList:
+def _get_variable_list(app_model: App, node_id: str, current_user_id: str) -> WorkflowDraftVariableList:
     with sessionmaker(bind=db.engine, expire_on_commit=False).begin() as session:
         draft_var_srv = WorkflowDraftVariableService(
             session=session,
         )
         if node_id == CONVERSATION_VARIABLE_NODE_ID:
-            draft_vars = draft_var_srv.list_conversation_variables(app_model.id, user_id=current_user.id)
+            draft_vars = draft_var_srv.list_conversation_variables(app_model.id, user_id=current_user_id)
         elif node_id == SYSTEM_VARIABLE_NODE_ID:
-            draft_vars = draft_var_srv.list_system_variables(app_model.id, user_id=current_user.id)
+            draft_vars = draft_var_srv.list_system_variables(app_model.id, user_id=current_user_id)
         else:
             draft_vars = draft_var_srv.list_node_variables(
                 app_id=app_model.id,
                 node_id=node_id,
-                user_id=current_user.id,
+                user_id=current_user_id,
             )
     return draft_vars
 
@@ -517,7 +574,7 @@ class ConversationVariableCollectionApi(Resource):
     @console_ns.response(404, "Draft workflow not found")
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
-    def get(self, app_model: App):
+    def get(self, current_user: Account, app_model: App):
         # NOTE(QuantumGhost): Prefill conversation variables into the draft variables table
         # so their IDs can be returned to the caller.
         workflow_srv = WorkflowService()
@@ -527,19 +584,24 @@ class ConversationVariableCollectionApi(Resource):
         draft_var_srv = WorkflowDraftVariableService(db.session())
         draft_var_srv.prefill_conversation_variable_default_values(draft_workflow, user_id=current_user.id)
         db.session.commit()
-        return _get_variable_list(app_model, CONVERSATION_VARIABLE_NODE_ID)
+        return _get_variable_list(app_model, CONVERSATION_VARIABLE_NODE_ID, current_user.id)
 
     @console_ns.expect(console_ns.models[ConversationVariableUpdatePayload.__name__])
     @console_ns.doc("update_conversation_variables")
     @console_ns.doc(description="Update conversation variables for workflow draft")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Conversation variables updated successfully")
+    @console_ns.response(
+        200,
+        "Conversation variables updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
     @get_app_model(mode=AppMode.ADVANCED_CHAT)
-    def post(self, app_model: App):
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
         payload = ConversationVariableUpdatePayload.model_validate(console_ns.payload or {})
 
         workflow_service = WorkflowService()
@@ -566,8 +628,8 @@ class SystemVariableCollectionApi(Resource):
     @console_ns.response(200, "System variables retrieved successfully", workflow_draft_variable_list_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
-    def get(self, app_model: App):
-        return _get_variable_list(app_model, SYSTEM_VARIABLE_NODE_ID)
+    def get(self, current_user: Account, app_model: App):
+        return _get_variable_list(app_model, SYSTEM_VARIABLE_NODE_ID, current_user.id)
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/environment-variables")
@@ -575,10 +637,14 @@ class EnvironmentVariableCollectionApi(Resource):
     @console_ns.doc("get_environment_variables")
     @console_ns.doc(description="Get environment variables for workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Environment variables retrieved successfully")
+    @console_ns.response(
+        200,
+        "Environment variables retrieved successfully",
+        console_ns.models[EnvironmentVariableListResponse.__name__],
+    )
     @console_ns.response(404, "Draft workflow not found")
     @_api_prerequisite
-    def get(self, app_model: App):
+    def get(self, _current_user: Account, app_model: App):
         """
         Get draft workflow
         """
@@ -613,13 +679,18 @@ class EnvironmentVariableCollectionApi(Resource):
     @console_ns.doc("update_environment_variables")
     @console_ns.doc(description="Update environment variables for workflow draft")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Environment variables updated successfully")
+    @console_ns.response(
+        200,
+        "Environment variables updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def post(self, app_model: App):
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
         payload = EnvironmentVariableUpdatePayload.model_validate(console_ns.payload or {})
 
         workflow_service = WorkflowService()

api/controllers/console/app/workflow_node_output_inspector.py

@@ -30,6 +30,8 @@ from uuid import UUID
 from flask import Response
 from flask_restx import Resource
 
+from controllers.common.fields import EventStreamResponse
+from controllers.common.schema import register_response_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required
@@ -38,8 +40,13 @@ from libs.login import login_required
 from models import App, AppMode
 from services.workflow import inspector_events
 from services.workflow.node_output_inspector_service import (
+    CheckResultView,
     NodeOutputInspectorError,
     NodeOutputInspectorService,
+    NodeOutputsView,
+    NodeOutputView,
+    OutputPreviewView,
+    WorkflowRunSnapshotView,
 )
 
 logger = logging.getLogger(__name__)
@@ -54,6 +61,16 @@ _HEARTBEAT_EVERY_TICKS = 15
 # many ticks (= seconds).
 _STREAM_HARD_TIMEOUT_TICKS = 1800  # 30 min
 
+register_response_schema_models(
+    console_ns,
+    EventStreamResponse,
+    CheckResultView,
+    NodeOutputView,
+    NodeOutputsView,
+    WorkflowRunSnapshotView,
+    OutputPreviewView,
+)
+
 
 def _service() -> NodeOutputInspectorService:
     """One-line factory so tests can monkeypatch a stub if needed."""
@@ -124,6 +141,7 @@ class WorkflowDraftRunNodeOutputsApi(Resource):
     @console_ns.doc("get_workflow_draft_run_node_outputs")
     @console_ns.doc(description="Snapshot of every node's declared outputs for a draft workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(200, "Workflow run node outputs", console_ns.models[WorkflowRunSnapshotView.__name__])
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
@@ -146,6 +164,7 @@ class WorkflowDraftRunNodeOutputDetailApi(Resource):
             "node_id": "Node ID inside the workflow graph",
         }
     )
+    @console_ns.response(200, "Workflow run node output detail", console_ns.models[NodeOutputsView.__name__])
     @console_ns.response(404, "Workflow run / node not found")
     @setup_required
     @login_required
@@ -171,6 +190,7 @@ class WorkflowDraftRunNodeOutputPreviewApi(Resource):
             "output_name": "Declared output name as exposed by Composer",
         }
     )
+    @console_ns.response(200, "Workflow run node output preview", console_ns.models[OutputPreviewView.__name__])
     @console_ns.response(404, "Workflow run / node / output not found")
     @setup_required
     @login_required
@@ -309,6 +329,11 @@ class WorkflowDraftRunNodeOutputEventsApi(Resource):
     @console_ns.doc("stream_workflow_draft_run_node_output_events")
     @console_ns.doc(description="Server-Sent Events stream of inspector deltas for a draft workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(
+        200,
+        "Workflow run node output event stream",
+        console_ns.models[EventStreamResponse.__name__],
+    )
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
@@ -338,6 +363,7 @@ class WorkflowPublishedRunNodeOutputsApi(Resource):
     @console_ns.doc("get_workflow_published_run_node_outputs")
     @console_ns.doc(description="Snapshot of every node's declared outputs for a published workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(200, "Workflow run node outputs", console_ns.models[WorkflowRunSnapshotView.__name__])
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
@@ -360,6 +386,7 @@ class WorkflowPublishedRunNodeOutputDetailApi(Resource):
             "node_id": "Node ID inside the workflow graph",
         }
     )
+    @console_ns.response(200, "Workflow run node output detail", console_ns.models[NodeOutputsView.__name__])
     @console_ns.response(404, "Workflow run / node not found")
     @setup_required
     @login_required
@@ -386,6 +413,7 @@ class WorkflowPublishedRunNodeOutputPreviewApi(Resource):
             "output_name": "Declared output name as exposed by Composer",
         }
     )
+    @console_ns.response(200, "Workflow run node output preview", console_ns.models[OutputPreviewView.__name__])
     @console_ns.response(404, "Workflow run / node / output not found")
     @setup_required
     @login_required
@@ -402,6 +430,11 @@ class WorkflowPublishedRunNodeOutputEventsApi(Resource):
     @console_ns.doc("stream_workflow_published_run_node_output_events")
     @console_ns.doc(description="Server-Sent Events stream of inspector deltas for a published workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(
+        200,
+        "Workflow run node output event stream",
+        console_ns.models[EventStreamResponse.__name__],
+    )
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required

api/controllers/console/app/workflow_run.py

@@ -1,5 +1,5 @@
 from datetime import UTC, datetime, timedelta
-from typing import Literal, cast
+from typing import Literal
 from uuid import UUID
 
 from flask import request
@@ -9,11 +9,16 @@ from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 
 from configs import dify_config
+from controllers.common.errors import NotFoundError
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
-from controllers.web.error import NotFoundError
+from controllers.console.wraps import (
+    account_initialization_required,
+    setup_required,
+    with_current_tenant_id,
+    with_current_user,
+)
 from core.workflow.human_input_forms import load_form_tokens_by_form_id as _load_form_tokens_by_form_id
 from extensions.ext_database import db
 from fields.base import ResponseModel
@@ -30,8 +35,8 @@ from graphon.enums import WorkflowExecutionStatus
 from libs.archive_storage import ArchiveStorageNotConfiguredError, get_archive_storage
 from libs.custom_inputs import time_duration
 from libs.helper import uuid_value
-from libs.login import current_user, login_required
-from models import Account, App, AppMode, EndUser, WorkflowArchiveLog, WorkflowRunTriggeredFrom
+from libs.login import login_required
+from models import Account, App, AppMode, WorkflowArchiveLog, WorkflowRunTriggeredFrom
 from models.workflow import WorkflowRun
 from repositories.factory import DifyAPIRepositoryFactory
 from services.retention.workflow_run.constants import ARCHIVE_BUNDLE_NAME
@@ -190,8 +195,8 @@ class WorkflowRunExportApi(Resource):
     @account_initialization_required
     @get_app_model()
     def get(self, app_model: App, run_id: UUID):
-        tenant_id = str(app_model.tenant_id)
-        app_id = str(app_model.id)
+        tenant_id = app_model.tenant_id
+        app_id = app_model.id
         run_id_str = str(run_id)
 
         run_created_at = db.session.scalar(
@@ -397,18 +402,18 @@ class WorkflowRunNodeExecutionListApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, run_id: UUID):
+    @with_current_user
+    def get(self, current_user: Account, app_model: App, run_id: UUID):
         """
         Get workflow run node execution list
         """
         run_id_str = str(run_id)
 
         workflow_run_service = WorkflowRunService()
-        user = cast("Account | EndUser", current_user)
         node_executions = workflow_run_service.get_workflow_run_node_executions(
             app_model=app_model,
             run_id=run_id_str,
-            user=user,
+            user=current_user,
         )
 
         return WorkflowRunNodeExecutionListResponse.model_validate(
@@ -432,7 +437,8 @@ class ConsoleWorkflowPauseDetailsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, workflow_run_id: str):
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, workflow_run_id: str):
         """
         Get workflow pause details.
 
@@ -449,7 +455,7 @@ class ConsoleWorkflowPauseDetailsApi(Resource):
         if not workflow_run:
             raise NotFoundError("Workflow run not found")
 
-        if workflow_run.tenant_id != current_user.current_tenant_id:
+        if workflow_run.tenant_id != current_tenant_id:
             raise NotFoundError("Workflow run not found")
 
         # Check if workflow is suspended

api/controllers/console/app/workflow_statistic.py

@@ -3,11 +3,12 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from extensions.ext_database import db
+from fields.base import ResponseModel
 from libs.datetime_utils import parse_time_range
 from libs.login import login_required
 from models.account import Account
@@ -28,7 +29,50 @@ class WorkflowStatisticQuery(BaseModel):
         return value
 
 
+class WorkflowDailyRunsStatisticItem(ResponseModel):
+    date: str
+    runs: int
+
+
+class WorkflowDailyRunsStatisticResponse(ResponseModel):
+    data: list[WorkflowDailyRunsStatisticItem]
+
+
+class WorkflowDailyTerminalsStatisticItem(ResponseModel):
+    date: str
+    terminal_count: int
+
+
+class WorkflowDailyTerminalsStatisticResponse(ResponseModel):
+    data: list[WorkflowDailyTerminalsStatisticItem]
+
+
+class WorkflowDailyTokenCostStatisticItem(ResponseModel):
+    date: str
+    token_count: int
+
+
+class WorkflowDailyTokenCostStatisticResponse(ResponseModel):
+    data: list[WorkflowDailyTokenCostStatisticItem]
+
+
+class WorkflowAverageAppInteractionStatisticItem(ResponseModel):
+    date: str
+    interactions: float
+
+
+class WorkflowAverageAppInteractionStatisticResponse(ResponseModel):
+    data: list[WorkflowAverageAppInteractionStatisticItem]
+
+
 register_schema_models(console_ns, WorkflowStatisticQuery)
+register_response_schema_models(
+    console_ns,
+    WorkflowDailyRunsStatisticResponse,
+    WorkflowDailyTerminalsStatisticResponse,
+    WorkflowDailyTokenCostStatisticResponse,
+    WorkflowAverageAppInteractionStatisticResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflow/statistics/daily-conversations")
@@ -41,8 +85,12 @@ class WorkflowDailyRunsStatistic(Resource):
     @console_ns.doc("get_workflow_daily_runs_statistic")
     @console_ns.doc(description="Get workflow daily runs statistics")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowStatisticQuery.__name__])
-    @console_ns.response(200, "Daily runs statistics retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WorkflowStatisticQuery))
+    @console_ns.response(
+        200,
+        "Daily runs statistics retrieved successfully",
+        console_ns.models[WorkflowDailyRunsStatisticResponse.__name__],
+    )
     @get_app_model
     @setup_required
     @login_required
@@ -80,8 +128,12 @@ class WorkflowDailyTerminalsStatistic(Resource):
     @console_ns.doc("get_workflow_daily_terminals_statistic")
     @console_ns.doc(description="Get workflow daily terminals statistics")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowStatisticQuery.__name__])
-    @console_ns.response(200, "Daily terminals statistics retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WorkflowStatisticQuery))
+    @console_ns.response(
+        200,
+        "Daily terminals statistics retrieved successfully",
+        console_ns.models[WorkflowDailyTerminalsStatisticResponse.__name__],
+    )
     @get_app_model
     @setup_required
     @login_required
@@ -119,8 +171,12 @@ class WorkflowDailyTokenCostStatistic(Resource):
     @console_ns.doc("get_workflow_daily_token_cost_statistic")
     @console_ns.doc(description="Get workflow daily token cost statistics")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowStatisticQuery.__name__])
-    @console_ns.response(200, "Daily token cost statistics retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WorkflowStatisticQuery))
+    @console_ns.response(
+        200,
+        "Daily token cost statistics retrieved successfully",
+        console_ns.models[WorkflowDailyTokenCostStatisticResponse.__name__],
+    )
     @get_app_model
     @setup_required
     @login_required
@@ -158,8 +214,12 @@ class WorkflowAverageAppInteractionStatistic(Resource):
     @console_ns.doc("get_workflow_average_app_interaction_statistic")
     @console_ns.doc(description="Get workflow average app interaction statistics")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowStatisticQuery.__name__])
-    @console_ns.response(200, "Average app interaction statistics retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WorkflowStatisticQuery))
+    @console_ns.response(
+        200,
+        "Average app interaction statistics retrieved successfully",
+        console_ns.models[WorkflowAverageAppInteractionStatisticResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/app/workflow_trigger.py

@@ -9,17 +9,17 @@ from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import NotFound
 
 from configs import dify_config
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from extensions.ext_database import db
 from fields.base import ResponseModel
-from libs.login import current_user, login_required
+from libs.login import login_required
 from models.enums import AppTriggerStatus
-from models.model import Account, App, AppMode
+from models.model import App, AppMode
 from models.trigger import AppTrigger, WorkflowWebhookTrigger
 
 from .. import console_ns
 from ..app.wraps import get_app_model
-from ..wraps import account_initialization_required, edit_permission_required, setup_required
+from ..wraps import account_initialization_required, edit_permission_required, setup_required, with_current_tenant_id
 
 logger = logging.getLogger(__name__)
 
@@ -86,7 +86,7 @@ register_schema_models(
 class WebhookTriggerApi(Resource):
     """Webhook Trigger API"""
 
-    @console_ns.expect(console_ns.models[Parser.__name__])
+    @console_ns.doc(params=query_params_from_model(Parser))
     @setup_required
     @login_required
     @account_initialization_required
@@ -124,18 +124,16 @@ class AppTriggersApi(Resource):
     @account_initialization_required
     @get_app_model(mode=AppMode.WORKFLOW)
     @console_ns.response(200, "Success", console_ns.models[WorkflowTriggerListResponse.__name__])
-    def get(self, app_model: App):
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, app_model: App):
         """Get app triggers list"""
-        assert isinstance(current_user, Account)
-        assert current_user.current_tenant_id is not None
-
         with sessionmaker(db.engine, expire_on_commit=False).begin() as session:
             # Get all triggers for this app using select API
             triggers = (
                 session.execute(
                     select(AppTrigger)
                     .where(
-                        AppTrigger.tenant_id == current_user.current_tenant_id,
+                        AppTrigger.tenant_id == current_tenant_id,
                         AppTrigger.app_id == app_model.id,
                     )
                     .order_by(AppTrigger.created_at.desc(), AppTrigger.id.desc())
@@ -166,19 +164,18 @@ class AppTriggerEnableApi(Resource):
     @edit_permission_required
     @get_app_model(mode=AppMode.WORKFLOW)
     @console_ns.response(200, "Success", console_ns.models[WorkflowTriggerResponse.__name__])
-    def post(self, app_model: App):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, app_model: App):
         """Update app trigger (enable/disable)"""
         args = ParserEnable.model_validate(console_ns.payload)
 
-        assert current_user.current_tenant_id is not None
-
         trigger_id = args.trigger_id
         with sessionmaker(db.engine, expire_on_commit=False).begin() as session:
             # Find the trigger using select
             trigger = session.execute(
                 select(AppTrigger).where(
                     AppTrigger.id == trigger_id,
-                    AppTrigger.tenant_id == current_user.current_tenant_id,
+                    AppTrigger.tenant_id == current_tenant_id,
                     AppTrigger.app_id == app_model.id,
                 )
             ).scalar_one_or_none()

api/controllers/console/auth/activate.py

@@ -2,15 +2,17 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 
+from configs import dify_config
 from constants.languages import supported_language
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
-from controllers.console.error import AlreadyActivateError
+from controllers.console.error import AccountInFreezeError, AlreadyActivateError
 from extensions.ext_database import db
 from libs.datetime_utils import naive_utc_now
 from libs.helper import EmailStr, timezone
 from models import AccountStatus
 from services.account_service import RegisterService
+from services.billing_service import BillingService
 
 
 class ActivateCheckQuery(BaseModel):
@@ -67,7 +69,7 @@ register_schema_models(
 class ActivateCheckApi(Resource):
     @console_ns.doc("check_activation_token")
     @console_ns.doc(description="Check if activation token is valid")
-    @console_ns.expect(console_ns.models[ActivateCheckQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ActivateCheckQuery))
     @console_ns.response(
         200,
         "Success",
@@ -120,9 +122,12 @@ class ActivateApi(Resource):
         if invitation is None:
             raise AlreadyActivateError()
 
+        account = invitation["account"]
+        if dify_config.BILLING_ENABLED and BillingService.is_email_in_freeze(account.email):
+            raise AccountInFreezeError()
+
         RegisterService.revoke_token(args.workspace_id, normalized_request_email, args.token)
 
-        account = invitation["account"]
         account.name = args.name
 
         account.interface_language = args.interface_language

api/controllers/console/auth/data_source_bearer_auth.py

@@ -3,6 +3,7 @@ from uuid import UUID
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
+from controllers.common.fields import SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from fields.base import ResponseModel
 from libs.login import login_required
@@ -33,7 +34,12 @@ class ApiKeyAuthDataSourceListResponse(ResponseModel):
 
 
 register_schema_models(console_ns, ApiKeyAuthBindingPayload)
-register_response_schema_models(console_ns, ApiKeyAuthDataSourceItem, ApiKeyAuthDataSourceListResponse)
+register_response_schema_models(
+    console_ns,
+    SimpleResultResponse,
+    ApiKeyAuthDataSourceItem,
+    ApiKeyAuthDataSourceListResponse,
+)
 
 
 @console_ns.route("/api-key-auth/data-source")
@@ -64,6 +70,7 @@ class ApiKeyAuthDataSource(Resource):
 
 @console_ns.route("/api-key-auth/data-source/binding")
 class ApiKeyAuthDataSourceBinding(Resource):
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/auth/data_source_oauth.py

@@ -7,7 +7,8 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field
 
 from configs import dify_config
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import RedirectResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_model, register_schema_models
 from libs.login import login_required
 from libs.oauth_data_source import NotionOAuth
 
@@ -29,12 +30,24 @@ class OAuthDataSourceSyncResponse(BaseModel):
     result: str = Field(description="Operation result")
 
 
+class OAuthDataSourceCallbackQuery(BaseModel):
+    code: str | None = Field(default=None, description="Authorization code from OAuth provider")
+    error: str | None = Field(default=None, description="Error message from OAuth provider")
+
+
+class OAuthDataSourceBindingQuery(BaseModel):
+    code: str = Field(description="Authorization code from OAuth provider")
+
+
 register_schema_models(
     console_ns,
     OAuthDataSourceResponse,
     OAuthDataSourceBindingResponse,
     OAuthDataSourceSyncResponse,
+    OAuthDataSourceCallbackQuery,
+    OAuthDataSourceBindingQuery,
 )
+register_response_schema_model(console_ns, RedirectResponse)
 
 
 def get_oauth_providers():
@@ -84,14 +97,9 @@ class OAuthDataSource(Resource):
 class OAuthDataSourceCallback(Resource):
     @console_ns.doc("oauth_data_source_callback")
     @console_ns.doc(description="Handle OAuth callback from data source provider")
-    @console_ns.doc(
-        params={
-            "provider": "Data source provider name (notion)",
-            "code": "Authorization code from OAuth provider",
-            "error": "Error message from OAuth provider",
-        }
-    )
-    @console_ns.response(302, "Redirect to console with result")
+    @console_ns.doc(params={"provider": "Data source provider name (notion)"})
+    @console_ns.doc(params=query_params_from_model(OAuthDataSourceCallbackQuery))
+    @console_ns.response(302, "Redirect to console with result", console_ns.models[RedirectResponse.__name__])
     @console_ns.response(400, "Invalid provider")
     def get(self, provider: str):
         OAUTH_DATASOURCE_PROVIDERS = get_oauth_providers()
@@ -115,9 +123,8 @@ class OAuthDataSourceCallback(Resource):
 class OAuthDataSourceBinding(Resource):
     @console_ns.doc("oauth_data_source_binding")
     @console_ns.doc(description="Bind OAuth data source with authorization code")
-    @console_ns.doc(
-        params={"provider": "Data source provider name (notion)", "code": "Authorization code from OAuth provider"}
-    )
+    @console_ns.doc(params={"provider": "Data source provider name (notion)"})
+    @console_ns.doc(params=query_params_from_model(OAuthDataSourceBindingQuery))
     @console_ns.response(
         200,
         "Data source binding success",

api/controllers/console/auth/email_register.py

@@ -15,6 +15,7 @@ from controllers.console.auth.error import (
     InvalidTokenError,
     PasswordMismatchError,
 )
+from fields.base import ResponseModel
 from libs.helper import EmailStr, extract_remote_ip
 from libs.helper import timezone as validate_timezone_string
 from libs.password import valid_password
@@ -58,8 +59,24 @@ class EmailRegisterResetPayload(BaseModel):
         return validate_timezone_string(value)
 
 
+class EmailRegisterTokenPairResponse(ResponseModel):
+    access_token: str
+    refresh_token: str
+    csrf_token: str
+
+
+class EmailRegisterResetResponse(ResponseModel):
+    result: str
+    data: EmailRegisterTokenPairResponse
+
+
 register_schema_models(console_ns, EmailRegisterSendPayload, EmailRegisterValidityPayload, EmailRegisterResetPayload)
-register_response_schema_models(console_ns, SimpleResultDataResponse, VerificationTokenResponse)
+register_response_schema_models(
+    console_ns,
+    SimpleResultDataResponse,
+    VerificationTokenResponse,
+    EmailRegisterResetResponse,
+)
 
 
 @console_ns.route("/email-register/send-email")
@@ -67,6 +84,7 @@ class EmailRegisterSendEmailApi(Resource):
     @setup_required
     @email_password_login_enabled
     @email_register_enabled
+    @console_ns.expect(console_ns.models[EmailRegisterSendPayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[SimpleResultDataResponse.__name__])
     def post(self):
         args = EmailRegisterSendPayload.model_validate(console_ns.payload)
@@ -76,7 +94,7 @@ class EmailRegisterSendEmailApi(Resource):
         if AccountService.is_email_send_ip_limit(ip_address):
             raise EmailSendIpLimitError()
         language = "en-US"
-        if args.language in languages:
+        if args.language is not None and args.language in languages:
             language = args.language
 
         if dify_config.BILLING_ENABLED and BillingService.is_email_in_freeze(normalized_email):
@@ -92,6 +110,7 @@ class EmailRegisterCheckApi(Resource):
     @setup_required
     @email_password_login_enabled
     @email_register_enabled
+    @console_ns.expect(console_ns.models[EmailRegisterValidityPayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[VerificationTokenResponse.__name__])
     def post(self):
         args = EmailRegisterValidityPayload.model_validate(console_ns.payload)
@@ -133,6 +152,8 @@ class EmailRegisterResetApi(Resource):
     @setup_required
     @email_password_login_enabled
     @email_register_enabled
+    @console_ns.expect(console_ns.models[EmailRegisterResetPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[EmailRegisterResetResponse.__name__])
     def post(self):
         args = EmailRegisterResetPayload.model_validate(console_ns.payload)
 

api/controllers/console/auth/oauth.py

@@ -4,10 +4,13 @@ import urllib.parse
 import httpx
 from flask import current_app, redirect, request
 from flask_restx import Resource
+from pydantic import BaseModel, Field
 from werkzeug.exceptions import Unauthorized
 
 from configs import dify_config
 from constants.languages import languages
+from controllers.common.fields import RedirectResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_model, register_schema_models
 from events.tenant_event import tenant_was_created
 from extensions.ext_database import db
 from libs.datetime_utils import naive_utc_now
@@ -31,6 +34,21 @@ from .. import console_ns
 logger = logging.getLogger(__name__)
 
 
+class OAuthLoginQuery(BaseModel):
+    invite_token: str | None = Field(default=None, description="Optional invitation token")
+    timezone: str | None = Field(default=None, description="Preferred timezone")
+    language: str | None = Field(default=None, description="Preferred interface language")
+
+
+class OAuthCallbackQuery(BaseModel):
+    code: str = Field(description="Authorization code from OAuth provider")
+    state: str | None = Field(default=None, description="OAuth state parameter")
+
+
+register_schema_models(console_ns, OAuthLoginQuery, OAuthCallbackQuery)
+register_response_schema_model(console_ns, RedirectResponse)
+
+
 def get_oauth_providers():
     with current_app.app_context():
         if not dify_config.GITHUB_CLIENT_ID or not dify_config.GITHUB_CLIENT_SECRET:
@@ -83,10 +101,9 @@ def _preferred_interface_language(language: str | None = None) -> str:
 class OAuthLogin(Resource):
     @console_ns.doc("oauth_login")
     @console_ns.doc(description="Initiate OAuth login process")
-    @console_ns.doc(
-        params={"provider": "OAuth provider name (github/google)", "invite_token": "Optional invitation token"}
-    )
-    @console_ns.response(302, "Redirect to OAuth authorization URL")
+    @console_ns.doc(params={"provider": "OAuth provider name (github/google)"})
+    @console_ns.doc(params=query_params_from_model(OAuthLoginQuery))
+    @console_ns.response(302, "Redirect to OAuth authorization URL", console_ns.models[RedirectResponse.__name__])
     @console_ns.response(400, "Invalid provider")
     def get(self, provider: str):
         invite_token = request.args.get("invite_token") or None
@@ -110,14 +127,9 @@ class OAuthLogin(Resource):
 class OAuthCallback(Resource):
     @console_ns.doc("oauth_callback")
     @console_ns.doc(description="Handle OAuth callback and complete login process")
-    @console_ns.doc(
-        params={
-            "provider": "OAuth provider name (github/google)",
-            "code": "Authorization code from OAuth provider",
-            "state": "Optional state parameter (used for invite token)",
-        }
-    )
-    @console_ns.response(302, "Redirect to console with access token")
+    @console_ns.doc(params={"provider": "OAuth provider name (github/google)"})
+    @console_ns.doc(params=query_params_from_model(OAuthCallbackQuery))
+    @console_ns.response(302, "Redirect to console with access token", console_ns.models[RedirectResponse.__name__])
     @console_ns.response(400, "OAuth process failed")
     def get(self, provider: str):
         OAUTH_PROVIDERS = get_oauth_providers()

api/controllers/console/auth/oauth_server.py

@@ -1,6 +1,6 @@
 from collections.abc import Callable
 from functools import wraps
-from typing import Concatenate
+from typing import Any, Concatenate
 
 from flask import jsonify, request
 from flask.typing import ResponseReturnValue
@@ -8,6 +8,7 @@ from flask_restx import Resource
 from pydantic import BaseModel
 from werkzeug.exceptions import BadRequest, NotFound
 
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs.login import login_required
@@ -36,6 +37,41 @@ class OAuthTokenRequest(BaseModel):
     refresh_token: str | None = None
 
 
+class OAuthProviderAppResponse(BaseModel):
+    app_icon: str
+    app_label: dict[str, Any]
+    scope: str
+
+
+class OAuthProviderAuthorizeResponse(BaseModel):
+    code: str
+
+
+class OAuthProviderTokenResponse(BaseModel):
+    access_token: str
+    token_type: str
+    expires_in: int
+    refresh_token: str
+
+
+class OAuthProviderAccountResponse(BaseModel):
+    name: str
+    email: str
+    avatar: str | None = None
+    interface_language: str
+    timezone: str
+
+
+register_schema_models(console_ns, OAuthClientPayload, OAuthProviderRequest, OAuthTokenRequest)
+register_response_schema_models(
+    console_ns,
+    OAuthProviderAccountResponse,
+    OAuthProviderAppResponse,
+    OAuthProviderAuthorizeResponse,
+    OAuthProviderTokenResponse,
+)
+
+
 def oauth_server_client_id_required[T, **P, R](
     view: Callable[Concatenate[T, OAuthProviderApp, P], R],
 ) -> Callable[Concatenate[T, P], R]:
@@ -110,6 +146,8 @@ def oauth_server_access_token_required[T, **P, R](
 @console_ns.route("/oauth/provider")
 class OAuthServerAppApi(Resource):
     @setup_required
+    @console_ns.expect(console_ns.models[OAuthProviderRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[OAuthProviderAppResponse.__name__])
     @oauth_server_client_id_required
     def post(self, oauth_provider_app: OAuthProviderApp):
         payload = OAuthProviderRequest.model_validate(request.get_json())
@@ -134,6 +172,8 @@ class OAuthServerUserAuthorizeApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_user
+    @console_ns.expect(console_ns.models[OAuthClientPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[OAuthProviderAuthorizeResponse.__name__])
     @oauth_server_client_id_required
     def post(self, oauth_provider_app: OAuthProviderApp, current_user: Account):
         user_account_id = current_user.id
@@ -148,6 +188,8 @@ class OAuthServerUserAuthorizeApi(Resource):
 @console_ns.route("/oauth/provider/token")
 class OAuthServerUserTokenApi(Resource):
     @setup_required
+    @console_ns.expect(console_ns.models[OAuthTokenRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[OAuthProviderTokenResponse.__name__])
     @oauth_server_client_id_required
     def post(self, oauth_provider_app: OAuthProviderApp):
         payload = OAuthTokenRequest.model_validate(request.get_json())
@@ -198,6 +240,8 @@ class OAuthServerUserTokenApi(Resource):
 @console_ns.route("/oauth/provider/account")
 class OAuthServerUserAccountApi(Resource):
     @setup_required
+    @console_ns.expect(console_ns.models[OAuthClientPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[OAuthProviderAccountResponse.__name__])
     @oauth_server_client_id_required
     @oauth_server_access_token_required
     def post(self, oauth_provider_app: OAuthProviderApp, account: Account):

api/controllers/console/billing/billing.py

@@ -1,12 +1,12 @@
 import base64
-from typing import Literal
+from typing import Any, Literal
 
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from werkzeug.exceptions import BadRequest
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -30,11 +30,18 @@ class PartnerTenantsPayload(BaseModel):
     click_id: str = Field(..., description="Click Id from partner referral link")
 
 
+class BillingResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(console_ns, SubscriptionQuery, PartnerTenantsPayload)
+register_response_schema_models(console_ns, BillingResponse)
 
 
 @console_ns.route("/billing/subscription")
 class Subscription(Resource):
+    @console_ns.doc(params=query_params_from_model(SubscriptionQuery))
+    @console_ns.response(200, "Success", console_ns.models[BillingResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -49,6 +56,7 @@ class Subscription(Resource):
 
 @console_ns.route("/billing/invoices")
 class Invoices(Resource):
+    @console_ns.response(200, "Success", console_ns.models[BillingResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -66,7 +74,7 @@ class PartnerTenants(Resource):
     @console_ns.doc(description="Sync partner tenants bindings")
     @console_ns.doc(params={"partner_key": "Partner key"})
     @console_ns.expect(console_ns.models[PartnerTenantsPayload.__name__])
-    @console_ns.response(200, "Tenants synced to partner successfully")
+    @console_ns.response(200, "Tenants synced to partner successfully", console_ns.models[BillingResponse.__name__])
     @console_ns.response(400, "Invalid partner information")
     @setup_required
     @login_required

api/controllers/console/billing/compliance.py

@@ -1,12 +1,16 @@
+from typing import Any
+
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 
+from controllers.common.schema import query_params_from_model, register_response_schema_models
 from libs.helper import extract_remote_ip
 from libs.login import login_required
 from models import Account
 from services.billing_service import BillingService
 
+from ...common.schema import DEFAULT_REF_TEMPLATE_OPENAPI_3_0
 from .. import console_ns
 from ..wraps import (
     account_initialization_required,
@@ -21,17 +25,23 @@ class ComplianceDownloadQuery(BaseModel):
     doc_name: str = Field(..., description="Compliance document name")
 
 
+class ComplianceDownloadResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 console_ns.schema_model(
     ComplianceDownloadQuery.__name__,
-    ComplianceDownloadQuery.model_json_schema(ref_template="#/definitions/{model}"),
+    ComplianceDownloadQuery.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0),
 )
+register_response_schema_models(console_ns, ComplianceDownloadResponse)
 
 
 @console_ns.route("/compliance/download")
 class ComplianceApi(Resource):
-    @console_ns.expect(console_ns.models[ComplianceDownloadQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ComplianceDownloadQuery))
     @console_ns.doc("download_compliance_document")
     @console_ns.doc(description="Get compliance document download link")
+    @console_ns.response(200, "Success", console_ns.models[ComplianceDownloadResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/datasets/datasets.py

@@ -22,6 +22,8 @@ from controllers.console.wraps import (
     enterprise_license_required,
     is_admin_or_owner_required,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
 from core.indexing_runner import IndexingRunner
@@ -36,9 +38,9 @@ from fields.base import ResponseModel
 from fields.dataset_fields import DatasetDetailResponse
 from graphon.model_runtime.entities.model_entities import ModelType
 from libs.helper import build_icon_url, dump_response, to_timestamp
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
 from libs.url_utils import normalize_api_base_url
-from models import ApiToken, Dataset, Document, DocumentSegment, UploadFile
+from models import Account, ApiToken, Dataset, Document, DocumentSegment, UploadFile
 from models.dataset import DatasetPermission, DatasetPermissionEnum
 from models.enums import ApiTokenType, SegmentStatus
 from models.provider_ids import ModelProviderID
@@ -93,13 +95,13 @@ class DatasetUpdatePayload(BaseModel):
     indexing_technique: str | None = None
     embedding_model: str | None = None
     embedding_model_provider: str | None = None
-    retrieval_model: dict[str, Any] | None = None
-    summary_index_setting: dict[str, Any] | None = None
+    retrieval_model: dict[str, Any] | None = Field(default=None)
+    summary_index_setting: dict[str, Any] | None = Field(default=None)
     partial_member_list: list[dict[str, str]] | None = None
-    external_retrieval_model: dict[str, Any] | None = None
+    external_retrieval_model: dict[str, Any] | None = Field(default=None)
     external_knowledge_id: str | None = None
     external_knowledge_api_id: str | None = None
-    icon_info: dict[str, Any] | None = None
+    icon_info: dict[str, Any] | None = Field(default=None)
     is_multimodal: bool | None = False
 
     @field_validator("indexing_technique")
@@ -389,8 +391,9 @@ class DatasetListApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def get(self):
-        current_user, current_tenant_id = current_account_with_tenant()
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user: Account):
         # Convert query parameters to dict, handling list parameters correctly
         query_params: dict[str, str | list[str]] = dict(request.args.to_dict())
         # Handle ids and tag_ids as lists (Flask request.args.getlist returns list even for single value)
@@ -471,9 +474,10 @@ class DatasetListApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def post(self):
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account):
         payload = DatasetCreatePayload.model_validate(console_ns.payload or {})
-        current_user, current_tenant_id = current_account_with_tenant()
 
         # The role of the current user in the ta table must be admin, owner, or editor, or dataset_operator
         if not current_user.is_dataset_editor:
@@ -512,8 +516,9 @@ class DatasetApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        current_user, current_tenant_id = current_account_with_tenant()
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -566,14 +571,15 @@ class DatasetApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def patch(self, dataset_id: UUID):
+    @with_current_user
+    @with_current_tenant_id
+    def patch(self, current_tenant_id: str, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
             raise NotFound("Dataset not found.")
 
         payload = DatasetUpdatePayload.model_validate(console_ns.payload or {})
-        current_user, current_tenant_id = current_account_with_tenant()
         # check embedding model setting
         if (
             payload.indexing_technique == IndexTechniqueType.HIGH_QUALITY
@@ -614,9 +620,9 @@ class DatasetApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Dataset deleted successfully")
-    def delete(self, dataset_id: UUID):
+    @with_current_user
+    def delete(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
-        current_user, _ = current_account_with_tenant()
 
         if not (current_user.has_edit_permission or current_user.is_dataset_operator):
             raise Forbidden()
@@ -664,8 +670,8 @@ class DatasetQueryApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -704,10 +710,10 @@ class DatasetIndexingEstimateApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.expect(console_ns.models[IndexingEstimatePayload.__name__])
-    def post(self):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
         payload = IndexingEstimatePayload.model_validate(console_ns.payload or {})
         args = payload.model_dump()
-        _, current_tenant_id = current_account_with_tenant()
         # validate args
         DocumentService.estimate_args_validate(args)
         extract_settings = []
@@ -804,8 +810,8 @@ class DatasetRelatedAppListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -840,8 +846,8 @@ class DatasetIndexingStatusApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         documents = db.session.scalars(
             select(Document).where(Document.dataset_id == dataset_id_str, Document.tenant_id == current_tenant_id)
@@ -898,8 +904,8 @@ class DatasetApiKeyApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str):
         keys = db.session.scalars(
             select(ApiToken).where(ApiToken.type == self.resource_type, ApiToken.tenant_id == current_tenant_id)
         ).all()
@@ -911,9 +917,8 @@ class DatasetApiKeyApi(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
-        _, current_tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
         current_key_count = (
             db.session.scalar(
                 select(func.count(ApiToken.id)).where(
@@ -952,8 +957,8 @@ class DatasetApiDeleteApi(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def delete(self, api_key_id: UUID):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str, api_key_id: UUID):
         api_key_id_str = str(api_key_id)
         key = db.session.scalar(
             select(ApiToken)
@@ -1079,8 +1084,8 @@ class DatasetPermissionUserListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:

api/controllers/console/datasets/datasets_document.py

@@ -10,13 +10,13 @@ from uuid import UUID
 import sqlalchemy as sa
 from flask import request, send_file
 from flask_restx import Resource
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, RootModel, field_validator
 from sqlalchemy import asc, desc, func, select
 from werkzeug.exceptions import Forbidden, NotFound
 
 import services
 from controllers.common.controller_schemas import DocumentBatchDownloadZipPayload
-from controllers.common.fields import SimpleResultMessageResponse, SimpleResultResponse, UrlResponse
+from controllers.common.fields import BinaryFileResponse, SimpleResultMessageResponse, SimpleResultResponse, UrlResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from core.errors.error import (
@@ -145,6 +145,10 @@ class DocumentWithSegmentsListResponse(ResponseModel):
     page: int
 
 
+class OpaqueObjectResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(
     console_ns,
     KnowledgeConfig,
@@ -158,6 +162,7 @@ register_schema_models(
 )
 register_response_schema_models(
     console_ns,
+    BinaryFileResponse,
     SimpleResultMessageResponse,
     SimpleResultResponse,
     UrlResponse,
@@ -167,6 +172,7 @@ register_response_schema_models(
     DocumentWithSegmentsResponse,
     DatasetAndDocumentResponse,
     DocumentWithSegmentsListResponse,
+    OpaqueObjectResponse,
 )
 
 
@@ -216,7 +222,7 @@ class GetProcessRuleApi(Resource):
     @console_ns.doc("get_process_rule")
     @console_ns.doc(description="Get dataset document processing rules")
     @console_ns.doc(params={"document_id": "Document ID (optional)"})
-    @console_ns.response(200, "Process rules retrieved successfully")
+    @console_ns.response(200, "Process rules retrieved successfully", console_ns.models[OpaqueObjectResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -537,7 +543,11 @@ class DocumentIndexingEstimateApi(DocumentResource):
     @console_ns.doc("estimate_document_indexing")
     @console_ns.doc(description="Estimate document indexing cost")
     @console_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
-    @console_ns.response(200, "Indexing estimate calculated successfully")
+    @console_ns.response(
+        200,
+        "Indexing estimate calculated successfully",
+        console_ns.models[OpaqueObjectResponse.__name__],
+    )
     @console_ns.response(404, "Document not found")
     @console_ns.response(400, "Document already finished")
     @setup_required
@@ -606,6 +616,11 @@ class DocumentIndexingEstimateApi(DocumentResource):
 
 @console_ns.route("/datasets/<uuid:dataset_id>/batch/<string:batch>/indexing-estimate")
 class DocumentBatchIndexingEstimateApi(DocumentResource):
+    @console_ns.response(
+        200,
+        "Batch indexing estimate calculated successfully",
+        console_ns.models[OpaqueObjectResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -824,7 +839,7 @@ class DocumentApi(DocumentResource):
             "metadata": "Metadata inclusion (all/only/without)",
         }
     )
-    @console_ns.response(200, "Document retrieved successfully")
+    @console_ns.response(200, "Document retrieved successfully", console_ns.models[OpaqueObjectResponse.__name__])
     @console_ns.response(404, "Document not found")
     @setup_required
     @login_required
@@ -966,6 +981,7 @@ class DocumentBatchDownloadZipApi(DocumentResource):
 
     @console_ns.doc("download_dataset_documents_as_zip")
     @console_ns.doc(description="Download selected dataset documents as a single ZIP archive (upload-file only)")
+    @console_ns.response(200, "ZIP archive generated successfully", console_ns.models[BinaryFileResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -1324,6 +1340,11 @@ class WebsiteDocumentSyncApi(DocumentResource):
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/pipeline-execution-log")
 class DocumentPipelineExecutionLogApi(DocumentResource):
+    @console_ns.response(
+        200,
+        "Document pipeline execution log retrieved successfully",
+        console_ns.models[OpaqueObjectResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -1464,7 +1485,7 @@ class DocumentSummaryStatusApi(DocumentResource):
     @console_ns.doc("get_document_summary_status")
     @console_ns.doc(description="Get summary index generation status for a document")
     @console_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
-    @console_ns.response(200, "Summary status retrieved successfully")
+    @console_ns.response(200, "Summary status retrieved successfully", console_ns.models[OpaqueObjectResponse.__name__])
     @console_ns.response(404, "Document not found")
     @setup_required
     @login_required

api/controllers/console/datasets/external.py

@@ -1,13 +1,19 @@
+from typing import Any
 from uuid import UUID
 
 from flask import request
 from flask_restx import Resource, fields, marshal
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from werkzeug.exceptions import Forbidden, InternalServerError, NotFound
 
 import services
 from controllers.common.fields import UsageCountResponse
-from controllers.common.schema import get_or_create_model, register_response_schema_models, register_schema_models
+from controllers.common.schema import (
+    get_or_create_model,
+    query_params_from_model,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.console import console_ns
 from controllers.console.datasets.error import DatasetNameDuplicateError
 from controllers.console.wraps import (
@@ -17,6 +23,7 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
+from fields.base import ResponseModel
 from fields.dataset_fields import (
     dataset_detail_fields,
     dataset_retrieval_model_fields,
@@ -88,13 +95,15 @@ class ExternalDatasetCreatePayload(BaseModel):
     external_knowledge_id: str
     name: str = Field(..., min_length=1, max_length=100)
     description: str | None = Field(None, max_length=400)
-    external_retrieval_model: dict[str, object] | None = None
+    external_retrieval_model: dict[str, object] | None = Field(default=None)
 
 
 class ExternalHitTestingPayload(BaseModel):
     query: str
-    external_retrieval_model: dict[str, object] | None = None
-    metadata_filtering_conditions: dict[str, object] | None = None
+    external_retrieval_model: dict[str, object] | None = Field(default=None)
+    metadata_filtering_conditions: dict[str, object] | None = Field(
+        default=None,
+    )
 
 
 class BedrockRetrievalPayload(BaseModel):
@@ -109,6 +118,34 @@ class ExternalApiTemplateListQuery(BaseModel):
     keyword: str | None = Field(default=None, description="Search keyword")
 
 
+class ExternalKnowledgeDatasetBindingResponse(ResponseModel):
+    id: str
+    name: str
+
+
+class ExternalKnowledgeApiResponse(ResponseModel):
+    id: str
+    tenant_id: str
+    name: str
+    description: str
+    settings: dict[str, Any] | None = Field(default=None)
+    dataset_bindings: list[ExternalKnowledgeDatasetBindingResponse] = Field(default_factory=list)
+    created_by: str
+    created_at: str
+
+
+class ExternalKnowledgeApiListResponse(ResponseModel):
+    data: list[ExternalKnowledgeApiResponse]
+    has_more: bool
+    limit: int
+    total: int
+    page: int
+
+
+class ExternalRetrievalTestResponse(RootModel[dict[str, Any] | list[dict[str, Any]]]):
+    root: dict[str, Any] | list[dict[str, Any]]
+
+
 register_schema_models(
     console_ns,
     ExternalKnowledgeApiPayload,
@@ -117,20 +154,24 @@ register_schema_models(
     BedrockRetrievalPayload,
     ExternalApiTemplateListQuery,
 )
+register_response_schema_models(
+    console_ns,
+    ExternalKnowledgeApiResponse,
+    ExternalKnowledgeApiListResponse,
+    ExternalRetrievalTestResponse,
+)
 
 
 @console_ns.route("/datasets/external-knowledge-api")
 class ExternalApiTemplateListApi(Resource):
     @console_ns.doc("get_external_api_templates")
     @console_ns.doc(description="Get external knowledge API templates")
-    @console_ns.doc(
-        params={
-            "page": "Page number (default: 1)",
-            "limit": "Number of items per page (default: 20)",
-            "keyword": "Search keyword",
-        }
+    @console_ns.doc(params=query_params_from_model(ExternalApiTemplateListQuery))
+    @console_ns.response(
+        200,
+        "External API templates retrieved successfully",
+        console_ns.models[ExternalKnowledgeApiListResponse.__name__],
     )
-    @console_ns.response(200, "External API templates retrieved successfully")
     @setup_required
     @login_required
     @with_current_tenant_id
@@ -154,6 +195,11 @@ class ExternalApiTemplateListApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.expect(console_ns.models[ExternalKnowledgeApiPayload.__name__])
+    @console_ns.response(
+        201,
+        "External API template created successfully",
+        console_ns.models[ExternalKnowledgeApiResponse.__name__],
+    )
     @with_current_user
     @with_current_tenant_id
     def post(self, current_tenant_id: str, current_user: Account):
@@ -180,7 +226,11 @@ class ExternalApiTemplateApi(Resource):
     @console_ns.doc("get_external_api_template")
     @console_ns.doc(description="Get external knowledge API template details")
     @console_ns.doc(params={"external_knowledge_api_id": "External knowledge API ID"})
-    @console_ns.response(200, "External API template retrieved successfully")
+    @console_ns.response(
+        200,
+        "External API template retrieved successfully",
+        console_ns.models[ExternalKnowledgeApiResponse.__name__],
+    )
     @console_ns.response(404, "Template not found")
     @setup_required
     @login_required
@@ -196,6 +246,11 @@ class ExternalApiTemplateApi(Resource):
 
         return external_knowledge_api.to_dict(), 200
 
+    @console_ns.response(
+        200,
+        "External API template updated successfully",
+        console_ns.models[ExternalKnowledgeApiResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -293,7 +348,11 @@ class ExternalKnowledgeHitTestingApi(Resource):
     @console_ns.doc(description="Test external knowledge retrieval for dataset")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
     @console_ns.expect(console_ns.models[ExternalHitTestingPayload.__name__])
-    @console_ns.response(200, "External hit testing completed successfully")
+    @console_ns.response(
+        200,
+        "External hit testing completed successfully",
+        console_ns.models[ExternalRetrievalTestResponse.__name__],
+    )
     @console_ns.response(404, "Dataset not found")
     @console_ns.response(400, "Invalid parameters")
     @setup_required
@@ -334,7 +393,11 @@ class BedrockRetrievalApi(Resource):
     @console_ns.doc("bedrock_retrieval_test")
     @console_ns.doc(description="Bedrock retrieval test (internal use only)")
     @console_ns.expect(console_ns.models[BedrockRetrievalPayload.__name__])
-    @console_ns.response(200, "Bedrock retrieval test completed")
+    @console_ns.response(
+        200,
+        "Bedrock retrieval test completed",
+        console_ns.models[ExternalRetrievalTestResponse.__name__],
+    )
     def post(self):
         payload = BedrockRetrievalPayload.model_validate(console_ns.payload or {})
 

api/controllers/console/datasets/hit_testing.py

@@ -8,6 +8,7 @@ from controllers.common.schema import register_response_schema_models, register_
 from fields.hit_testing_fields import HitTestingResponse
 from libs.helper import dump_response
 from libs.login import login_required
+from models import Account
 
 from .. import console_ns
 from ..datasets.hit_testing_base import DatasetsHitTestingBase, HitTestingPayload
@@ -15,6 +16,8 @@ from ..wraps import (
     account_initialization_required,
     cloud_edition_billing_rate_limit_check,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 
 register_schema_models(console_ns, HitTestingPayload)
@@ -38,11 +41,16 @@ class HitTestingApi(Resource, DatasetsHitTestingBase):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def post(self, dataset_id: UUID) -> dict[str, object]:
+    @with_current_tenant_id
+    @with_current_user
+    def post(self, current_user: Account, current_tenant_id: str, dataset_id: UUID) -> dict[str, object]:
         dataset_id_str = str(dataset_id)
 
-        dataset = self.get_and_validate_dataset(dataset_id_str)
+        dataset = self.get_and_validate_dataset(dataset_id_str, current_user, current_tenant_id)
         args = self.parse_args(console_ns.payload)
         self.hit_testing_args_check(args)
 
-        return dump_response(HitTestingResponse, self.perform_hit_testing(dataset, args))
+        return dump_response(
+            HitTestingResponse,
+            self.perform_hit_testing(dataset, args, current_user, current_tenant_id),
+        )

api/controllers/console/datasets/hit_testing_base.py

@@ -19,7 +19,7 @@ from core.errors.error import (
     QuotaExceededError,
 )
 from graphon.model_runtime.errors.invoke import InvokeError
-from libs.login import current_user
+from libs.login import resolve_account_fallback
 from models.account import Account
 from models.dataset import Dataset
 from services.dataset_service import DatasetService
@@ -32,7 +32,7 @@ logger = logging.getLogger(__name__)
 class HitTestingPayload(BaseModel):
     query: str = Field(max_length=250)
     retrieval_model: RetrievalModel | None = None
-    external_retrieval_model: dict[str, Any] | None = None
+    external_retrieval_model: dict[str, Any] | None = Field(default=None)
     attachment_ids: list[str] | None = None
 
 
@@ -71,8 +71,10 @@ class DatasetsHitTestingBase:
         return normalized_records
 
     @staticmethod
-    def get_and_validate_dataset(dataset_id: str) -> Dataset:
-        assert isinstance(current_user, Account)
+    def get_and_validate_dataset(
+        dataset_id: str, current_user: Account | None = None, current_tenant_id: str | None = None
+    ) -> Dataset:
+        current_user, _ = resolve_account_fallback(current_user, current_tenant_id)
         dataset = DatasetService.get_dataset(dataset_id)
         if dataset is None:
             raise NotFound("Dataset not found.")
@@ -95,9 +97,14 @@ class DatasetsHitTestingBase:
         return hit_testing_payload.model_dump(exclude_none=True)
 
     @staticmethod
-    def perform_hit_testing(dataset: Dataset, args: dict[str, Any]) -> dict[str, Any]:
-        assert isinstance(current_user, Account)
+    def perform_hit_testing(
+        dataset: Dataset,
+        args: dict[str, Any],
+        current_user: Account | None = None,
+        current_tenant_id: str | None = None,
+    ) -> dict[str, Any]:
         try:
+            current_user, _ = resolve_account_fallback(current_user, current_tenant_id)
             response = HitTestingService.retrieve(
                 dataset=dataset,
                 query=cast(str, args.get("query")),

api/controllers/console/datasets/metadata.py

@@ -11,6 +11,7 @@ from controllers.console.wraps import (
     account_initialization_required,
     enterprise_license_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
 )
 from fields.dataset_fields import (
@@ -50,7 +51,8 @@ class DatasetMetadataCreateApi(Resource):
     @console_ns.response(201, "Metadata created successfully", console_ns.models[DatasetMetadataResponse.__name__])
     @console_ns.expect(console_ns.models[MetadataArgs.__name__])
     @with_current_user
-    def post(self, current_user: Account, dataset_id: UUID):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, dataset_id: UUID):
         metadata_args = MetadataArgs.model_validate(console_ns.payload or {})
 
         dataset_id_str = str(dataset_id)
@@ -59,7 +61,7 @@ class DatasetMetadataCreateApi(Resource):
             raise NotFound("Dataset not found.")
         DatasetService.check_dataset_permission(dataset, current_user)
 
-        metadata = MetadataService.create_metadata(dataset_id_str, metadata_args)
+        metadata = MetadataService.create_metadata(dataset_id_str, metadata_args, current_user, current_tenant_id)
         return dump_response(DatasetMetadataResponse, metadata), 201
 
     @setup_required
@@ -87,7 +89,8 @@ class DatasetMetadataApi(Resource):
     @console_ns.response(200, "Metadata updated successfully", console_ns.models[DatasetMetadataResponse.__name__])
     @console_ns.expect(console_ns.models[MetadataUpdatePayload.__name__])
     @with_current_user
-    def patch(self, current_user: Account, dataset_id: UUID, metadata_id: UUID):
+    @with_current_tenant_id
+    def patch(self, current_tenant_id: str, current_user: Account, dataset_id: UUID, metadata_id: UUID):
         payload = MetadataUpdatePayload.model_validate(console_ns.payload or {})
         name = payload.name
 
@@ -98,7 +101,9 @@ class DatasetMetadataApi(Resource):
             raise NotFound("Dataset not found.")
         DatasetService.check_dataset_permission(dataset, current_user)
 
-        metadata = MetadataService.update_metadata_name(dataset_id_str, metadata_id_str, name)
+        metadata = MetadataService.update_metadata_name(
+            dataset_id_str, metadata_id_str, name, current_user, current_tenant_id
+        )
         return dump_response(DatasetMetadataResponse, metadata), 200
 
     @setup_required
@@ -181,7 +186,7 @@ class DocumentMetadataEditApi(Resource):
 
         metadata_args = MetadataOperationData.model_validate(console_ns.payload or {})
 
-        MetadataService.update_documents_metadata(dataset, metadata_args)
+        MetadataService.update_documents_metadata(dataset, metadata_args, current_user)
 
         # Frontend callers only await success and invalidate caches; no response body is consumed.
         return "", 204

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

@@ -6,8 +6,8 @@ from pydantic import BaseModel, Field
 from werkzeug.exceptions import Forbidden, NotFound
 
 from configs import dify_config
-from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.fields import RedirectResponse, SimpleResultResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -16,7 +16,9 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
+from core.plugin.entities.plugin_daemon import PluginOAuthAuthorizationUrlResponse
 from core.plugin.impl.oauth import OAuthHandler
+from fields.base import ResponseModel
 from graphon.model_runtime.errors.validate import CredentialsValidateFailedError
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs.login import login_required
@@ -38,11 +40,11 @@ class DatasourceCredentialDeletePayload(BaseModel):
 class DatasourceCredentialUpdatePayload(BaseModel):
     credential_id: str
     name: str | None = Field(default=None, max_length=100)
-    credentials: dict[str, Any] | None = None
+    credentials: dict[str, Any] | None = Field(default=None)
 
 
 class DatasourceCustomClientPayload(BaseModel):
-    client_params: dict[str, Any] | None = None
+    client_params: dict[str, Any] | None = Field(default=None)
     enable_oauth_custom_client: bool | None = None
 
 
@@ -55,8 +57,25 @@ class DatasourceUpdateNamePayload(BaseModel):
     name: str = Field(max_length=100)
 
 
+class DatasourceOAuthAuthorizationQuery(BaseModel):
+    credential_id: str | None = Field(default=None, description="Credential ID to reauthorize")
+
+
+class DatasourceOAuthCallbackQuery(BaseModel):
+    code: str | None = Field(default=None, description="Authorization code from OAuth provider")
+    state: str | None = Field(default=None, description="OAuth state parameter")
+    error: str | None = Field(default=None, description="Error message from OAuth provider")
+    context_id: str | None = Field(default=None, description="OAuth proxy context ID")
+
+
+class DatasourceCredentialsResponse(ResponseModel):
+    result: Any
+
+
 register_schema_models(
     console_ns,
+    DatasourceOAuthAuthorizationQuery,
+    DatasourceOAuthCallbackQuery,
     DatasourceCredentialPayload,
     DatasourceCredentialDeletePayload,
     DatasourceCredentialUpdatePayload,
@@ -64,11 +83,23 @@ register_schema_models(
     DatasourceDefaultPayload,
     DatasourceUpdateNamePayload,
 )
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(
+    console_ns,
+    DatasourceCredentialsResponse,
+    PluginOAuthAuthorizationUrlResponse,
+    RedirectResponse,
+    SimpleResultResponse,
+)
 
 
 @console_ns.route("/oauth/plugin/<path:provider_id>/datasource/get-authorization-url")
 class DatasourcePluginOAuthAuthorizationUrl(Resource):
+    @console_ns.doc(params=query_params_from_model(DatasourceOAuthAuthorizationQuery))
+    @console_ns.response(
+        200,
+        "Authorization URL retrieved successfully",
+        console_ns.models[PluginOAuthAuthorizationUrlResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -118,6 +149,12 @@ class DatasourcePluginOAuthAuthorizationUrl(Resource):
 
 @console_ns.route("/oauth/plugin/<path:provider_id>/datasource/callback")
 class DatasourceOAuthCallback(Resource):
+    @console_ns.doc(params=query_params_from_model(DatasourceOAuthCallbackQuery))
+    @console_ns.response(
+        302,
+        "Redirect to console OAuth callback page",
+        console_ns.models[RedirectResponse.__name__],
+    )
     @setup_required
     def get(self, provider_id: str):
         context_id = request.cookies.get("context_id") or request.args.get("context_id")
@@ -176,6 +213,7 @@ class DatasourceOAuthCallback(Resource):
 @console_ns.route("/auth/plugin/datasource/<path:provider_id>")
 class DatasourceAuth(Resource):
     @console_ns.expect(console_ns.models[DatasourceCredentialPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -200,6 +238,7 @@ class DatasourceAuth(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @console_ns.response(200, "Success", console_ns.models[DatasourceCredentialsResponse.__name__])
     @with_current_user
     @with_current_tenant_id
     def get(self, current_tenant_id: str, user: Account, provider_id: str):
@@ -243,6 +282,7 @@ class DatasourceAuthDeleteApi(Resource):
 @console_ns.route("/auth/plugin/datasource/<path:provider_id>/update")
 class DatasourceAuthUpdateApi(Resource):
     @console_ns.expect(console_ns.models[DatasourceCredentialUpdatePayload.__name__])
+    @console_ns.response(201, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -266,6 +306,7 @@ class DatasourceAuthUpdateApi(Resource):
 
 @console_ns.route("/auth/plugin/datasource/list")
 class DatasourceAuthListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[DatasourceCredentialsResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -278,6 +319,7 @@ class DatasourceAuthListApi(Resource):
 
 @console_ns.route("/auth/plugin/datasource/default-list")
 class DatasourceHardCodeAuthListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[DatasourceCredentialsResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -291,6 +333,7 @@ class DatasourceHardCodeAuthListApi(Resource):
 @console_ns.route("/auth/plugin/datasource/<path:provider_id>/custom-client")
 class DatasourceAuthOauthCustomClient(Resource):
     @console_ns.expect(console_ns.models[DatasourceCustomClientPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

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

@@ -1,42 +1,47 @@
+from typing import Any
+
 from flask_restx import (  # type: ignore
     Resource,  # type: ignore
 )
-from pydantic import BaseModel
-from werkzeug.exceptions import Forbidden
+from pydantic import BaseModel, RootModel
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.datasets.wraps import get_rag_pipeline
-from controllers.console.wraps import account_initialization_required, setup_required
-from libs.login import current_user, login_required
+from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
+from libs.login import login_required
 from models import Account
 from models.dataset import Pipeline
 from services.rag_pipeline.rag_pipeline import RagPipelineService
 
 
 class Parser(BaseModel):
-    inputs: dict
+    inputs: dict[str, Any]
     datasource_type: str
     credential_id: str | None = None
 
 
+class DataSourceContentPreviewResponse(RootModel[Any]):
+    root: Any
+
+
 register_schema_models(console_ns, Parser)
+register_response_schema_models(console_ns, DataSourceContentPreviewResponse)
 
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/datasource/nodes/<string:node_id>/preview")
 class DataSourceContentPreviewApi(Resource):
     @console_ns.expect(console_ns.models[Parser.__name__])
+    @console_ns.response(200, "Success", console_ns.models[DataSourceContentPreviewResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    @with_current_user
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run datasource content preview
         """
-        if not isinstance(current_user, Account):
-            raise Forbidden()
-
         args = Parser.model_validate(console_ns.payload)
 
         inputs = args.inputs

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

@@ -21,11 +21,14 @@ from controllers.console.wraps import (
     enterprise_license_required,
     knowledge_pipeline_publish_enabled,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.helper import dump_response
 from libs.login import login_required
+from models.account import Account
 from models.dataset import PipelineCustomizedTemplate
 from services.entities.knowledge_entities.rag_pipeline_entities import IconInfo, PipelineTemplateInfoEntity
 from services.rag_pipeline.rag_pipeline import RagPipelineService
@@ -71,7 +74,9 @@ class PipelineTemplateDetailResponse(ResponseModel):
 class CustomizedPipelineTemplatePayload(BaseModel):
     name: str = Field(..., min_length=1, max_length=40)
     description: str = Field(default="", max_length=400)
-    icon_info: dict[str, object] = Field(default_factory=lambda: IconInfo(icon="").model_dump())
+    icon_info: dict[str, object] = Field(
+        default_factory=lambda: IconInfo(icon="").model_dump(),
+    )
 
 
 register_schema_models(
@@ -96,10 +101,11 @@ class PipelineTemplateListApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def get(self) -> JsonResponseWithStatus:
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str) -> JsonResponseWithStatus:
         query = PipelineTemplateListQuery.model_validate(request.args.to_dict(flat=True))
         # get pipeline templates
-        pipeline_templates = RagPipelineService.get_pipeline_templates(query.type, query.language)
+        pipeline_templates = RagPipelineService.get_pipeline_templates(query.type, query.language, current_tenant_id)
         return dump_response(PipelineTemplateListResponse, pipeline_templates), 200
 
 
@@ -128,10 +134,14 @@ class CustomizedPipelineTemplateApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def patch(self, template_id: str) -> tuple[str, int]:
+    @with_current_user
+    @with_current_tenant_id
+    def patch(self, current_tenant_id: str, current_user: Account, template_id: str) -> tuple[str, int]:
         payload = CustomizedPipelineTemplatePayload.model_validate(console_ns.payload or {})
         pipeline_template_info = PipelineTemplateInfoEntity.model_validate(payload.model_dump())
-        RagPipelineService.update_customized_pipeline_template(template_id, pipeline_template_info)
+        RagPipelineService.update_customized_pipeline_template(
+            template_id, pipeline_template_info, current_user, current_tenant_id
+        )
         return "", 204
 
     @console_ns.response(204, "Pipeline template deleted")
@@ -139,8 +149,9 @@ class CustomizedPipelineTemplateApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def delete(self, template_id: str) -> tuple[str, int]:
-        RagPipelineService.delete_customized_pipeline_template(template_id)
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str, template_id: str) -> tuple[str, int]:
+        RagPipelineService.delete_customized_pipeline_template(template_id, current_tenant_id)
         return "", 204
 
     @setup_required
@@ -168,8 +179,12 @@ class PublishCustomizedPipelineTemplateApi(Resource):
     @account_initialization_required
     @enterprise_license_required
     @knowledge_pipeline_publish_enabled
-    def post(self, pipeline_id: str) -> tuple[str, int]:
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, pipeline_id: str) -> tuple[str, int]:
         payload = CustomizedPipelineTemplatePayload.model_validate(console_ns.payload or {})
         rag_pipeline_service = RagPipelineService()
-        rag_pipeline_service.publish_customized_pipeline_template(pipeline_id, payload.model_dump())
+        rag_pipeline_service.publish_customized_pipeline_template(
+            pipeline_id, payload.model_dump(), current_user, current_tenant_id
+        )
         return "", 204

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

@@ -1,5 +1,6 @@
 import logging
 from collections.abc import Callable
+from functools import wraps
 from typing import Any, Concatenate, NoReturn
 from uuid import UUID
 
@@ -9,27 +10,28 @@ from pydantic import BaseModel, Field
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import Forbidden
 
-from controllers.common.schema import register_schema_models
+from controllers.common.errors import InvalidArgumentError, NotFoundError
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     DraftWorkflowNotExist,
 )
 from controllers.console.app.workflow_draft_variable import (
     _WORKFLOW_DRAFT_VARIABLE_FIELDS,  # type: ignore[private-usage]
+    EnvironmentVariableListResponse,
     workflow_draft_variable_list_model,
     workflow_draft_variable_list_without_value_model,
     workflow_draft_variable_model,
 )
 from controllers.console.datasets.wraps import get_rag_pipeline
-from controllers.console.wraps import account_initialization_required, setup_required
-from controllers.web.error import InvalidArgumentError, NotFoundError
+from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from core.app.file_access import DatabaseFileAccessController
 from core.workflow.variable_prefixes import CONVERSATION_VARIABLE_NODE_ID, SYSTEM_VARIABLE_NODE_ID
 from extensions.ext_database import db
 from factories.file_factory import build_from_mapping, build_from_mappings
 from factories.variable_factory import build_segment_with_type
 from graphon.variables.types import SegmentType
-from libs.login import current_user, login_required
+from libs.login import login_required
 from models import Account
 from models.dataset import Pipeline
 from services.rag_pipeline.rag_pipeline import RagPipelineService
@@ -39,14 +41,9 @@ logger = logging.getLogger(__name__)
 _file_access_controller = DatabaseFileAccessController()
 
 
-def _create_pagination_parser():
-    class PaginationQuery(BaseModel):
-        page: int = Field(default=1, ge=1, le=100_000)
-        limit: int = Field(default=20, ge=1, le=100)
-
-    register_schema_models(console_ns, PaginationQuery)
-
-    return PaginationQuery
+class PaginationQuery(BaseModel):
+    page: int = Field(default=1, ge=1, le=100_000)
+    limit: int = Field(default=20, ge=1, le=100)
 
 
 class WorkflowDraftVariablePatchPayload(BaseModel):
@@ -54,11 +51,11 @@ class WorkflowDraftVariablePatchPayload(BaseModel):
     value: Any | None = None
 
 
-register_schema_models(console_ns, WorkflowDraftVariablePatchPayload)
+register_schema_models(console_ns, PaginationQuery, WorkflowDraftVariablePatchPayload)
 
 
 def _api_prerequisite[T, **P, R](
-    f: Callable[Concatenate[T, P], R],
+    f: Callable[Concatenate[T, Account, P], R],
 ) -> Callable[Concatenate[T, P], R | Response]:
     """Common prerequisites for all draft workflow variable APIs.
 
@@ -74,24 +71,31 @@ def _api_prerequisite[T, **P, R](
     @login_required
     @account_initialization_required
     @get_rag_pipeline
-    def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R | Response:
-        if not isinstance(current_user, Account) or not current_user.has_edit_permission:
+    @with_current_user
+    @wraps(f)
+    def wrapper(self: T, current_user: Account, *args: P.args, **kwargs: P.kwargs) -> R | Response:
+        if not current_user.has_edit_permission:
             raise Forbidden()
-        return f(self, *args, **kwargs)
+        return f(self, current_user, *args, **kwargs)
 
     return wrapper
 
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/variables")
 class RagPipelineVariableCollectionApi(Resource):
+    @console_ns.doc(params=query_params_from_model(PaginationQuery))
+    @console_ns.response(
+        200,
+        "Workflow variables retrieved successfully",
+        workflow_draft_variable_list_without_value_model,
+    )
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_without_value_model)
-    def get(self, pipeline: Pipeline):
+    def get(self, current_user: Account, pipeline: Pipeline):
         """
         Get draft workflow
         """
-        pagination = _create_pagination_parser()
-        query = pagination.model_validate(request.args.to_dict())
+        query = PaginationQuery.model_validate(request.args.to_dict())
 
         # fetch draft workflow by app_model
         rag_pipeline_service = RagPipelineService()
@@ -113,8 +117,9 @@ class RagPipelineVariableCollectionApi(Resource):
 
         return workflow_vars
 
+    @console_ns.response(204, "Workflow variables deleted successfully")
     @_api_prerequisite
-    def delete(self, pipeline: Pipeline):
+    def delete(self, current_user: Account, pipeline: Pipeline):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
@@ -143,9 +148,10 @@ def validate_node_id(node_id: str) -> NoReturn | None:
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/nodes/<string:node_id>/variables")
 class RagPipelineNodeVariableCollectionApi(Resource):
+    @console_ns.response(200, "Node variables retrieved successfully", workflow_draft_variable_list_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
-    def get(self, pipeline: Pipeline, node_id: str):
+    def get(self, current_user: Account, pipeline: Pipeline, node_id: str):
         validate_node_id(node_id)
         with sessionmaker(bind=db.engine, expire_on_commit=False).begin() as session:
             draft_var_srv = WorkflowDraftVariableService(
@@ -155,8 +161,9 @@ class RagPipelineNodeVariableCollectionApi(Resource):
 
         return node_vars
 
+    @console_ns.response(204, "Node variables deleted successfully")
     @_api_prerequisite
-    def delete(self, pipeline: Pipeline, node_id: str):
+    def delete(self, current_user: Account, pipeline: Pipeline, node_id: str):
         validate_node_id(node_id)
         srv = WorkflowDraftVariableService(db.session())
         srv.delete_node_variables(pipeline.id, node_id, user_id=current_user.id)
@@ -169,9 +176,10 @@ class RagPipelineVariableApi(Resource):
     _PATCH_NAME_FIELD = "name"
     _PATCH_VALUE_FIELD = "value"
 
+    @console_ns.response(200, "Variable retrieved successfully", workflow_draft_variable_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
-    def get(self, pipeline: Pipeline, variable_id: UUID):
+    def get(self, _current_user: Account, pipeline: Pipeline, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
@@ -183,10 +191,11 @@ class RagPipelineVariableApi(Resource):
             raise NotFoundError(description=f"variable not found, id={variable_id_str}")
         return variable
 
+    @console_ns.response(200, "Variable updated successfully", workflow_draft_variable_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
     @console_ns.expect(console_ns.models[WorkflowDraftVariablePatchPayload.__name__])
-    def patch(self, pipeline: Pipeline, variable_id: UUID):
+    def patch(self, _current_user: Account, pipeline: Pipeline, variable_id: UUID):
         # Request payload for file types:
         #
         # Local File:
@@ -254,8 +263,9 @@ class RagPipelineVariableApi(Resource):
         db.session.commit()
         return variable
 
+    @console_ns.response(204, "Variable deleted successfully")
     @_api_prerequisite
-    def delete(self, pipeline: Pipeline, variable_id: UUID):
+    def delete(self, _current_user: Account, pipeline: Pipeline, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
@@ -272,8 +282,10 @@ class RagPipelineVariableApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/variables/<uuid:variable_id>/reset")
 class RagPipelineVariableResetApi(Resource):
+    @console_ns.response(200, "Variable reset successfully", workflow_draft_variable_model)
+    @console_ns.response(204, "Variable reset (no content)")
     @_api_prerequisite
-    def put(self, pipeline: Pipeline, variable_id: UUID):
+    def put(self, _current_user: Account, pipeline: Pipeline, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
@@ -299,32 +311,38 @@ class RagPipelineVariableResetApi(Resource):
             return marshal(resetted, _WORKFLOW_DRAFT_VARIABLE_FIELDS)
 
 
-def _get_variable_list(pipeline: Pipeline, node_id) -> WorkflowDraftVariableList:
+def _get_variable_list(pipeline: Pipeline, node_id: str, current_user_id: str) -> WorkflowDraftVariableList:
     with sessionmaker(bind=db.engine, expire_on_commit=False).begin() as session:
         draft_var_srv = WorkflowDraftVariableService(
             session=session,
         )
         if node_id == CONVERSATION_VARIABLE_NODE_ID:
-            draft_vars = draft_var_srv.list_conversation_variables(pipeline.id, user_id=current_user.id)
+            draft_vars = draft_var_srv.list_conversation_variables(pipeline.id, user_id=current_user_id)
         elif node_id == SYSTEM_VARIABLE_NODE_ID:
-            draft_vars = draft_var_srv.list_system_variables(pipeline.id, user_id=current_user.id)
+            draft_vars = draft_var_srv.list_system_variables(pipeline.id, user_id=current_user_id)
         else:
-            draft_vars = draft_var_srv.list_node_variables(app_id=pipeline.id, node_id=node_id, user_id=current_user.id)
+            draft_vars = draft_var_srv.list_node_variables(app_id=pipeline.id, node_id=node_id, user_id=current_user_id)
     return draft_vars
 
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/system-variables")
 class RagPipelineSystemVariableCollectionApi(Resource):
+    @console_ns.response(200, "System variables retrieved successfully", workflow_draft_variable_list_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
-    def get(self, pipeline: Pipeline):
-        return _get_variable_list(pipeline, SYSTEM_VARIABLE_NODE_ID)
+    def get(self, current_user: Account, pipeline: Pipeline):
+        return _get_variable_list(pipeline, SYSTEM_VARIABLE_NODE_ID, current_user.id)
 
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/environment-variables")
 class RagPipelineEnvironmentVariableCollectionApi(Resource):
+    @console_ns.response(
+        200,
+        "Environment variables retrieved successfully",
+        console_ns.models[EnvironmentVariableListResponse.__name__],
+    )
     @_api_prerequisite
-    def get(self, pipeline: Pipeline):
+    def get(self, _current_user: Account, pipeline: Pipeline):
         """
         Get draft workflow
         """

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

@@ -5,14 +5,14 @@ from uuid import UUID
 
 from flask import abort, request
 from flask_restx import Resource
-from pydantic import BaseModel, Field, ValidationError
+from pydantic import BaseModel, Field, RootModel, ValidationError
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import BadRequest, Forbidden, InternalServerError, NotFound
 
 import services
 from controllers.common.controller_schemas import DefaultBlockConfigQuery, WorkflowListQuery, WorkflowUpdatePayload
 from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     ConversationCompletedError,
@@ -21,6 +21,8 @@ from controllers.console.app.error import (
 )
 from controllers.console.app.workflow import (
     RESTORE_SOURCE_WORKFLOW_MUST_BE_PUBLISHED_MESSAGE,
+    DefaultBlockConfigResponse,
+    DefaultBlockConfigsResponse,
     WorkflowPaginationResponse,
     WorkflowResponse,
 )
@@ -29,6 +31,8 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.apps.base_app_queue_manager import AppQueueManager
@@ -46,7 +50,7 @@ from fields.workflow_run_fields import (
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs import helper
 from libs.helper import TimestampField, UUIDStrOrEmpty, dump_response
-from libs.login import current_account_with_tenant, current_user, login_required
+from libs.login import login_required
 from models import Account
 from models.dataset import Pipeline
 from models.model import EndUser
@@ -65,14 +69,14 @@ logger = logging.getLogger(__name__)
 class DraftWorkflowSyncPayload(BaseModel):
     graph: dict[str, Any]
     hash: str | None = None
-    environment_variables: list[dict[str, Any]] | None = None
-    conversation_variables: list[dict[str, Any]] | None = None
-    rag_pipeline_variables: list[dict[str, Any]] | None = None
-    features: dict[str, Any] | None = None
+    environment_variables: list[dict[str, Any]] | None = Field(default=None)
+    conversation_variables: list[dict[str, Any]] | None = Field(default=None)
+    rag_pipeline_variables: list[dict[str, Any]] | None = Field(default=None)
+    features: dict[str, Any] | None = Field(default=None)
 
 
 class NodeRunPayload(BaseModel):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class NodeRunRequiredPayload(BaseModel):
@@ -129,6 +133,14 @@ class RagPipelineWorkflowPublishResponse(ResponseModel):
     created_at: int
 
 
+class RagPipelineOpaqueResponse(RootModel[Any]):
+    root: Any
+
+
+class RagPipelineStepParametersResponse(ResponseModel):
+    variables: Any
+
+
 register_schema_models(
     console_ns,
     DraftWorkflowSyncPayload,
@@ -147,6 +159,10 @@ register_schema_models(
 )
 register_response_schema_models(
     console_ns,
+    DefaultBlockConfigResponse,
+    DefaultBlockConfigsResponse,
+    RagPipelineOpaqueResponse,
+    RagPipelineStepParametersResponse,
     RagPipelineWorkflowPublishResponse,
     RagPipelineWorkflowSyncResponse,
     SimpleResultResponse,
@@ -187,16 +203,15 @@ class DraftRagPipelineApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
     @edit_permission_required
+    @console_ns.expect(console_ns.models[DraftWorkflowSyncPayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[RagPipelineWorkflowSyncResponse.__name__])
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Sync draft workflow
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         content_type = request.headers.get("Content-Type", "")
 
         if "application/json" in content_type:
@@ -244,18 +259,17 @@ class DraftRagPipelineApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/iteration/nodes/<string:node_id>/run")
 class RagPipelineDraftRunIterationNodeApi(Resource):
     @console_ns.expect(console_ns.models[NodeRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
     @edit_permission_required
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run draft workflow iteration node
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = NodeRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump(exclude_none=True)
 
@@ -279,18 +293,17 @@ class RagPipelineDraftRunIterationNodeApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/loop/nodes/<string:node_id>/run")
 class RagPipelineDraftRunLoopNodeApi(Resource):
     @console_ns.expect(console_ns.models[NodeRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run draft workflow loop node
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = NodeRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump(exclude_none=True)
 
@@ -314,18 +327,17 @@ class RagPipelineDraftRunLoopNodeApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/run")
 class DraftRagPipelineRunApi(Resource):
     @console_ns.expect(console_ns.models[DraftWorkflowRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Run draft workflow
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = DraftWorkflowRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump()
 
@@ -346,18 +358,17 @@ class DraftRagPipelineRunApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/run")
 class PublishedRagPipelineRunApi(Resource):
     @console_ns.expect(console_ns.models[PublishedWorkflowRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Run published workflow
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = PublishedWorkflowRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump(exclude_none=True)
         streaming = payload.response_mode == "streaming"
@@ -379,18 +390,17 @@ class PublishedRagPipelineRunApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/datasource/nodes/<string:node_id>/run")
 class RagPipelinePublishedDatasourceNodeRunApi(Resource):
     @console_ns.expect(console_ns.models[DatasourceNodeRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run rag pipeline datasource
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = DatasourceNodeRunPayload.model_validate(console_ns.payload or {})
 
         rag_pipeline_service = RagPipelineService()
@@ -412,18 +422,17 @@ class RagPipelinePublishedDatasourceNodeRunApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/datasource/nodes/<string:node_id>/run")
 class RagPipelineDraftDatasourceNodeRunApi(Resource):
     @console_ns.expect(console_ns.models[DatasourceNodeRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @edit_permission_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run rag pipeline datasource
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = DatasourceNodeRunPayload.model_validate(console_ns.payload or {})
 
         rag_pipeline_service = RagPipelineService()
@@ -454,14 +463,12 @@ class RagPipelineDraftNodeRunApi(Resource):
     @login_required
     @edit_permission_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run draft workflow node
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = NodeRunRequiredPayload.model_validate(console_ns.payload or {})
         inputs = payload.inputs
 
@@ -485,14 +492,12 @@ class RagPipelineTaskStopApi(Resource):
     @login_required
     @edit_permission_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, task_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, task_id: str):
         """
         Stop workflow task
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         AppQueueManager.set_stop_flag(task_id, InvokeFrom.DEBUGGER, current_user.id)
 
         return {"result": "success"}
@@ -532,13 +537,12 @@ class PublishedRagPipelineApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Publish workflow
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
         rag_pipeline_service = RagPipelineService()
         workflow = rag_pipeline_service.publish_workflow(
             session=db.session,  # type: ignore[reportArgumentType,arg-type]
@@ -558,6 +562,11 @@ class PublishedRagPipelineApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/default-workflow-block-configs")
 class DefaultRagPipelineBlockConfigsApi(Resource):
+    @console_ns.response(
+        200,
+        "Default block configs retrieved successfully",
+        console_ns.models[DefaultBlockConfigsResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -574,6 +583,12 @@ class DefaultRagPipelineBlockConfigsApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/default-workflow-block-configs/<string:block_type>")
 class DefaultRagPipelineBlockConfigApi(Resource):
+    @console_ns.doc(params=query_params_from_model(DefaultBlockConfigQuery))
+    @console_ns.response(
+        200,
+        "Default block config retrieved successfully",
+        console_ns.models[DefaultBlockConfigResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -599,6 +614,7 @@ class DefaultRagPipelineBlockConfigApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows")
 class PublishedAllRagPipelineApi(Resource):
+    @console_ns.doc(params=query_params_from_model(WorkflowListQuery))
     @console_ns.response(
         200,
         "Published workflows retrieved successfully",
@@ -609,13 +625,12 @@ class PublishedAllRagPipelineApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def get(self, pipeline: Pipeline):
+    def get(self, current_user: Account, pipeline: Pipeline):
         """
         Get published workflows
         """
-        current_user, _ = current_account_with_tenant()
-
         query = WorkflowListQuery.model_validate(request.args.to_dict())
 
         page = query.page
@@ -655,9 +670,9 @@ class RagPipelineDraftWorkflowRestoreApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, workflow_id: str):
-        current_user, _ = current_account_with_tenant()
+    def post(self, current_user: Account, pipeline: Pipeline, workflow_id: str):
         rag_pipeline_service = RagPipelineService()
 
         try:
@@ -689,14 +704,13 @@ class RagPipelineByIdApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def patch(self, pipeline: Pipeline, workflow_id: str):
+    @console_ns.expect(console_ns.models[WorkflowUpdatePayload.__name__])
+    def patch(self, current_user: Account, pipeline: Pipeline, workflow_id: str):
         """
         Update workflow attributes
         """
-        # Check permission
-        current_user, _ = current_account_with_tenant()
-
         payload = WorkflowUpdatePayload.model_validate(console_ns.payload or {})
         update_data = payload.model_dump(exclude_unset=True)
 
@@ -754,6 +768,8 @@ class RagPipelineByIdApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/processing/parameters")
 class PublishedRagPipelineSecondStepApi(Resource):
+    @console_ns.doc(params=query_params_from_model(NodeIdQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineStepParametersResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -774,6 +790,8 @@ class PublishedRagPipelineSecondStepApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/pre-processing/parameters")
 class PublishedRagPipelineFirstStepApi(Resource):
+    @console_ns.doc(params=query_params_from_model(NodeIdQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineStepParametersResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -794,6 +812,8 @@ class PublishedRagPipelineFirstStepApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/pre-processing/parameters")
 class DraftRagPipelineFirstStepApi(Resource):
+    @console_ns.doc(params=query_params_from_model(NodeIdQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineStepParametersResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -814,6 +834,8 @@ class DraftRagPipelineFirstStepApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/processing/parameters")
 class DraftRagPipelineSecondStepApi(Resource):
+    @console_ns.doc(params=query_params_from_model(NodeIdQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineStepParametersResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -835,6 +857,7 @@ class DraftRagPipelineSecondStepApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflow-runs")
 class RagPipelineWorkflowRunListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(WorkflowRunQuery))
     @console_ns.response(
         200,
         "Workflow runs retrieved successfully",
@@ -855,7 +878,7 @@ class RagPipelineWorkflowRunListApi(Resource):
             }
         )
         args = {
-            "last_id": str(query.last_id) if query.last_id else None,
+            "last_id": query.last_id or None,
             "limit": query.limit,
         }
 
@@ -901,7 +924,8 @@ class RagPipelineWorkflowRunNodeExecutionListApi(Resource):
     @login_required
     @account_initialization_required
     @get_rag_pipeline
-    def get(self, pipeline: Pipeline, run_id: UUID):
+    @with_current_user
+    def get(self, current_user: Account, pipeline: Pipeline, run_id: UUID):
         """
         Get workflow run node execution list
         """
@@ -922,11 +946,12 @@ class RagPipelineWorkflowRunNodeExecutionListApi(Resource):
 
 @console_ns.route("/rag/pipelines/datasource-plugins")
 class DatasourceListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str):
         return jsonable_encoder(RagPipelineManageService.list_rag_pipeline_datasources(current_tenant_id))
 
 
@@ -958,18 +983,18 @@ class RagPipelineWorkflowLastRunApi(Resource):
 
 @console_ns.route("/rag/pipelines/transform/datasets/<uuid:dataset_id>")
 class RagPipelineTransformApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
-
+    @with_current_user
+    def post(self, current_user: Account, dataset_id: UUID):
         if not (current_user.has_edit_permission or current_user.is_dataset_operator):
             raise Forbidden()
 
         dataset_id_str = str(dataset_id)
         rag_pipeline_transform_service = RagPipelineTransformService()
-        result = rag_pipeline_transform_service.transform_dataset(dataset_id_str)
+        result = rag_pipeline_transform_service.transform_dataset(dataset_id_str, db.session)
         return result
 
 
@@ -984,13 +1009,13 @@ class RagPipelineDatasourceVariableApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
     @edit_permission_required
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Set datasource variables
         """
-        current_user, _ = current_account_with_tenant()
         args = DatasourceVariablesPayload.model_validate(console_ns.payload or {}).model_dump()
 
         rag_pipeline_service = RagPipelineService()
@@ -1006,12 +1031,16 @@ class RagPipelineDatasourceVariableApi(Resource):
 
 @console_ns.route("/rag/pipelines/recommended-plugins")
 class RagPipelineRecommendedPluginApi(Resource):
+    @console_ns.doc(params=query_params_from_model(RagPipelineRecommendedPluginQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user: Account):
         query = RagPipelineRecommendedPluginQuery.model_validate(request.args.to_dict())
 
         rag_pipeline_service = RagPipelineService()
-        recommended_plugins = rag_pipeline_service.get_recommended_plugins(query.type)
+        recommended_plugins = rag_pipeline_service.get_recommended_plugins(query.type, current_user, current_tenant_id)
         return recommended_plugins

api/controllers/console/datasets/website.py

@@ -1,10 +1,10 @@
-from typing import Literal
+from typing import Any, Literal
 
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel
+from pydantic import BaseModel, RootModel
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.datasets.error import WebsiteCrawlError
 from controllers.console.wraps import account_initialization_required, setup_required
@@ -22,7 +22,12 @@ class WebsiteCrawlStatusQuery(BaseModel):
     provider: Literal["firecrawl", "watercrawl", "jinareader"]
 
 
+class WebsiteCrawlResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(console_ns, WebsiteCrawlPayload, WebsiteCrawlStatusQuery)
+register_response_schema_models(console_ns, WebsiteCrawlResponse)
 
 
 @console_ns.route("/website/crawl")
@@ -30,7 +35,7 @@ class WebsiteCrawlApi(Resource):
     @console_ns.doc("crawl_website")
     @console_ns.doc(description="Crawl website content")
     @console_ns.expect(console_ns.models[WebsiteCrawlPayload.__name__])
-    @console_ns.response(200, "Website crawl initiated successfully")
+    @console_ns.response(200, "Website crawl initiated successfully", console_ns.models[WebsiteCrawlResponse.__name__])
     @console_ns.response(400, "Invalid crawl parameters")
     @setup_required
     @login_required
@@ -57,8 +62,8 @@ class WebsiteCrawlStatusApi(Resource):
     @console_ns.doc("get_crawl_status")
     @console_ns.doc(description="Get website crawl status")
     @console_ns.doc(params={"job_id": "Crawl job ID", "provider": "Crawl provider (firecrawl/watercrawl/jinareader)"})
-    @console_ns.expect(console_ns.models[WebsiteCrawlStatusQuery.__name__])
-    @console_ns.response(200, "Crawl status retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WebsiteCrawlStatusQuery))
+    @console_ns.response(200, "Crawl status retrieved successfully", console_ns.models[WebsiteCrawlResponse.__name__])
     @console_ns.response(404, "Crawl job not found")
     @console_ns.response(400, "Invalid provider")
     @setup_required

api/controllers/console/explore/audio.py

@@ -5,7 +5,8 @@ from werkzeug.exceptions import InternalServerError
 
 import services
 from controllers.common.controller_schemas import TextToAudioPayload
-from controllers.common.schema import register_schema_model
+from controllers.common.fields import AudioBinaryResponse, AudioTranscriptResponse
+from controllers.common.schema import register_response_schema_models, register_schema_model
 from controllers.console.app.error import (
     AppUnavailableError,
     AudioTooLargeError,
@@ -34,6 +35,7 @@ from .. import console_ns
 logger = logging.getLogger(__name__)
 
 register_schema_model(console_ns, TextToAudioPayload)
+register_response_schema_models(console_ns, AudioBinaryResponse, AudioTranscriptResponse)
 
 
 @console_ns.route(
@@ -41,6 +43,7 @@ register_schema_model(console_ns, TextToAudioPayload)
     endpoint="installed_app_audio",
 )
 class ChatAudioApi(InstalledAppResource):
+    @console_ns.response(200, "Success", console_ns.models[AudioTranscriptResponse.__name__])
     def post(self, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:
@@ -84,6 +87,7 @@ class ChatAudioApi(InstalledAppResource):
 )
 class ChatTextApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[TextToAudioPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[AudioBinaryResponse.__name__])
     def post(self, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:

api/controllers/console/explore/banner.py

@@ -1,17 +1,44 @@
+from typing import Any, cast
+
 from flask import request
-from flask_restx import Resource
+from flask_restx import Namespace, Resource
+from pydantic import BaseModel, Field, RootModel
 from sqlalchemy import select
 
+from controllers.common.schema import query_params_from_model, register_response_schema_models
 from controllers.console import api
 from controllers.console.explore.wraps import explore_banner_enabled
 from extensions.ext_database import db
+from fields.base import ResponseModel
 from models.enums import BannerStatus
 from models.model import ExporleBanner
 
 
+class BannerListQuery(BaseModel):
+    language: str = Field(default="en-US", description="Banner language")
+
+
+class BannerResponse(ResponseModel):
+    id: str
+    content: Any
+    link: str | None = None
+    sort: int
+    status: str
+    created_at: str | None = None
+
+
+class BannerListResponse(RootModel[list[BannerResponse]]):
+    root: list[BannerResponse]
+
+
+register_response_schema_models(cast(Namespace, api), BannerListResponse)
+
+
 class BannerApi(Resource):
     """Resource for banner list."""
 
+    @api.doc(params=query_params_from_model(BannerListQuery))
+    @api.response(200, "Success", api.models[BannerListResponse.__name__])
     @explore_banner_enabled
     def get(self):
         """Get banner list."""

api/controllers/console/explore/completion.py

@@ -6,7 +6,7 @@ from pydantic import BaseModel, Field, field_validator
 from werkzeug.exceptions import InternalServerError, NotFound
 
 import services
-from controllers.common.fields import SimpleResultResponse
+from controllers.common.fields import GeneratedAppResponse, SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console.app.error import (
     AppUnavailableError,
@@ -18,7 +18,7 @@ from controllers.console.app.error import (
 )
 from controllers.console.explore.error import NotChatAppError, NotCompletionAppError
 from controllers.console.explore.wraps import InstalledAppResource
-from controllers.console.wraps import with_current_user_id
+from controllers.console.wraps import with_current_user, with_current_user_id
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.entities.app_invoke_entities import InvokeFrom
 from core.errors.error import (
@@ -30,7 +30,6 @@ from extensions.ext_database import db
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs import helper
 from libs.datetime_utils import naive_utc_now
-from libs.login import current_user
 from models import Account
 from models.model import AppMode, InstalledApp
 from services.app_generate_service import AppGenerateService
@@ -45,7 +44,7 @@ logger = logging.getLogger(__name__)
 class CompletionMessageExplorePayload(BaseModel):
     inputs: dict[str, Any]
     query: str = ""
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
     response_mode: Literal["blocking", "streaming"] | None = None
     retriever_from: str = Field(default="explore_app")
 
@@ -53,7 +52,7 @@ class CompletionMessageExplorePayload(BaseModel):
 class ChatMessagePayload(BaseModel):
     inputs: dict[str, Any]
     query: str
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
     conversation_id: str | None = None
     parent_message_id: str | None = None
     retriever_from: str = Field(default="explore_app")
@@ -74,7 +73,7 @@ class ChatMessagePayload(BaseModel):
 
 
 register_schema_models(console_ns, CompletionMessageExplorePayload, ChatMessagePayload)
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(console_ns, GeneratedAppResponse, SimpleResultResponse)
 
 
 # define completion api for user
@@ -84,7 +83,9 @@ register_response_schema_models(console_ns, SimpleResultResponse)
 )
 class CompletionApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[CompletionMessageExplorePayload.__name__])
-    def post(self, installed_app: InstalledApp):
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
+    @with_current_user
+    def post(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -101,8 +102,6 @@ class CompletionApi(InstalledAppResource):
         db.session.commit()
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             response = AppGenerateService.generate(
                 app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.EXPLORE, streaming=streaming
             )
@@ -160,7 +159,9 @@ class CompletionStopApi(InstalledAppResource):
 )
 class ChatApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[ChatMessagePayload.__name__])
-    def post(self, installed_app: InstalledApp):
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
+    @with_current_user
+    def post(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -177,8 +178,6 @@ class ChatApi(InstalledAppResource):
         db.session.commit()
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             response = AppGenerateService.generate(
                 app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.EXPLORE, streaming=True
             )

api/controllers/console/explore/conversation.py

@@ -7,10 +7,11 @@ from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import NotFound
 
 from controllers.common.controller_schemas import ConversationRenamePayload
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console.app.error import AppUnavailableError
 from controllers.console.explore.error import NotChatAppError
 from controllers.console.explore.wraps import InstalledAppResource
+from controllers.console.wraps import with_current_user
 from core.app.entities.app_invoke_entities import InvokeFrom
 from extensions.ext_database import db
 from fields.conversation_fields import (
@@ -19,7 +20,6 @@ from fields.conversation_fields import (
     SimpleConversation,
 )
 from libs.helper import UUIDStrOrEmpty
-from libs.login import current_user
 from models import Account
 from models.model import AppMode, InstalledApp
 from services.conversation_service import ConversationService
@@ -36,7 +36,12 @@ class ConversationListQuery(BaseModel):
 
 
 register_schema_models(console_ns, ConversationListQuery, ConversationRenamePayload)
-register_response_schema_models(console_ns, ResultResponse)
+register_response_schema_models(
+    console_ns,
+    ConversationInfiniteScrollPagination,
+    ResultResponse,
+    SimpleConversation,
+)
 
 
 @console_ns.route(
@@ -44,8 +49,10 @@ register_response_schema_models(console_ns, ResultResponse)
     endpoint="installed_app_conversations",
 )
 class ConversationListApi(InstalledAppResource):
-    @console_ns.expect(console_ns.models[ConversationListQuery.__name__])
-    def get(self, installed_app: InstalledApp):
+    @console_ns.doc(params=query_params_from_model(ConversationListQuery))
+    @console_ns.response(200, "Success", console_ns.models[ConversationInfiniteScrollPagination.__name__])
+    @with_current_user
+    def get(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -66,14 +73,12 @@ class ConversationListApi(InstalledAppResource):
         args = ConversationListQuery.model_validate(raw_args)
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             with sessionmaker(db.engine).begin() as session:
                 pagination = WebConversationService.pagination_by_last_id(
                     session=session,
                     app_model=app_model,
                     user=current_user,
-                    last_id=str(args.last_id) if args.last_id else None,
+                    last_id=args.last_id or None,
                     limit=args.limit,
                     invoke_from=InvokeFrom.EXPLORE,
                     pinned=args.pinned,
@@ -95,7 +100,8 @@ class ConversationListApi(InstalledAppResource):
 )
 class ConversationApi(InstalledAppResource):
     @console_ns.response(204, "Conversation deleted successfully")
-    def delete(self, installed_app: InstalledApp, c_id: UUID):
+    @with_current_user
+    def delete(self, current_user: Account, installed_app: InstalledApp, c_id: UUID):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -105,8 +111,6 @@ class ConversationApi(InstalledAppResource):
 
         conversation_id = str(c_id)
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             ConversationService.delete(app_model, conversation_id, current_user)
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
@@ -120,7 +124,9 @@ class ConversationApi(InstalledAppResource):
 )
 class ConversationRenameApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[ConversationRenamePayload.__name__])
-    def post(self, installed_app: InstalledApp, c_id: UUID):
+    @console_ns.response(200, "Conversation renamed successfully", console_ns.models[SimpleConversation.__name__])
+    @with_current_user
+    def post(self, current_user: Account, installed_app: InstalledApp, c_id: UUID):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -133,8 +139,6 @@ class ConversationRenameApi(InstalledAppResource):
         payload = ConversationRenamePayload.model_validate(console_ns.payload or {})
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             conversation = ConversationService.rename(
                 app_model, conversation_id, current_user, payload.name, payload.auto_generate
             )
@@ -153,7 +157,8 @@ class ConversationRenameApi(InstalledAppResource):
 )
 class ConversationPinApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[ResultResponse.__name__])
-    def patch(self, installed_app: InstalledApp, c_id: UUID):
+    @with_current_user
+    def patch(self, current_user: Account, installed_app: InstalledApp, c_id: UUID):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -164,8 +169,6 @@ class ConversationPinApi(InstalledAppResource):
         conversation_id = str(c_id)
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             WebConversationService.pin(app_model, conversation_id, current_user)
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
@@ -179,7 +182,8 @@ class ConversationPinApi(InstalledAppResource):
 )
 class ConversationUnPinApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[ResultResponse.__name__])
-    def patch(self, installed_app: InstalledApp, c_id: UUID):
+    @with_current_user
+    def patch(self, current_user: Account, installed_app: InstalledApp, c_id: UUID):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -188,8 +192,6 @@ class ConversationUnPinApi(InstalledAppResource):
             raise NotChatAppError()
 
         conversation_id = str(c_id)
-        if not isinstance(current_user, Account):
-            raise ValueError("current_user must be an Account instance")
         WebConversationService.unpin(app_model, conversation_id, current_user)
 
         return ResultResponse(result="success").model_dump(mode="json")

api/controllers/console/explore/installed_app.py

@@ -5,11 +5,11 @@ from typing import Any
 from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, computed_field, field_validator
-from sqlalchemy import and_, select
+from sqlalchemy import and_, exists, or_, select
 from werkzeug.exceptions import BadRequest, Forbidden, NotFound
 
 from controllers.common.fields import SimpleMessageResponse, SimpleResultMessageResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.explore.wraps import InstalledAppResource
 from controllers.console.wraps import (
@@ -24,8 +24,8 @@ from graphon.file import helpers as file_helpers
 from libs.datetime_utils import naive_utc_now
 from libs.helper import to_timestamp
 from libs.login import login_required
-from models import Account, App, InstalledApp, RecommendedApp
-from models.model import IconType
+from models import Account, App, AppModelConfig, InstalledApp, RecommendedApp, Workflow
+from models.model import AppMode, IconType
 from services.account_service import TenantService
 from services.enterprise.enterprise_service import EnterpriseService
 from services.feature_service import FeatureService
@@ -61,6 +61,24 @@ def _safe_primitive(value: Any) -> Any:
     return None
 
 
+def _published_app_filter():
+    """Return the SQL predicate for installed-app web API availability.
+
+    The installed-app parameters endpoint reads the published workflow for
+    workflow-style apps and the published app model config for easy UI apps.
+    Keep the list endpoint aligned in SQL so it does not return entries that
+    will immediately fail with app_unavailable when opened.
+    """
+    workflow_app_modes = (AppMode.ADVANCED_CHAT, AppMode.WORKFLOW)
+    has_published_workflow = exists(select(Workflow.id).where(Workflow.id == App.workflow_id))
+    has_published_model_config = exists(select(AppModelConfig.id).where(AppModelConfig.id == App.app_model_config_id))
+
+    return or_(
+        and_(App.mode.in_(workflow_app_modes), App.workflow_id.isnot(None), has_published_workflow),
+        and_(~App.mode.in_(workflow_app_modes), App.app_model_config_id.isnot(None), has_published_model_config),
+    )
+
+
 class InstalledAppInfoResponse(ResponseModel):
     id: str
     name: str | None = None
@@ -135,39 +153,39 @@ register_response_schema_models(console_ns, SimpleMessageResponse, SimpleResultM
 class InstalledAppsListApi(Resource):
     @login_required
     @account_initialization_required
+    @console_ns.doc(params=query_params_from_model(InstalledAppsListQuery))
     @console_ns.response(200, "Success", console_ns.models[InstalledAppListResponse.__name__])
     @with_current_user
     @with_current_tenant_id
     def get(self, current_tenant_id: str, current_user: Account):
         query = InstalledAppsListQuery.model_validate(request.args.to_dict())
 
+        stmt = (
+            select(InstalledApp, App)
+            .join(App, App.id == InstalledApp.app_id)
+            .where(InstalledApp.tenant_id == current_tenant_id, _published_app_filter())
+        )
         if query.app_id:
-            installed_apps = db.session.scalars(
-                select(InstalledApp).where(
-                    and_(InstalledApp.tenant_id == current_tenant_id, InstalledApp.app_id == query.app_id)
-                )
-            ).all()
-        else:
-            installed_apps = db.session.scalars(
-                select(InstalledApp).where(InstalledApp.tenant_id == current_tenant_id)
-            ).all()
+            stmt = stmt.where(InstalledApp.app_id == query.app_id)
+
+        installed_apps = db.session.execute(stmt).all()
 
         if current_user.current_tenant is None:
             raise ValueError("current_user.current_tenant must not be None")
         current_user.role = TenantService.get_user_role(current_user, current_user.current_tenant)
-        installed_app_list: list[dict[str, Any]] = [
-            {
-                "id": installed_app.id,
-                "app": installed_app.app,
-                "app_owner_tenant_id": installed_app.app_owner_tenant_id,
-                "is_pinned": installed_app.is_pinned,
-                "last_used_at": installed_app.last_used_at,
-                "editable": current_user.role in {"owner", "admin"},
-                "uninstallable": current_tenant_id == installed_app.app_owner_tenant_id,
-            }
-            for installed_app in installed_apps
-            if installed_app.app is not None
-        ]
+        installed_app_list: list[dict[str, Any]] = []
+        for installed_app, app_model in installed_apps:
+            installed_app_list.append(
+                {
+                    "id": installed_app.id,
+                    "app": app_model,
+                    "app_owner_tenant_id": installed_app.app_owner_tenant_id,
+                    "is_pinned": installed_app.is_pinned,
+                    "last_used_at": installed_app.last_used_at,
+                    "editable": current_user.role in {"owner", "admin"},
+                    "uninstallable": current_tenant_id == installed_app.app_owner_tenant_id,
+                }
+            )
 
         # filter out apps that user doesn't have access to
         if FeatureService.get_system_features().webapp_auth.enabled:
@@ -217,6 +235,7 @@ class InstalledAppsListApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_resource_check("apps")
+    @console_ns.expect(console_ns.models[InstalledAppCreatePayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[SimpleMessageResponse.__name__])
     @with_current_tenant_id
     def post(self, current_tenant_id: str):
@@ -278,6 +297,7 @@ class InstalledAppApi(InstalledAppResource):
         return "", 204
 
     @console_ns.response(200, "Success", console_ns.models[SimpleResultMessageResponse.__name__])
+    @console_ns.expect(console_ns.models[InstalledAppUpdatePayload.__name__])
     def patch(self, installed_app: InstalledApp):
         payload = InstalledAppUpdatePayload.model_validate(console_ns.payload or {})
 

api/controllers/console/explore/message.py

@@ -7,7 +7,8 @@ from pydantic import BaseModel, TypeAdapter
 from werkzeug.exceptions import InternalServerError, NotFound
 
 from controllers.common.controller_schemas import MessageFeedbackPayload, MessageListQuery
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.fields import GeneratedAppResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console.app.error import (
     AppMoreLikeThisDisabledError,
     AppUnavailableError,
@@ -52,7 +53,13 @@ class MoreLikeThisQuery(BaseModel):
 
 
 register_schema_models(console_ns, MessageListQuery, MessageFeedbackPayload, MoreLikeThisQuery)
-register_response_schema_models(console_ns, ResultResponse, SuggestedQuestionsResponse)
+register_response_schema_models(
+    console_ns,
+    GeneratedAppResponse,
+    MessageInfiniteScrollPagination,
+    ResultResponse,
+    SuggestedQuestionsResponse,
+)
 
 
 @console_ns.route(
@@ -60,7 +67,8 @@ register_response_schema_models(console_ns, ResultResponse, SuggestedQuestionsRe
     endpoint="installed_app_messages",
 )
 class MessageListApi(InstalledAppResource):
-    @console_ns.expect(console_ns.models[MessageListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(MessageListQuery))
+    @console_ns.response(200, "Success", console_ns.models[MessageInfiniteScrollPagination.__name__])
     @with_current_user
     def get(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app
@@ -129,7 +137,8 @@ class MessageFeedbackApi(InstalledAppResource):
     endpoint="installed_app_more_like_this",
 )
 class MessageMoreLikeThisApi(InstalledAppResource):
-    @console_ns.expect(console_ns.models[MoreLikeThisQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(MoreLikeThisQuery))
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
     @with_current_user
     def get(self, current_user: Account, installed_app: InstalledApp, message_id: UUID):
         app_model = installed_app.app

api/controllers/console/explore/parameter.py

@@ -1,6 +1,9 @@
 from typing import Any, cast
 
+from pydantic import BaseModel, Field
+
 from controllers.common import fields
+from controllers.common.schema import register_response_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import AppUnavailableError
 from controllers.console.explore.wraps import InstalledAppResource
@@ -9,10 +12,18 @@ from models.model import AppMode, InstalledApp
 from services.app_service import AppService
 
 
+class ExploreAppMetaResponse(BaseModel):
+    tool_icons: dict[str, Any] = Field(default_factory=dict)
+
+
+register_response_schema_models(console_ns, fields.Parameters, ExploreAppMetaResponse)
+
+
 @console_ns.route("/installed-apps/<uuid:installed_app_id>/parameters", endpoint="installed_app_parameters")
 class AppParameterApi(InstalledAppResource):
     """Resource for app variables."""
 
+    @console_ns.response(200, "Success", console_ns.models[fields.Parameters.__name__])
     def get(self, installed_app: InstalledApp):
         """Retrieve app parameters."""
         app_model = installed_app.app
@@ -42,6 +53,7 @@ class AppParameterApi(InstalledAppResource):
 
 @console_ns.route("/installed-apps/<uuid:installed_app_id>/meta", endpoint="installed_app_meta")
 class ExploreAppMetaApi(InstalledAppResource):
+    @console_ns.response(200, "Success", console_ns.models[ExploreAppMetaResponse.__name__])
     def get(self, installed_app: InstalledApp):
         """Get app meta"""
         app_model = installed_app.app