refactor(deployments): move flow-version tool_name into provider_data

Move provider tool_name from a top-level flow-version response field into
provider_data, aligning API ownership boundaries for provider-originated
non-persisted fields.
- Remove top-level tool_name from DeploymentFlowVersionListItem
- Add tool_name to WatsonxApiDeploymentFlowVersionItemData with normalization
- Update WXO mapper to shape tool_name under provider_data
- Update frontend attachments type and consumer to read provider_data.tool_name
- Update backend tests for new response contract location
- Add explicit RULES.md requirement for non-persisted provider data placement

Author: HzaRashid

src/backend/base/langflow/api/v1/mappers/deployments/RULES.md

@@ -412,6 +412,7 @@ Use this checklist before merge:
 - [ ] Provider-account update logic lives in mapper, not in route conditionals
 - [ ] Provider-specific cross-field rules (e.g. tenant/URL coupling) are implemented as mapper overrides calling `super()`, not as base-class conditionals
 - [ ] Credential extraction uses `resolve_credential_fields`, not route-level assumptions about `provider_data` contents
+- [ ] Non-persisted provider-originated fields are placed in `provider_data` (never top-level)
 - [ ] DB-level consistency validators exist as defense-in-depth for cross-field invariants
 - [ ] Tests cover both base mapper defaults and provider overrides
 - [ ] Failure cases for missing/unexpected bindings are covered
@@ -556,3 +557,14 @@ When adding a new field to an execution or deployment response:
 1. Is Langflow the source of truth for this value? → top level.
 2. Does this value come from the provider and Langflow just relays it? → inside `provider_data`.
 3. Does the provider supply it but Langflow persists and indexes it (like `resource_key`)? → top level is acceptable.
+
+### 14.4 Hard placement rule for non-persisted provider data
+
+If data is not persisted in the Langflow DB and comes directly from the provider,
+it must go into `provider_data`.
+
+Rules:
+
+- Top-level response fields are reserved for values that Langflow persists and controls.
+- Provider-originated data that Langflow only relays must stay in `provider_data` without exception.
+- Examples: provider tool names, execution metadata/status/timestamps, connection types, environments.

src/backend/base/langflow/api/v1/mappers/deployments/watsonx_orchestrate/mapper.py

@@ -1093,8 +1093,10 @@ def shape_flow_version_list_result(
                 version_number=row.flow_version.version_number,
                 attached_at=row.attachment.created_at,
                 provider_snapshot_id=row.snapshot_id,
-                tool_name=snapshot_name_by_id.get(row.snapshot_id),
-                provider_data=self.shape_deployment_flow_version_item_data(snapshot_data_by_id.get(row.snapshot_id)),
+                provider_data=self.shape_deployment_flow_version_item_data(
+                    snapshot_data=snapshot_data_by_id.get(row.snapshot_id),
+                    tool_name=snapshot_name_by_id.get(row.snapshot_id),
+                ),
             )
             for row in normalized_rows
         ]
