refactor(web): migrate handwritten console API calls to the generated oRPC contract

[hyoban]

Summary

Replace the handwritten get / post / put / patch / del console calls in web/ with the generated console contract (consoleQuery / consoleClient from @/service/console). The work is split into one commit per module. Where backend endpoints read query params or bodies that their OpenAPI docs did not declare, the docs were fixed so the generated contract types them.

Migrated

• Logs, annotations, agent logs: use-log, annotation, log messages, and agent thoughts.
• Model providers: credentials, default model, enable/disable, and parameter rules.
• Workspace: members, RBAC roles, workspace info, and permission.
• Small modules: publish, Notion import, and hit testing.
• Account: auth flows, setup/init, account deletion, email change, and ownership transfer (service/common).
• service/use-common: everything except one broken flow, listed below.
• Datasets and knowledge: service/datasets and service/knowledge/use-{dataset,document,segment,metadata,create-dataset}.
• Plugins: use-plugins (install, upgrade, upload, permission and auto-upgrade settings, debugging key, tasks, dynamic options) and plugins.ts.
• Tools: tools.ts and use-tools.ts (built-in, API, workflow and MCP tools, MCP servers, app triggers).
• RAG pipelines and datasources: use-pipeline and use-datasource.
• Workflow draft calls: node run, inspect variables, last run, system/conversation variables, and variable reset/edit/delete. These go per flow type (app, RAG pipeline, snippet) through a typed callByFlowType helper.
• Debug: chat history and suggested questions (now with a real AbortSignal), rule and instruction generation, prompt templates, and message detail.

Some UI types narrow fields that backend response models declare as plain strings or loose records: enum-like statuses, doc_form, plugin source, locale label maps. Those responses are narrowed once at the service boundary with a documented narrowResponse helper (service/console/narrow-response.ts) instead of retyping every consumer. Where a UI type was simply wrong, it now aliases or follows the generated type.

Bugs and mismatches the contract surfaced

• Schema-name collisions. Flask-RESTX registered Pydantic schemas by bare class name, so same-named types overwrote each other. Registration now fails on a conflicting name.
• Annotation batch delete. Array params were serialized with indexed keys, so a batch delete could clear all annotations. Repeated-key rules now cover annotations and document batch delete/status.
• 204 responses. Deleting an external knowledge API and retrying error docs return 204. The UI only worked because the legacy fetch layer rewrote 204 into {result: 'success'}; callers now treat a resolved request as success.
• Dataset update body. The type declared partial_member_list as string[], but the UI sends {user_id, role} objects. It now uses the generated type.
• Removed endpoints still called: /tool-provider/model/tools (the backend has no model tool provider type; the fetch and the isModel prop chain were removed).
• Missing required fields:
  • Plugin dynamic options require provider_type, which callers could leave unset. It now defaults to tool.
  • Document creation requires indexing_technique.
  • Workflow tool requests carry label.
  • MCP provider requests carry server_identifier.
• Wrong UI types: member roles and timestamps, model parameter required, Notion icons without a type (now dropped), and icon_background nullability.
• Response fields the backend never sends: workflow log read_at (the unread dot always renders; behaviour kept) and the conversation introduction, which lives at the top level.
• Pipeline conversation variables. The UI queried them, but RAG pipelines have no such endpoint. The query now resolves empty for pipelines.

Not migrated (intentionally)

• Handwritten flows that don't match the backend:
  • The forgot-password token flow: the endpoint requires email and code.
  • The legacy built-in tool credential modal: the schema moved, credentials became a list, and update/delete need a credential_id. Only non-plugin providers reach it, and none of them need credentials.
• Hooks that take prebuilt URL strings: workflow draft fetch/sync, run history, run detail and tracing, version history, publish/restore/delete, stop run, human-input step forms, the plugin-auth credential registry (plugin-auth/hooks/use-get-api), and the one-step-run iteration/loop endpoints. Each needs its call sites redesigned around ids instead of URLs.
• Streaming, binary and multipart transfers: SSE runs, file and skill uploads, the documents zip, skill blob downloads, and annotation batch import.
• Marketplace calls: they hit the external marketplace API, and its hand-written contract does not cover these endpoints.
• Public web-app APIs: share.ts, sso.ts, and the web-app login helpers in common.ts. They need a web-app contract client.
• Endpoints without a contract: enterprise web-app access control, /x-version and /x-env.

Follow-ups

• Declare literal types on backend response models (statuses, doc_form, plugin source, label maps) so narrowResponse call sites can be dropped.
• Make fields with defaults required in response schemas (json_schema_serialization_defaults_required).
• Redesign the URL-string registries listed above around ids so they can use the contract.
• Add a web-app (public API) oRPC client for share.ts and the web-app helpers.
• Rebuild or remove the legacy built-in tool credential modal.

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've verified the change and added or updated tests where meaningful regression risk justifies coverage.
• I've updated the documentation accordingly.
• I ran make lint && make type-check (backend) and vp staged (frontend) to appease the lint gods

Verification per commit: tsc --noEmit, vp lint, knip, the spec files that import each migrated module, and the touched backend controller tests. The full web suite was not run locally.

🤖 Generated with Claude Code

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-10-15 22:12:54.717570585 +0000
+++ /tmp/pyrefly_pr.txt	2026-10-15 22:12:46.133473321 +0000
@@ -1576,6 +1576,8 @@
    --> tests/unit_tests/commands/test_upgrade_db.py:128:5
 ERROR No attribute `MethodView` in module `builtins` [missing-attribute]
  --> tests/unit_tests/controllers/common/test_fields.py:8:5
+ERROR No matching overload found for function `pydantic.main.create_model` called with arguments: (Literal['UserModel'], __module__=Literal['other_module'], **dict[str, tuple[type[Any], EllipsisType]]) [no-matching-overload]
+   --> tests/unit_tests/controllers/common/test_schema.py:133:24
 ERROR Object of class `int` has no attribute `lower` [missing-attribute]
    --> tests/unit_tests/controllers/console/app/test_annotation_security.py:237:38
 ERROR Object of class `int` has no attribute `lower` [missing-attribute]

[github-actions]

Pyrefly Type Coverage

Metric	Base	PR	Delta
Type coverage	75.04%	75.04%	-0.01%
Strict coverage	74.71%	74.71%	-0.01%
Typed symbols	61,998	62,004	+6
Untyped symbols	20,710	20,719	+9
Modules	3796	3797	+1

[codecov]

Codecov Report

❌ Patch coverage is 95.25424% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.10%. Comparing base (8c5eb6d) to head (c08553f).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
...ole/datasets/rag_pipeline/rag_pipeline_workflow.py	86.20%	4 Missing ⚠️
web/app/components/app/log/list.tsx	86.20%	4 Missing ⚠️
...pp/account/(commonLayout)/delete-account/state.tsx	0.00%	3 Missing ⚠️
...p/access-point/built-in-access-points/mcp-card.tsx	70.00%	3 Missing ⚠️
...figuration/dataset-config/settings-modal/index.tsx	83.33%	3 Missing ⚠️
web/app/components/app/log/list-utils.ts	96.34%	3 Missing ⚠️
...nts/app/annotation/view-annotation-modal/index.tsx	85.71%	2 Missing ⚠️
.../app/components/base/agent-log-modal/tool-call.tsx	75.00%	2 Missing ⚠️
...i/controllers/console/snippets/snippet_workflow.py	66.66%	1 Missing ⚠️
web/app/components/app/annotation/list.tsx	80.00%	1 Missing ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #44169      +/-   ##
==========================================
+ Coverage   88.94%   89.10%   +0.16%     
==========================================
  Files        5304     5305       +1     
  Lines      326595   326570      -25     
  Branches    63840    64242     +402     