@@ -1159,12 +1161,13 @@ def _resolve_snapshot_name_by_id(
 
         Edge cases:
         - Provider unreachable / snapshot_result is None: returns ``{}``.
-          The ``tool_name`` field in the response will be ``None`` and the
-          frontend falls back to the Langflow flow name for display.
+          ``provider_data.tool_name`` will be absent/``None`` and the frontend
+          falls back to the Langflow flow name for display.
         - Tool renamed in wxO console: the new name is returned here since
           ``snapshot_result`` is fetched fresh on each request.
         - Tool deleted in wxO: missing from ``snapshot_result.snapshots``,
-          so no entry in the returned dict. ``tool_name`` will be ``None``.
+          so no entry in the returned dict. ``provider_data.tool_name`` will be
+          absent/``None``.
         """
         if not snapshot_result or not snapshot_result.snapshots:
             return {}
@@ -1178,17 +1181,21 @@ def _resolve_snapshot_name_by_id(
 
     def shape_deployment_flow_version_item_data(
         self,
+        *,
         snapshot_data: dict[str, Any] | None,
+        tool_name: str | None = None,
     ) -> dict[str, Any] | None:
-        if not snapshot_data:
-            return None
-        raw_connections = snapshot_data.get("connections")
-        if raw_connections is None or not isinstance(raw_connections, dict):
+        raw_connections = snapshot_data.get("connections") if snapshot_data else None
+        app_ids = list(raw_connections.keys()) if isinstance(raw_connections, dict) else []
+        if not app_ids and not tool_name:
             return None
         try:
             return self._validate_slot(
                 self.api_payloads.deployment_item_data,
-                {"app_ids": list(raw_connections.keys())},
+                {
+                    "app_ids": app_ids,
+                    "tool_name": tool_name,
+                },
             )
         except AdapterPayloadValidationError as exc:
             detail = exc.format_first_error()

src/backend/base/langflow/api/v1/mappers/deployments/watsonx_orchestrate/payloads.py

@@ -527,6 +527,7 @@ class WatsonxApiDeploymentFlowVersionItemData(BaseModel):
     model_config = {"extra": "forbid"}
 
     app_ids: list[str] = Field(default_factory=list)
+    tool_name: str | None = None
 
     @field_validator("app_ids", mode="before")
     @classmethod
@@ -535,6 +536,12 @@ def normalize_app_ids(cls, value: Any) -> list[str]:
             return []
         return [str(app_id).strip() for app_id in value if str(app_id).strip()]
 
+    @field_validator("tool_name", mode="before")
+    @classmethod
+    def normalize_optional_tool_name(cls, value: Any) -> str | None:
+        normalized = str(value or "").strip()
+        return normalized or None
+
 
 class _WatsonxApiAgentExecutionResultBase(BaseModel):
     """Shared fields for API-facing agent execution result payloads.

src/backend/base/langflow/api/v1/schemas/deployments.py

@@ -331,15 +331,15 @@ class DeploymentFlowVersionListItem(BaseModel):
     distinguishes the following cases:
 
     * **Tool renamed in provider** — Same ``provider_snapshot_id``, different
-      ``tool_name``.  Langflow picks up the new name on the next fetch.
+      ``provider_data.tool_name``.  Langflow picks up the new name on the next fetch.
     * **Tool deleted in provider** — ``provider_snapshot_id`` no longer
-      resolves.  ``tool_name`` and ``provider_data`` will be ``None``.
+      resolves.  ``provider_data.tool_name`` may be missing/``None``.
     * **Tool deleted + new tool created with same name** — The new tool has
       a different ID.  Langflow's attachment still points to the old
       (missing) ID.  The new tool is invisible to Langflow until explicitly
       attached via an update operation.
 
-    Frontends should use ``tool_name`` for display and
+    Frontends should use ``provider_data.tool_name`` for display and
     ``provider_snapshot_id`` for identity / operations.
     """
 
@@ -358,15 +358,6 @@ class DeploymentFlowVersionListItem(BaseModel):
         default=None,
         description="Provider-owned snapshot/tool identifier linked by the attachment.",
     )
-    tool_name: str | None = Field(
-        default=None,
-        description=(
-            "Provider tool name for this snapshot. May differ from ``flow_name`` "
-            "if the user set a custom name at deploy time or renamed the tool in "
-            "the provider console. ``None`` when the provider is unreachable or "
-            "the tool has been deleted — frontends should fall back to ``flow_name``."
-        ),
-    )
     provider_data: dict[str, Any] | None = Field(
         default=None,
         description="Provider-owned opaque payload for this attached flow version.",

src/backend/tests/unit/api/v1/test_deployment_mapper_watsonx.py

@@ -229,18 +229,25 @@ def test_watsonx_mapper_formats_conflict_detail(raw_message: str, expected: str)
 def test_watsonx_mapper_shapes_flow_version_item_data_from_connections() -> None:
     mapper = WatsonxOrchestrateDeploymentMapper()
 
-    shaped = mapper.shape_deployment_flow_version_item_data({"connections": {"cfg-1": "conn-1", "cfg-2": "conn-2"}})
+    shaped = mapper.shape_deployment_flow_version_item_data(
+        snapshot_data={"connections": {"cfg-1": "conn-1", "cfg-2": "conn-2"}},
+        tool_name="Tool 1",
+    )
 
-    assert shaped == {"app_ids": ["cfg-1", "cfg-2"]}
+    assert shaped == {"app_ids": ["cfg-1", "cfg-2"], "tool_name": "Tool 1"}
 
 
 def test_watsonx_mapper_flow_version_item_data_handles_missing_invalid_and_empty_connections() -> None:
     mapper = WatsonxOrchestrateDeploymentMapper()
 
-    assert mapper.shape_deployment_flow_version_item_data(None) is None
-    assert mapper.shape_deployment_flow_version_item_data({}) is None
-    assert mapper.shape_deployment_flow_version_item_data({"connections": []}) is None
-    assert mapper.shape_deployment_flow_version_item_data({"connections": {}}) == {"app_ids": []}
+    assert mapper.shape_deployment_flow_version_item_data(snapshot_data=None) is None
+    assert mapper.shape_deployment_flow_version_item_data(snapshot_data={}) is None
+    assert mapper.shape_deployment_flow_version_item_data(snapshot_data={"connections": []}) is None
+    assert mapper.shape_deployment_flow_version_item_data(snapshot_data={"connections": {}}) is None
+    assert mapper.shape_deployment_flow_version_item_data(snapshot_data=None, tool_name="Tool 1") == {
+        "app_ids": [],
+        "tool_name": "Tool 1",
+    }
 
 
 def test_watsonx_mapper_shapes_flow_version_list_result_with_enrichment() -> None:
@@ -282,7 +289,7 @@ def test_watsonx_mapper_shapes_flow_version_list_result_with_enrichment() -> Non
     assert shaped.flow_versions[0].version_number == 3
     assert shaped.flow_versions[0].attached_at == attached_at
     assert shaped.flow_versions[0].provider_snapshot_id == "tool-1"
-    assert shaped.flow_versions[0].provider_data == {"app_ids": ["cfg-1"]}
+    assert shaped.flow_versions[0].provider_data == {"app_ids": ["cfg-1"], "tool_name": "Tool 1"}
 
 
 def test_watsonx_mapper_flow_version_list_result_returns_empty_app_ids_when_snapshot_has_no_connections() -> None:
@@ -315,7 +322,7 @@ def test_watsonx_mapper_flow_version_list_result_returns_empty_app_ids_when_snap
     assert shaped.total == 1
     assert len(shaped.flow_versions) == 1
     assert shaped.flow_versions[0].provider_snapshot_id == "tool-1"
-    assert shaped.flow_versions[0].provider_data == {"app_ids": []}
+    assert shaped.flow_versions[0].provider_data == {"app_ids": [], "tool_name": "Tool 1"}
 
 
 def test_watsonx_mapper_flow_version_list_result_degrades_when_snapshot_result_missing() -> None:

src/backend/tests/unit/services/deployment/test_watsonx_orchestrate.py

@@ -7112,33 +7112,32 @@ def test_rename_tool_provider_payload_parses():
 
 
 # ---------------------------------------------------------------------------
-# DeploymentFlowVersionListItem includes tool_name
+# DeploymentFlowVersionListItem carries provider tool_name under provider_data
 # ---------------------------------------------------------------------------
 
 
-def test_flow_version_list_item_includes_tool_name():
-    """DeploymentFlowVersionListItem accepts and serializes tool_name."""
+def test_flow_version_list_item_includes_tool_name_in_provider_data():
+    """DeploymentFlowVersionListItem serializes provider tool_name under provider_data."""
     from langflow.api.v1.schemas.deployments import DeploymentFlowVersionListItem
 
     item = DeploymentFlowVersionListItem(
         id="00000000-0000-0000-0000-000000000001",
         flow_id="00000000-0000-0000-0000-000000000002",
         flow_name="My Flow",
         version_number=1,
-        tool_name="my_custom_tool",
+        provider_data={"tool_name": "my_custom_tool"},
     )
-    assert item.tool_name == "my_custom_tool"
     data = item.model_dump()
-    assert data["tool_name"] == "my_custom_tool"
+    assert data["provider_data"]["tool_name"] == "my_custom_tool"
 
 
-def test_flow_version_list_item_tool_name_defaults_to_none():
-    """DeploymentFlowVersionListItem defaults tool_name to None."""
+def test_flow_version_list_item_provider_data_defaults_to_none():
+    """DeploymentFlowVersionListItem defaults provider_data to None."""
     from langflow.api.v1.schemas.deployments import DeploymentFlowVersionListItem
 
     item = DeploymentFlowVersionListItem(
         id="00000000-0000-0000-0000-000000000001",
         flow_id="00000000-0000-0000-0000-000000000002",
         version_number=1,
     )
-    assert item.tool_name is None
+    assert item.provider_data is None

src/frontend/src/controllers/API/queries/deployments/use-get-deployment-attachments.ts

@@ -8,13 +8,13 @@ import { UseRequestProcessor } from "../../services/request-processor";
  *
  * Identity contract: Langflow tracks provider tools by their immutable
  * `provider_snapshot_id` (wxO tool_id), never by name.
- * - Tool renamed in provider → same snapshot ID, new `tool_name`.
- * - Tool deleted in provider → snapshot ID unresolvable, `tool_name` is null.
+ * - Tool renamed in provider → same snapshot ID, new `provider_data.tool_name`.
+ * - Tool deleted in provider → snapshot ID unresolvable, `provider_data.tool_name` is null/missing.
  * - Tool deleted + new tool created with same name → different ID, our
  *   attachment still points to the old (missing) ID. The new tool is
  *   invisible to Langflow until explicitly attached.
  *
- * Use `tool_name` for display, fall back to `flow_name` when null.
+ * Use `provider_data.tool_name` for display, fall back to `flow_name` when null.
  * Use `provider_snapshot_id` for operations.
  */
 export interface DeploymentFlowVersionItem {
@@ -24,10 +24,10 @@ export interface DeploymentFlowVersionItem {
   version_number: number;
   attached_at: string | null;
   provider_snapshot_id: string | null;
-  /** Provider tool name — null when the tool was deleted or provider is unreachable. */
-  tool_name: string | null;
   provider_data: {
     app_ids?: string[];
+    /** Provider tool name — null/missing when the tool was deleted or provider is unreachable. */
+    tool_name?: string | null;
   } | null;
 }
 

src/frontend/src/pages/MainPage/pages/deploymentsPage/components/deployment-stepper-modal.tsx

@@ -8,8 +8,8 @@ import {
   DialogTitle,
 } from "@/components/ui/dialog";
 import { usePostProviderAccount } from "@/controllers/API/queries/deployment-provider-accounts/use-post-provider-account";
-import { useGetDeploymentAttachments } from "@/controllers/API/queries/deployments/use-get-deployment-attachments";
 import { useGetDeployment } from "@/controllers/API/queries/deployments/use-get-deployment";
+import { useGetDeploymentAttachments } from "@/controllers/API/queries/deployments/use-get-deployment-attachments";
 import { usePatchDeployment } from "@/controllers/API/queries/deployments/use-patch-deployment";
 import { usePostDeployment } from "@/controllers/API/queries/deployments/use-post-deployment";
 import {
@@ -71,7 +71,7 @@ export default function DeploymentStepperModal({
   //
   // - If a user renames a tool in the wxO console, the new name appears
   //   here on the next edit. Langflow doesn't cache tool names locally.
-  // - If a tool is deleted in wxO, its tool_name will be null and the
+  // - If a tool is deleted in wxO, provider_data.tool_name will be null and the
   //   review page falls back to the Langflow flow name.
   // - If a connection is deleted in wxO but the tool still references it,
   //   the app_id will appear in connectionsByFlow. The backend will fail
@@ -93,8 +93,9 @@ export default function DeploymentStepperModal({
         versionTag: `v${fv.version_number}`,
       });
       // Pre-populate tool names from the provider (may differ from flow name).
-      if (fv.tool_name) {
-        toolNames.set(fv.flow_id, fv.tool_name);
+      const providerToolName = fv.provider_data?.tool_name;
+      if (providerToolName) {
+        toolNames.set(fv.flow_id, providerToolName);
       }
       // Pre-populate attached connections from existing tool bindings.
       const appIds = fv.provider_data?.app_ids;