==========================================
+ Hits       290497   291005     +508     
+ Misses      30900    30371     -529     
+ Partials     5198     5194       -4     

Flag	Coverage Δ
api	88.57% <98.32%> (+0.04%)	⬆️
cli	90.56% <ø> (ø)
dify-ui	92.25% <ø> (ø)
web	89.70% <92.09%> (+0.35%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Vinext bundle analysis

JS gzip: 🟢 −4.65 KiB (−0.05%) · CSS gzip: ⚪ No change

All client output	Base gzip → Merge gzip	Gzip change
JS	9937.20 KiB → 9932.55 KiB	🟢 −4.65 KiB (−0.05%)
CSS	332.39 KiB → 332.39 KiB	⚪ No change

Entry changes: 🟠 5 increased · 🟢 166 decreased (gzip).

Largest entry changes

Top 5 by absolute gzip delta. Static dependencies overlap; do not sum entries.

Source entry	Base gzip → Merge gzip	Gzip change
app/components/workflow/nodes/data-source/panel.tsx	1048.83 KiB → 1075.09 KiB	🟠 +26.26 KiB (+2.50%)
app/(shareLayout)/chatbot/[token]/page.tsx	1011.29 KiB → 999.99 KiB	🟢 −11.29 KiB (−1.12%)
app/(shareLayout)/agent/[token]/page.tsx	1035.03 KiB → 1023.76 KiB	🟢 −11.27 KiB (−1.09%)
app/(shareLayout)/chat/[token]/page.tsx	1032.45 KiB → 1021.18 KiB	🟢 −11.27 KiB (−1.09%)
app/(shareLayout)/environment/chat/[token]/page.tsx	1032.45 KiB → 1021.18 KiB	🟢 −11.27 KiB (−1.09%)

Top 20 of 171 changed entries (full paths and raw sizes)

Source entry	Base gzip → Merge gzip	Gzip change	Raw change
dynamic-entry: app/components/workflow/nodes/data-source/panel.tsx	1048.83 KiB → 1075.09 KiB	🟠 +26.26 KiB (+2.50%)	🟠 +99.04 KiB (+2.93%)
dynamic-entry: app/(shareLayout)/chatbot/[token]/page.tsx	1011.29 KiB → 999.99 KiB	🟢 −11.29 KiB (−1.12%)	🟢 −25.76 KiB (−0.81%)
dynamic-entry: app/(shareLayout)/agent/[token]/page.tsx	1035.03 KiB → 1023.76 KiB	🟢 −11.27 KiB (−1.09%)	🟢 −25.53 KiB (−0.78%)
dynamic-entry: app/(shareLayout)/chat/[token]/page.tsx	1032.45 KiB → 1021.18 KiB	🟢 −11.27 KiB (−1.09%)	🟢 −25.53 KiB (−0.78%)
dynamic-entry: app/(shareLayout)/environment/chat/[token]/page.tsx	1032.45 KiB → 1021.18 KiB	🟢 −11.27 KiB (−1.09%)	🟢 −25.53 KiB (−0.78%)
dynamic-entry: app/components/base/chat/chat-with-history/index.tsx	1029.96 KiB → 1018.69 KiB	🟢 −11.27 KiB (−1.09%)	🟢 −25.53 KiB (−0.78%)
dynamic-entry: app/components/explore/try-app/app/index.tsx	1039.61 KiB → 1028.36 KiB	🟢 −11.25 KiB (−1.08%)	🟢 −25.46 KiB (−0.77%)
dynamic-entry: app/components/datasets/create/index.tsx	683.72 KiB → 672.87 KiB	🟢 −10.85 KiB (−1.59%)	🟢 −25.42 KiB (−1.17%)
dynamic-entry: app/components/datasets/documents/detail/index.tsx	815.96 KiB → 805.26 KiB	🟢 −10.70 KiB (−1.31%)	🟢 −24.80 KiB (−0.93%)
dynamic-entry: app/components/datasets/create-from-pipeline/index.tsx	689.25 KiB → 678.65 KiB	🟢 −10.60 KiB (−1.54%)	🟢 −25.70 KiB (−1.17%)
dynamic-entry: app/components/app-sidebar/dataset-detail-sidebar.tsx	539.57 KiB → 529.25 KiB	🟢 −10.32 KiB (−1.91%)	🟢 −25.97 KiB (−1.52%)
dynamic-entry: app/components/app/log-annotation/index.tsx	1060.35 KiB → 1050.24 KiB	🟢 −10.11 KiB (−0.95%)	🟢 −22.65 KiB (−0.68%)
dynamic-entry: app/components/datasets/settings/form/index.tsx	662.80 KiB → 652.79 KiB	🟢 −10.01 KiB (−1.51%)	🟢 −22.88 KiB (−1.09%)
dynamic-entry: app/components/datasets/hit-testing/index.tsx	666.52 KiB → 656.58 KiB	🟢 −9.94 KiB (−1.49%)	🟢 −23.37 KiB (−1.11%)
dynamic-entry: app/components/explore/try-app/index.tsx	1340.34 KiB → 1331.18 KiB	🟢 −9.17 KiB (−0.68%)	🟢 −19.06 KiB (−0.44%)
dynamic-entry: app/components/datasets/documents/create-from-pipeline/index.tsx	889.03 KiB → 879.88 KiB	🟢 −9.15 KiB (−1.03%)	🟢 −21.87 KiB (−0.77%)
dynamic-entry: app/components/datasets/documents/detail/settings/index.tsx	825.91 KiB → 817.02 KiB	🟢 −8.90 KiB (−1.08%)	🟢 −21.40 KiB (−0.81%)
dynamic-entry: app/components/app/configuration/index.tsx	1386.85 KiB → 1378.29 KiB	🟢 −8.57 KiB (−0.62%)	🟢 −17.05 KiB (−0.38%)
dynamic-entry: app/components/workflow/panel/chat-record/index.tsx	1411.79 KiB → 1403.23 KiB	🟢 −8.56 KiB (−0.61%)	🟢 −15.89 KiB (−0.35%)
dynamic-entry: app/components/workflow/panel/debug-and-preview/index.tsx	1418.44 KiB → 1409.89 KiB	🟢 −8.55 KiB (−0.60%)	🟢 −15.89 KiB (−0.35%)

📦 3 package attribution changes (uncompressed modules)

Showing 3 of 3, ordered by absolute module-size delta.

Package	Base	Merge	Δ
qs	40.48 KiB	0.00 KiB	🟢 −40.48 KiB (−100.00%)
@nolyfill/side-channel	1.37 KiB	0.00 KiB	🟢 −1.37 KiB (−100.00%)
es-define-property	0.28 KiB	0.00 KiB	🟢 −288 B (−100.00%)

Measurement details and build revisions

Base: 8c5eb6d16e97edad3c84e0b7d25408e40fbd8a7a · Merge: 09f8494641e840cb6d7f7d4a8c896c9812ee3a4f
Vinext: 1.1.0 → 1.1.0; Rolldown: 1.2.12 → 1.2.12

Raw JS change: 🟠 +2.38 KiB (+<0.01%) · Raw CSS change: ⚪ No change

🟠 Increase · 🟢 Decrease · ⚪ Unchanged. Colors indicate direction, not a performance budget verdict. Percentages use the base size.

Entries follow only static edges in the official Rolldown chunk graph, deduplicating shared files. Dynamic entries are measured when loaded; they are not page first-load metrics. Entry totals overlap and must not be summed.
Package attribution sums module sizes reported by Rolldown, not compressed emitted bytes. Gzip totals are measured per emitted file. This is Vinext output, not Next.js/Turbopack output.
Report only: increases do not fail this check. Missing or incompatible analysis data does.

Download base/merge snapshots and official Rolldown analysis reports.

Comparison: event base SHA vs the tested merge commit at GITHUB_SHA (PR or merge queue).