@qingflow-tech/qingflow-app-user-mcp 1.0.8 → 1.0.10

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -70,6 +70,19 @@ def _normalize_builder_view_key(value: str) -> str:
 
 
 PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook", "end"]
+BUILDER_APPLY_SCHEMA_VERSION = "builder.apply.v1"
+BUILDER_APPLY_TOOL_NAMES = {
+    "package_apply",
+    "app_schema_apply",
+    "app_layout_apply",
+    "app_flow_apply",
+    "app_views_apply",
+    "app_custom_buttons_apply",
+    "app_associated_resources_apply",
+    "app_charts_apply",
+    "portal_apply",
+    "app_publish_verify",
+}
 
 
 class AiBuilderTools(ToolBase):
@@ -340,7 +353,32 @@ class AiBuilderTools(ToolBase):
             add_fields: list[JSONObject] | None = None,
             update_fields: list[JSONObject] | None = None,
             remove_fields: list[JSONObject] | None = None,
+            apps: list[JSONObject] | None = None,
         ) -> JSONObject:
+            if apps:
+                if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+                    return _config_failure(
+                        tool_name="app_schema_apply",
+                        message="app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
+                        fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                    )
+                if package_id is None:
+                    return _config_failure(
+                        tool_name="app_schema_apply",
+                        message="app_schema_apply multi-app mode requires package_id.",
+                        fix_hint="Pass package_id and apps[].app_name for new apps, or apps[].app_key for existing apps.",
+                    )
+                return self.app_schema_apply(
+                    profile=profile,
+                    package_id=package_id,
+                    visibility=visibility,
+                    create_if_missing=create_if_missing,
+                    publish=publish,
+                    apps=apps,
+                    add_fields=[],
+                    update_fields=[],
+                    remove_fields=[],
+                )
             has_app_key = bool((app_key or "").strip())
             has_app_name = bool((app_name or "").strip())
             has_app_title = bool((app_title or "").strip())
@@ -372,6 +410,7 @@ class AiBuilderTools(ToolBase):
                 add_fields=add_fields or [],
                 update_fields=update_fields or [],
                 remove_fields=remove_fields or [],
+                apps=[],
             )
 
         @mcp.tool()
@@ -550,6 +589,7 @@ class AiBuilderTools(ToolBase):
             "verification": {},
             "verified": False,
         }
+        contract = _builder_contract_with_apply_output(lookup_name, contract)
         return {
             "status": "success",
             "error_code": None,
@@ -647,7 +687,10 @@ class AiBuilderTools(ToolBase):
             try:
                 visibility_patch = VisibilityPatch.model_validate(visibility)
             except ValidationError as exc:
-                return _visibility_validation_failure(str(exc), tool_name="package_apply", exc=exc)
+                return _attach_builder_apply_envelope(
+                    "package_apply",
+                    _visibility_validation_failure(str(exc), tool_name="package_apply", exc=exc),
+                )
         normalized_args = {
             "package_id": package_id,
             **({"package_name": package_name} if str(package_name or "").strip() else {}),
@@ -658,7 +701,7 @@ class AiBuilderTools(ToolBase):
             **({"items": deepcopy(items)} if items is not None else {}),
             "allow_detach": bool(allow_detach),
         }
-        return _publicize_package_fields(_safe_tool_call(
+        result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.package_apply(
                 profile=profile,
                 package_id=package_id,
@@ -674,6 +717,7 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "package_apply", "arguments": {"profile": profile, **normalized_args}},
         ))
+        return _attach_builder_apply_envelope("package_apply", result)
 
     @tool_cn_name("分组更新")
     def package_update(
@@ -914,7 +958,7 @@ class AiBuilderTools(ToolBase):
         try:
             request = CustomButtonsApplyRequest.model_validate(raw_request)
         except ValidationError as exc:
-            return _validation_failure(
+            return _attach_builder_apply_envelope("app_custom_buttons_apply", _validation_failure(
                 str(exc),
                 tool_name="app_custom_buttons_apply",
                 exc=exc,
@@ -936,14 +980,14 @@ class AiBuilderTools(ToolBase):
                         "view_configs": [],
                     },
                 },
-            )
+            ))
         normalized_args = request.model_dump(mode="json")
-        return _safe_tool_call(
+        return _attach_builder_apply_envelope("app_custom_buttons_apply", _safe_tool_call(
             lambda: self._facade.app_custom_buttons_apply(profile=profile, request=request),
             error_code="CUSTOM_BUTTONS_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_custom_buttons_apply", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
     @tool_cn_name("应用关联资源声明式应用")
     def app_associated_resources_apply(
@@ -969,7 +1013,7 @@ class AiBuilderTools(ToolBase):
         try:
             request = AssociatedResourcesApplyRequest.model_validate(raw_request)
         except ValidationError as exc:
-            return _validation_failure(
+            return _attach_builder_apply_envelope("app_associated_resources_apply", _validation_failure(
                 str(exc),
                 tool_name="app_associated_resources_apply",
                 exc=exc,
@@ -996,14 +1040,14 @@ class AiBuilderTools(ToolBase):
                         ],
                     },
                 },
-            )
+            ))
         normalized_args = request.model_dump(mode="json", exclude_none=True)
-        return _safe_tool_call(
+        return _attach_builder_apply_envelope("app_associated_resources_apply", _safe_tool_call(
             lambda: self._facade.app_associated_resources_apply(profile=profile, request=request),
             error_code="ASSOCIATED_RESOURCES_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_associated_resources_apply", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
     @tool_cn_name("应用按钮列表")
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
@@ -1534,8 +1578,19 @@ class AiBuilderTools(ToolBase):
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
+        apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        if apps:
+            result = self._app_schema_apply_multi(
+                profile=profile,
+                package_id=package_id,
+                visibility=visibility,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                apps=apps,
+            )
+            return _attach_builder_apply_envelope("app_schema_apply", result)
         result = self._app_schema_apply_once(
             profile=profile,
             app_key=app_key,
@@ -1551,7 +1606,7 @@ class AiBuilderTools(ToolBase):
             update_fields=update_fields,
             remove_fields=remove_fields,
         )
-        return self._retry_after_self_lock_release(
+        result = self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._app_schema_apply_once(
@@ -1570,6 +1625,229 @@ class AiBuilderTools(ToolBase):
                 remove_fields=remove_fields,
             ),
         )
+        return _attach_builder_apply_envelope("app_schema_apply", result)
+
+    def _app_schema_apply_multi(
+        self,
+        *,
+        profile: str,
+        package_id: int | None,
+        visibility: JSONObject | None,
+        create_if_missing: bool,
+        publish: bool,
+        apps: list[JSONObject],
+    ) -> JSONObject:
+        normalized_args: JSONObject = {
+            "package_id": package_id,
+            "create_if_missing": create_if_missing,
+            "publish": publish,
+            "apps": deepcopy(apps),
+        }
+        if visibility is not None:
+            normalized_args["visibility"] = deepcopy(visibility)
+        if package_id is None:
+            return _config_failure(
+                tool_name="app_schema_apply",
+                message="app_schema_apply multi-app mode requires package_id.",
+                fix_hint="Pass package_id and apps[].app_name for new apps, or apps[].app_key for existing apps.",
+            )
+        if not apps:
+            return _config_failure(
+                tool_name="app_schema_apply",
+                message="app_schema_apply multi-app mode requires non-empty apps.",
+                fix_hint="Pass apps as a non-empty list of app schema items.",
+            )
+
+        client_key_to_app_key: dict[str, str] = {}
+        created_app_keys: list[str] = []
+        results: list[JSONObject] = []
+        any_write_executed = False
+        client_keys: set[str] = set()
+
+        for index, raw_item in enumerate(apps):
+            if not isinstance(raw_item, dict):
+                results.append(_multi_app_item_failure(index, raw_item, "INVALID_APP_ITEM", "apps[] items must be objects"))
+                continue
+            item = deepcopy(raw_item)
+            client_key = str(item.get("client_key") or item.get("clientKey") or "").strip()
+            app_name = str(item.get("app_name") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip()
+            app_key = str(item.get("app_key") or item.get("appKey") or "").strip()
+            if client_key:
+                if client_key in client_keys:
+                    results.append(_multi_app_item_failure(index, item, "DUPLICATE_CLIENT_KEY", f"duplicate client_key '{client_key}'"))
+                    continue
+                client_keys.add(client_key)
+            if not app_key and not app_name:
+                results.append(_multi_app_item_failure(index, item, "APP_SELECTOR_REQUIRED", "apps[] requires app_key or app_name"))
+                continue
+
+            initial_add_fields, deferred_add_fields = _split_multi_app_initial_add_fields(item, is_new_app=not bool(app_key))
+            item["_deferred_add_fields"] = deferred_add_fields
+            shell = self._app_schema_apply_once(
+                profile=profile,
+                app_key=app_key,
+                package_id=package_id if not app_key else None,
+                app_name=app_name,
+                app_title="",
+                icon=str(item.get("icon") or ""),
+                color=str(item.get("color") or ""),
+                visibility=item.get("visibility", visibility),
+                create_if_missing=create_if_missing and not app_key,
+                publish=publish and not deferred_add_fields,
+                add_fields=initial_add_fields,
+                update_fields=[],
+                remove_fields=[],
+            )
+            public_shell = _publicize_package_fields(shell)
+            resolved_key = str(public_shell.get("app_key") or "").strip()
+            if public_shell.get("status") not in {"success", "partial_success"} or not resolved_key:
+                results.append({
+                    "index": index,
+                    "row_number": index + 1,
+                    "client_key": client_key or None,
+                    "app_name": app_name or None,
+                    "app_key": resolved_key or app_key or None,
+                    "status": "failed",
+                    "stage": "resolve_or_create_shell",
+                    "error_code": public_shell.get("error_code") or "APP_SHELL_APPLY_FAILED",
+                    "message": public_shell.get("message") or "app shell resolve/create failed",
+                    "safe_to_retry": not any_write_executed,
+                })
+                continue
+            if bool(public_shell.get("created")):
+                created_app_keys.append(resolved_key)
+            if _schema_apply_result_has_write(public_shell):
+                any_write_executed = True
+            if client_key:
+                client_key_to_app_key[client_key] = resolved_key
+            results.append({
+                "index": index,
+                "row_number": index + 1,
+                "client_key": client_key or None,
+                "app_name": str(public_shell.get("app_name_after") or public_shell.get("app_name") or app_name or "").strip() or None,
+                "app_key": resolved_key,
+                "status": "shell_ready",
+                "created": bool(public_shell.get("created")),
+                "shell_result": public_shell,
+                "shell_field_diff": public_shell.get("field_diff") or {},
+                "shell_field_diff_details": public_shell.get("field_diff_details") or {},
+                "deferred_add_fields": deferred_add_fields,
+            })
+
+        final_items: list[JSONObject] = []
+        for index, raw_item in enumerate(apps):
+            existing = next((item for item in results if item.get("index") == index), None)
+            if not existing or existing.get("status") != "shell_ready":
+                if existing:
+                    final_items.append(existing)
+                continue
+            item = deepcopy(raw_item)
+            app_key = str(existing.get("app_key") or "").strip()
+            try:
+                compiled_item = _compile_multi_app_schema_item_refs(item, client_key_to_app_key)
+            except ValueError as error:
+                final_items.append({
+                    **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
+                    "status": "failed",
+                    "stage": "compile_relation_refs",
+                    "error_code": "TARGET_APP_REF_NOT_FOUND",
+                    "message": str(error),
+                    "safe_to_retry": False,
+                })
+                any_write_executed = True
+                continue
+
+            deferred_add_fields = (
+                _compiled_multi_app_deferred_add_fields(compiled_item, existing)
+                if bool(existing.get("created"))
+                else list(compiled_item.get("add_fields") or [])
+            )
+            update_fields = list(compiled_item.get("update_fields") or [])
+            remove_fields = list(compiled_item.get("remove_fields") or [])
+            if bool(existing.get("created")) and not deferred_add_fields and not update_fields and not remove_fields:
+                shell_result = existing.get("shell_result") if isinstance(existing.get("shell_result"), dict) else {}
+                item_status = shell_result.get("status") if shell_result.get("status") in {"success", "partial_success"} else "failed"
+                shell_field_diff = existing.get("shell_field_diff") if isinstance(existing.get("shell_field_diff"), dict) else {}
+                shell_field_diff_details = existing.get("shell_field_diff_details") if isinstance(existing.get("shell_field_diff_details"), dict) else {}
+                final_items.append({
+                    **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
+                    "status": item_status,
+                    "stage": "schema_apply",
+                    "field_diff": shell_field_diff,
+                    "field_diff_details": shell_field_diff_details,
+                    "shell_field_diff": shell_field_diff,
+                    "shell_field_diff_details": shell_field_diff_details,
+                    "published": bool(shell_result.get("published")),
+                    "verified": bool(shell_result.get("verified")),
+                    "error_code": shell_result.get("error_code"),
+                    "message": shell_result.get("message"),
+                    "safe_to_retry": False,
+                })
+                continue
+
+            field_result = self._app_schema_apply_once(
+                profile=profile,
+                app_key=app_key,
+                package_id=None,
+                app_name=str(compiled_item.get("app_name") or compiled_item.get("appTitle") or compiled_item.get("app_title") or ""),
+                app_title="",
+                icon=str(compiled_item.get("icon") or ""),
+                color=str(compiled_item.get("color") or ""),
+                visibility=compiled_item.get("visibility"),
+                create_if_missing=False,
+                publish=publish,
+                add_fields=deferred_add_fields,
+                update_fields=update_fields,
+                remove_fields=remove_fields,
+            )
+            public_result = _publicize_package_fields(field_result)
+            if _schema_apply_result_has_write(public_result):
+                any_write_executed = True
+            item_status = public_result.get("status") if public_result.get("status") in {"success", "partial_success"} else "failed"
+            shell_field_diff = existing.get("shell_field_diff") if isinstance(existing.get("shell_field_diff"), dict) else {}
+            shell_field_diff_details = existing.get("shell_field_diff_details") if isinstance(existing.get("shell_field_diff_details"), dict) else {}
+            field_diff = _merge_schema_field_diffs(shell_field_diff, public_result.get("field_diff") or {})
+            field_diff_details = _merge_schema_field_diffs(shell_field_diff_details, public_result.get("field_diff_details") or {})
+            final_items.append({
+                **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
+                "status": item_status,
+                "stage": "schema_apply",
+                "field_diff": field_diff,
+                "field_diff_details": field_diff_details,
+                "shell_field_diff": shell_field_diff,
+                "shell_field_diff_details": shell_field_diff_details,
+                "published": bool(public_result.get("published")),
+                "verified": bool(public_result.get("verified")),
+                "error_code": public_result.get("error_code"),
+                "message": public_result.get("message"),
+                "safe_to_retry": False,
+            })
+
+        succeeded = sum(1 for item in final_items if item.get("status") in {"success", "partial_success"})
+        failed = len(final_items) - succeeded
+        overall_status = "success" if failed == 0 else ("partial_success" if succeeded > 0 or any_write_executed else "failed")
+        return {
+            "status": overall_status,
+            "mode": "multi_app",
+            "total": len(apps),
+            "succeeded": succeeded,
+            "failed": failed,
+            "created_app_keys": created_app_keys,
+            "write_executed": any_write_executed,
+            "safe_to_retry": not any_write_executed,
+            "package_id": package_id,
+            "publish_requested": publish,
+            "apps": final_items,
+            "normalized_args": normalized_args,
+            "verification": {
+                "all_apps_succeeded": failed == 0,
+                "created_app_count": len(created_app_keys),
+            },
+            "request_id": None,
+            "error_code": None if overall_status != "failed" else "MULTI_APP_SCHEMA_APPLY_FAILED",
+            "recoverable": overall_status != "success",
+            "message": "multi-app schema apply completed" if overall_status != "failed" else "multi-app schema apply failed",
+        }
 
     def _app_schema_apply_once(
         self,
@@ -1685,7 +1963,7 @@ class AiBuilderTools(ToolBase):
             publish=publish,
             sections=sections,
         )
-        return self._retry_after_self_lock_release(
+        result = self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._app_layout_apply_once(
@@ -1696,6 +1974,7 @@ class AiBuilderTools(ToolBase):
                 sections=sections,
             ),
         )
+        return _attach_builder_apply_envelope("app_layout_apply", result)
 
     def _app_layout_apply_once(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
         """执行内部辅助逻辑。"""
@@ -1775,7 +2054,7 @@ class AiBuilderTools(ToolBase):
             nodes=nodes,
             transitions=transitions,
         )
-        return self._retry_after_self_lock_release(
+        result = self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._app_flow_apply_once(
@@ -1787,6 +2066,7 @@ class AiBuilderTools(ToolBase):
                 transitions=transitions,
             ),
         )
+        return _attach_builder_apply_envelope("app_flow_apply", result)
 
     def _app_flow_apply_once(
         self,
@@ -1886,7 +2166,7 @@ class AiBuilderTools(ToolBase):
             patch_views=patch_views or [],
             remove_views=remove_views,
         )
-        return self._retry_after_self_lock_release(
+        result = self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._app_views_apply_once(
@@ -1898,6 +2178,7 @@ class AiBuilderTools(ToolBase):
                 patch_views=patch_views or [],
             ),
         )
+        return _attach_builder_apply_envelope("app_views_apply", result)
 
     def _app_views_apply_once(
         self,
@@ -2053,7 +2334,7 @@ class AiBuilderTools(ToolBase):
                 }
             )
         except ValidationError as exc:
-            return _visibility_validation_failure(
+            return _attach_builder_apply_envelope("app_charts_apply", _visibility_validation_failure(
                 str(exc),
                 tool_name="app_charts_apply",
                 exc=exc,
@@ -2067,14 +2348,14 @@ class AiBuilderTools(ToolBase):
                         "reorder_chart_ids": [],
                     },
                 },
-            )
+            ))
         normalized_args = request.model_dump(mode="json")
-        return _safe_tool_call(
+        return _attach_builder_apply_envelope("app_charts_apply", _safe_tool_call(
             lambda: self._facade.chart_apply(profile=profile, request=request),
             error_code="CHART_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
     @tool_cn_name("门户配置应用")
     def portal_apply(
@@ -2113,7 +2394,7 @@ class AiBuilderTools(ToolBase):
                 }
             )
         except ValidationError as exc:
-            return _visibility_validation_failure(
+            return _attach_builder_apply_envelope("portal_apply", _visibility_validation_failure(
                 str(exc),
                 tool_name="portal_apply",
                 exc=exc,
@@ -2133,15 +2414,16 @@ class AiBuilderTools(ToolBase):
                         ],
                     },
                 },
-            )
+            ))
         normalized_args = request.model_dump(mode="json")
         normalized_args["package_id"] = normalized_args.pop("package_tag_id", package_id)
-        return _publicize_package_fields(_safe_tool_call(
+        result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_apply(profile=profile, request=request),
             error_code="PORTAL_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
         ))
+        return _attach_builder_apply_envelope("portal_apply", result)
 
     @tool_cn_name("应用发布校验")
     def app_publish_verify(
@@ -2159,7 +2441,7 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, **normalized_args}},
         ))
-        return _publicize_package_fields(self._retry_after_self_lock_release(
+        result = _publicize_package_fields(self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._facade.app_publish_verify(
@@ -2168,6 +2450,7 @@ class AiBuilderTools(ToolBase):
                 expected_package_tag_id=expected_package_id,
             ),
         ))
+        return _attach_builder_apply_envelope("app_publish_verify", result)
 
     def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
         """执行内部辅助逻辑。"""
@@ -2286,6 +2569,128 @@ class AiBuilderTools(ToolBase):
         return rewritten
 
 
+def _multi_app_item_failure(index: int, item: object, error_code: str, message: str) -> JSONObject:
+    app_name = None
+    client_key = None
+    app_key = None
+    if isinstance(item, dict):
+        app_name = str(item.get("app_name") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip() or None
+        client_key = str(item.get("client_key") or item.get("clientKey") or "").strip() or None
+        app_key = str(item.get("app_key") or item.get("appKey") or "").strip() or None
+    return {
+        "index": index,
+        "row_number": index + 1,
+        "client_key": client_key,
+        "app_name": app_name,
+        "app_key": app_key,
+        "status": "failed",
+        "stage": "validate_item",
+        "error_code": error_code,
+        "message": message,
+        "safe_to_retry": True,
+    }
+
+
+def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key: dict[str, str]) -> JSONObject:
+    compiled = deepcopy(item)
+
+    def visit(value):
+        if isinstance(value, list):
+            return [visit(entry) for entry in value]
+        if not isinstance(value, dict):
+            return value
+        payload = {key: visit(entry) for key, entry in value.items()}
+        ref = (
+            payload.pop("target_app_ref", None)
+            or payload.pop("targetAppRef", None)
+            or payload.pop("target_app_client_key", None)
+            or payload.pop("targetAppClientKey", None)
+        )
+        if ref is not None:
+            ref_key = str(ref or "").strip()
+            target_app_key = client_key_to_app_key.get(ref_key)
+            if not target_app_key:
+                raise ValueError(f"target_app_ref '{ref_key}' did not match any apps[].client_key")
+            payload["target_app_key"] = target_app_key
+        return payload
+
+    return visit(compiled)
+
+
+def _split_multi_app_initial_add_fields(item: JSONObject, *, is_new_app: bool) -> tuple[list[JSONObject], list[JSONObject]]:
+    add_fields = _multi_app_list_value(item, "add_fields", "addFields")
+    if not is_new_app:
+        return [], add_fields
+    initial: list[JSONObject] = []
+    deferred: list[JSONObject] = []
+    for field in add_fields:
+        if _contains_multi_app_target_ref(field):
+            deferred.append(field)
+        else:
+            initial.append(field)
+    return initial, deferred
+
+
+def _compiled_multi_app_deferred_add_fields(compiled_item: JSONObject, existing_result: JSONObject) -> list[JSONObject]:
+    deferred = existing_result.get("deferred_add_fields")
+    if not isinstance(deferred, list):
+        return list(compiled_item.get("add_fields") or [])
+    deferred_names = {str(item.get("name") or item.get("title") or item.get("label") or "").strip() for item in deferred if isinstance(item, dict)}
+    if not deferred_names:
+        return []
+    return [
+        deepcopy(field)
+        for field in list(compiled_item.get("add_fields") or [])
+        if isinstance(field, dict)
+        and str(field.get("name") or field.get("title") or field.get("label") or "").strip() in deferred_names
+    ]
+
+
+def _multi_app_list_value(item: JSONObject, *keys: str) -> list[JSONObject]:
+    for key in keys:
+        value = item.get(key)
+        if isinstance(value, list):
+            return [deepcopy(entry) for entry in value if isinstance(entry, dict)]
+    return []
+
+
+def _contains_multi_app_target_ref(value: object) -> bool:
+    if isinstance(value, list):
+        return any(_contains_multi_app_target_ref(item) for item in value)
+    if not isinstance(value, dict):
+        return False
+    for key, entry in value.items():
+        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey"}:
+            return True
+        if _contains_multi_app_target_ref(entry):
+            return True
+    return False
+
+
+def _merge_schema_field_diffs(*diffs: object) -> JSONObject:
+    merged: JSONObject = {"added": [], "updated": [], "removed": []}
+    for diff in diffs:
+        if not isinstance(diff, dict):
+            continue
+        for key in ("added", "updated", "removed"):
+            values = diff.get(key)
+            if not isinstance(values, list):
+                continue
+            for value in values:
+                if value not in merged[key]:
+                    merged[key].append(value)
+    return merged
+
+
+def _schema_apply_result_has_write(result: JSONObject) -> bool:
+    if bool(result.get("created")) or bool(result.get("published")) or bool(result.get("app_base_updated")):
+        return True
+    field_diff = result.get("field_diff")
+    if isinstance(field_diff, dict):
+        return any(bool(field_diff.get(key)) for key in ("added", "updated", "removed"))
+    return False
+
+
 def _validation_failure(
     detail: str,
     *,
@@ -2448,6 +2853,661 @@ def _publicize_package_fields(value):
     return public
 
 
+def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) -> JSONObject:
+    public = deepcopy(contract)
+    if tool_name not in BUILDER_APPLY_TOOL_NAMES:
+        return public
+    notes = public.setdefault("execution_notes", [])
+    if isinstance(notes, list):
+        note = "apply/write output includes schema_version, operation, summary, and resources[]; UI and agents should read resources[].id/key/name first and use legacy fields only for compatibility/debugging"
+        if note not in notes:
+            notes.append(note)
+    public["output_contract"] = {
+        "schema_version": BUILDER_APPLY_SCHEMA_VERSION,
+        "preferred_ui_fields": ["operation", "summary", "resources"],
+        "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "error_code", "message"],
+        "legacy_fields_preserved": True,
+    }
+    return public
+
+
+def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONObject:
+    if not isinstance(payload, dict):
+        return payload
+    resources = _builder_apply_resources(tool_name, payload)
+    payload["schema_version"] = BUILDER_APPLY_SCHEMA_VERSION
+    payload["operation"] = tool_name
+    payload["resources"] = resources
+    payload["summary"] = _builder_apply_summary(payload, resources)
+    return payload
+
+
+def _builder_apply_summary(payload: JSONObject, resources: list[JSONObject]) -> JSONObject:
+    status = str(payload.get("status") or "")
+    failed = sum(1 for item in resources if str(item.get("status") or "") == "failed")
+    created = sum(1 for item in resources if str(item.get("operation") or "") == "created" and str(item.get("status") or "") != "failed")
+    removed = sum(1 for item in resources if str(item.get("operation") or "") == "removed" and str(item.get("status") or "") != "failed")
+    updated = sum(
+        1
+        for item in resources
+        if str(item.get("status") or "") != "failed"
+        and str(item.get("operation") or "") in {"updated", "layout_updated", "workflow_updated", "verified", "published"}
+    )
+    published_value = payload.get("published")
+    if published_value is None:
+        publish_requested = payload.get("publish_requested")
+        published_value = bool(publish_requested) and status in {"success", "partial_success"}
+    verified_value = payload.get("verified")
+    if verified_value is None:
+        verification = payload.get("verification")
+        verified_value = status == "success" and failed == 0 and _builder_verification_truthy(verification)
+    summary: JSONObject = {
+        "total": len(resources),
+        "created": created,
+        "updated": updated,
+        "removed": removed,
+        "failed": failed,
+        "published": bool(published_value),
+        "verified": bool(verified_value),
+    }
+    if "write_executed" in payload:
+        summary["write_executed"] = bool(payload.get("write_executed"))
+    if "safe_to_retry" in payload:
+        summary["safe_to_retry"] = bool(payload.get("safe_to_retry"))
+    return summary
+
+
+def _builder_verification_truthy(value: object) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, dict):
+        booleans = [item for item in value.values() if isinstance(item, bool)]
+        return all(booleans) if booleans else True
+    return True
+
+
+def _builder_apply_resources(tool_name: str, payload: JSONObject) -> list[JSONObject]:
+    resources: list[JSONObject]
+    if tool_name == "package_apply":
+        resources = _builder_package_resources(payload)
+    elif tool_name == "app_schema_apply":
+        resources = _builder_schema_resources(payload)
+    elif tool_name == "app_layout_apply":
+        resources = [_builder_app_resource(payload, operation="layout_updated")]
+    elif tool_name == "app_flow_apply":
+        resources = [_builder_app_resource(payload, operation="workflow_updated")]
+    elif tool_name == "app_views_apply":
+        resources = _builder_view_resources(payload)
+    elif tool_name == "app_charts_apply":
+        resources = _builder_chart_resources(payload)
+    elif tool_name == "portal_apply":
+        resources = _builder_portal_resources(payload)
+    elif tool_name == "app_custom_buttons_apply":
+        resources = _builder_button_resources(payload)
+    elif tool_name == "app_associated_resources_apply":
+        resources = _builder_associated_resource_resources(payload)
+    elif tool_name == "app_publish_verify":
+        resources = [_builder_app_resource(payload, operation="verified")]
+    else:
+        resources = []
+    if not resources and _builder_status(payload, "") == "failed" and _builder_apply_tool_is_app_scoped(tool_name):
+        app_key = _builder_payload_app_key(payload)
+        if app_key not in (None, ""):
+            resources = [_builder_app_resource(payload, operation="failed")]
+    return resources
+
+
+def _builder_apply_tool_is_app_scoped(tool_name: str) -> bool:
+    return tool_name in {
+        "app_schema_apply",
+        "app_layout_apply",
+        "app_flow_apply",
+        "app_views_apply",
+        "app_custom_buttons_apply",
+        "app_associated_resources_apply",
+        "app_charts_apply",
+        "app_publish_verify",
+    }
+
+
+def _builder_status(payload_or_item: JSONObject, fallback: str = "success") -> str:
+    status = str(payload_or_item.get("status") or fallback or "success")
+    return status
+
+
+def _builder_operation(value: object, fallback: str = "updated") -> str:
+    raw = str(value or fallback or "updated").strip()
+    mapping = {
+        "create": "created",
+        "created": "created",
+        "add": "created",
+        "update": "updated",
+        "updated": "updated",
+        "patch": "updated",
+        "remove": "removed",
+        "removed": "removed",
+        "delete": "removed",
+        "deleted": "removed",
+        "unchanged": "unchanged",
+        "failed": "failed",
+    }
+    return mapping.get(raw, raw)
+
+
+def _builder_parent(resource_type: str, *, key: object = None, name: object = None, id_value: object = None) -> JSONObject:
+    return {
+        "resource_type": resource_type,
+        "id": id_value,
+        "key": str(key) if key not in (None, "") else None,
+        "name": str(name) if name not in (None, "") else None,
+    }
+
+
+def _builder_app_parent(payload: JSONObject) -> JSONObject | None:
+    app_key = payload.get("app_key") or payload.get("appKey")
+    app_name = payload.get("app_name_after") or payload.get("app_name") or payload.get("appTitle") or payload.get("app_title")
+    if app_key in (None, "") and app_name in (None, ""):
+        return None
+    return _builder_parent("app", key=app_key, name=app_name)
+
+
+def _builder_resource(
+    *,
+    resource_type: str,
+    operation: str,
+    status: str,
+    id_value: object = None,
+    key: object = None,
+    name: object = None,
+    ids: JSONObject | None = None,
+    parent: JSONObject | None = None,
+    error_code: object = None,
+    message: object = None,
+) -> JSONObject:
+    return {
+        "resource_type": resource_type,
+        "operation": operation,
+        "status": status,
+        "id": id_value,
+        "key": str(key) if key not in (None, "") else None,
+        "name": str(name) if name not in (None, "") else None,
+        "ids": ids or {},
+        "parent": parent,
+        "error_code": str(error_code) if error_code not in (None, "") else None,
+        "message": str(message) if message not in (None, "") else None,
+    }
+
+
+def _builder_app_resource(payload: JSONObject, *, operation: str) -> JSONObject:
+    status = _builder_status(payload, "success")
+    if status == "failed":
+        operation = "failed"
+    app_key = _builder_payload_app_key(payload)
+    app_name = _builder_payload_app_name(payload)
+    return _builder_resource(
+        resource_type="app",
+        operation=operation,
+        status=status,
+        key=app_key,
+        name=app_name,
+        ids={"app_key": app_key} if app_key not in (None, "") else {},
+        error_code=payload.get("error_code"),
+        message=payload.get("message") if status == "failed" else None,
+    )
+
+
+def _builder_payload_app_key(payload: JSONObject) -> object:
+    return _builder_payload_identity_value(payload, ("app_key", "appKey"))
+
+
+def _builder_payload_app_name(payload: JSONObject) -> object:
+    return _builder_payload_identity_value(payload, ("app_name_after", "app_name", "appName", "appTitle", "app_title", "name", "title"))
+
+
+def _builder_payload_identity_value(payload: JSONObject, keys: tuple[str, ...]) -> object:
+    for key in keys:
+        value = payload.get(key)
+        if value not in (None, ""):
+            return value
+    for container_key in ("normalized_args", "canonical_arguments"):
+        container = payload.get(container_key)
+        if isinstance(container, dict):
+            for key in keys:
+                value = container.get(key)
+                if value not in (None, ""):
+                    return value
+    details = payload.get("details")
+    if isinstance(details, dict):
+        for container_key in ("normalized_args", "canonical_arguments"):
+            container = details.get(container_key)
+            if isinstance(container, dict):
+                for key in keys:
+                    value = container.get(key)
+                    if value not in (None, ""):
+                        return value
+    return None
+
+
+def _builder_package_resources(payload: JSONObject) -> list[JSONObject]:
+    package_id = payload.get("package_id") or payload.get("id")
+    package_name = payload.get("package_name") or payload.get("name")
+    status = _builder_status(payload, "success")
+    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    return [
+        _builder_resource(
+            resource_type="package",
+            operation=operation,
+            status=status,
+            id_value=package_id,
+            key=str(package_id) if package_id not in (None, "") else None,
+            name=package_name,
+            ids={"package_id": package_id} if package_id not in (None, "") else {},
+            error_code=payload.get("error_code"),
+            message=payload.get("message") if status == "failed" else None,
+        )
+    ]
+
+
+def _builder_schema_resources(payload: JSONObject) -> list[JSONObject]:
+    if payload.get("mode") == "multi_app" and isinstance(payload.get("apps"), list):
+        resources: list[JSONObject] = []
+        package_id = payload.get("package_id")
+        package_parent = _builder_parent("package", id_value=package_id, key=package_id) if package_id not in (None, "") else None
+        for item in payload.get("apps") or []:
+            if not isinstance(item, dict):
+                continue
+            status = _builder_status(item, "success")
+            operation = "failed" if status == "failed" else ("created" if bool(item.get("created")) else "updated")
+            parent = _builder_parent("app", key=item.get("app_key"), name=item.get("app_name"))
+            resources.append(
+                _builder_resource(
+                    resource_type="app",
+                    operation=operation,
+                    status=status,
+                    key=item.get("app_key"),
+                    name=item.get("app_name"),
+                    ids={
+                        **({"app_key": item.get("app_key")} if item.get("app_key") else {}),
+                        **({"package_id": package_id} if package_id not in (None, "") else {}),
+                    },
+                    parent=package_parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status == "failed" else None,
+                )
+            )
+            resources.extend(_builder_field_resources(item.get("field_diff_details") or item.get("field_diff"), parent=parent))
+        return resources
+
+    status = _builder_status(payload, "success")
+    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    app_key = payload.get("app_key")
+    app_name = payload.get("app_name_after") or payload.get("app_name")
+    parent = _builder_parent("app", key=app_key, name=app_name)
+    resources = [
+        _builder_resource(
+            resource_type="app",
+            operation=operation,
+            status=status,
+            key=app_key,
+            name=app_name,
+            ids={"app_key": app_key} if app_key else {},
+            error_code=payload.get("error_code"),
+            message=payload.get("message") if status == "failed" else None,
+        )
+    ]
+    resources.extend(_builder_field_resources(payload.get("field_diff_details") or payload.get("field_diff"), parent=parent))
+    return resources
+
+
+def _builder_field_resources(field_diff: object, *, parent: JSONObject | None) -> list[JSONObject]:
+    if not isinstance(field_diff, dict):
+        return []
+    resources: list[JSONObject] = []
+    for key, operation in (("added", "created"), ("updated", "updated"), ("removed", "removed")):
+        for field in field_diff.get(key) or []:
+            if isinstance(field, dict):
+                name = field.get("name") or field.get("title") or field.get("field_name") or field.get("queTitle")
+                field_id = field.get("field_id") or field.get("queId")
+                que_id = field.get("que_id") or field.get("queId")
+            else:
+                name = field
+                field_id = None
+                que_id = None
+            resource_id = que_id if que_id not in (None, "") else field_id
+            resources.append(
+                _builder_resource(
+                    resource_type="field",
+                    operation=operation,
+                    status="success",
+                    id_value=resource_id,
+                    key=field_id if field_id not in (None, "") else name,
+                    name=name,
+                    ids={
+                        **({"field_id": field_id} if field_id not in (None, "") else {}),
+                        **({"que_id": que_id} if que_id not in (None, "") else {}),
+                        **({"app_key": parent.get("key")} if isinstance(parent, dict) and parent.get("key") else {}),
+                    },
+                    parent=parent,
+                )
+            )
+    return resources
+
+
+def _builder_view_resources(payload: JSONObject) -> list[JSONObject]:
+    diff = payload.get("views_diff") if isinstance(payload.get("views_diff"), dict) else {}
+    verification_by_name = _builder_view_verification_by_name(payload)
+    parent = _builder_app_parent(payload)
+    resources: list[JSONObject] = []
+    for key, operation in (("created", "created"), ("updated", "updated"), ("removed", "removed")):
+        for item in diff.get(key) or []:
+            name, view_key, status, error_code, message = _builder_view_identity(item, verification_by_name)
+            resources.append(
+                _builder_resource(
+                    resource_type="view",
+                    operation=operation,
+                    status=status,
+                    key=view_key,
+                    name=name,
+                    ids={
+                        **({"view_key": view_key} if view_key else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    },
+                    parent=parent,
+                    error_code=error_code,
+                    message=message,
+                )
+            )
+    for item in diff.get("failed") or []:
+        name, view_key, _status, error_code, message = _builder_view_identity(item, verification_by_name)
+        resources.append(
+            _builder_resource(
+                resource_type="view",
+                operation="failed",
+                status="failed",
+                key=view_key,
+                name=name,
+                ids={
+                    **({"view_key": view_key} if view_key else {}),
+                    **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                },
+                parent=parent,
+                error_code=error_code,
+                message=message,
+            )
+        )
+    return resources
+
+
+def _builder_view_verification_by_name(payload: JSONObject) -> dict[str, JSONObject]:
+    verification = payload.get("verification")
+    by_view = verification.get("by_view") if isinstance(verification, dict) else None
+    result: dict[str, JSONObject] = {}
+    if isinstance(by_view, list):
+        for item in by_view:
+            if isinstance(item, dict):
+                name = str(item.get("name") or "").strip()
+                if name:
+                    result[name] = item
+    return result
+
+
+def _builder_view_identity(item: object, verification_by_name: dict[str, JSONObject]) -> tuple[str | None, str | None, str, object, object]:
+    if isinstance(item, dict):
+        name = item.get("name") or item.get("view_name") or item.get("viewName")
+        view_key = item.get("view_key") or item.get("viewKey")
+        status = str(item.get("status") or "success")
+        error_code = item.get("error_code")
+        message = item.get("message")
+    else:
+        name = str(item) if item not in (None, "") else None
+        view_key = None
+        status = "success"
+        error_code = None
+        message = None
+    if name and not view_key:
+        verification = verification_by_name.get(str(name))
+        if isinstance(verification, dict):
+            view_key = verification.get("view_key") or verification.get("viewKey")
+            if not view_key:
+                matching = verification.get("matching_view_keys")
+                if isinstance(matching, list) and matching:
+                    view_key = matching[0]
+    return (
+        str(name) if name not in (None, "") else None,
+        str(view_key) if view_key not in (None, "") else None,
+        status,
+        error_code,
+        message,
+    )
+
+
+def _builder_chart_resources(payload: JSONObject) -> list[JSONObject]:
+    parent = _builder_app_parent(payload)
+    resources: list[JSONObject] = []
+    for item in payload.get("chart_results") or []:
+        if not isinstance(item, dict):
+            continue
+        status = str(item.get("status") or "success")
+        operation = _builder_operation(status, fallback="updated")
+        if status == "failed":
+            operation = "failed"
+        chart_id = item.get("chart_id") or item.get("chartId")
+        chart_key = item.get("chart_key") or item.get("chartKey")
+        resources.append(
+            _builder_resource(
+                resource_type="chart",
+                operation=operation,
+                status="failed" if status == "failed" else "success",
+                id_value=chart_id,
+                key=chart_key or chart_id,
+                name=item.get("name") or item.get("chart_name") or item.get("chartName"),
+                ids={
+                    **({"chart_id": chart_id} if chart_id not in (None, "") else {}),
+                    **({"chart_key": chart_key} if chart_key else {}),
+                    **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    **({"chart_type": item.get("chart_type")} if item.get("chart_type") else {}),
+                },
+                parent=parent,
+                error_code=item.get("error_code"),
+                message=item.get("message") if status == "failed" else None,
+            )
+        )
+    return resources
+
+
+def _builder_portal_resources(payload: JSONObject) -> list[JSONObject]:
+    status = _builder_status(payload, "success")
+    draft_result = payload.get("draft_result") if isinstance(payload.get("draft_result"), dict) else {}
+    live_result = payload.get("live_result") if isinstance(payload.get("live_result"), dict) else {}
+    normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
+    dash_key = (
+        payload.get("dash_key")
+        or payload.get("dashKey")
+        or draft_result.get("dashKey")
+        or draft_result.get("dash_key")
+        or live_result.get("dashKey")
+        or live_result.get("dash_key")
+    )
+    dash_name = (
+        payload.get("dash_name")
+        or payload.get("dashName")
+        or payload.get("name")
+        or draft_result.get("dashName")
+        or draft_result.get("dash_name")
+        or draft_result.get("name")
+        or live_result.get("dashName")
+        or live_result.get("dash_name")
+        or live_result.get("name")
+        or normalized_args.get("dash_name")
+        or normalized_args.get("dashName")
+    )
+    package_id = payload.get("package_id") or normalized_args.get("package_id") or normalized_args.get("package_tag_id")
+    if package_id in (None, "") and isinstance(draft_result.get("tags"), list) and draft_result.get("tags"):
+        first_tag = draft_result.get("tags")[0]
+        if isinstance(first_tag, dict):
+            package_id = first_tag.get("tagId") or first_tag.get("tag_id") or first_tag.get("id")
+    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    parent = None
+    if package_id:
+        parent = _builder_parent("package", id_value=package_id, key=package_id)
+    return [
+        _builder_resource(
+            resource_type="portal",
+            operation=operation,
+            status=status,
+            key=dash_key,
+            name=dash_name,
+            ids={
+                **({"dash_key": dash_key} if dash_key else {}),
+                **({"package_id": package_id} if package_id else {}),
+            },
+            parent=parent,
+            error_code=payload.get("error_code"),
+            message=payload.get("message") if status == "failed" else None,
+        )
+    ]
+
+
+def _builder_button_resources(payload: JSONObject) -> list[JSONObject]:
+    parent = _builder_app_parent(payload)
+    resources: list[JSONObject] = []
+    for key, operation in (("created", "created"), ("updated", "updated"), ("removed", "removed"), ("failed", "failed")):
+        for item in payload.get(key) or []:
+            if not isinstance(item, dict):
+                continue
+            status = "failed" if operation == "failed" or item.get("status") == "failed" else str(item.get("status") or "success")
+            button_id = item.get("button_id") or item.get("buttonId")
+            resources.append(
+                _builder_resource(
+                    resource_type="button",
+                    operation=operation if operation != "failed" else "failed",
+                    status=status,
+                    id_value=button_id,
+                    key=button_id,
+                    name=item.get("button_text") or item.get("buttonText"),
+                    ids={
+                        **({"button_id": button_id} if button_id not in (None, "") else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    },
+                    parent=parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status == "failed" else None,
+                )
+            )
+    for item in payload.get("view_configs") or []:
+        if isinstance(item, dict):
+            status = str(item.get("status") or "success")
+            view_key = item.get("view_key") or item.get("viewKey")
+            resources.append(
+                _builder_resource(
+                    resource_type="button_binding",
+                    operation="updated" if status != "failed" else "failed",
+                    status=status,
+                    key=view_key,
+                    name=item.get("view_name") or item.get("viewName") or view_key,
+                    ids={
+                        **({"view_key": view_key} if view_key else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    },
+                    parent=parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status == "failed" else None,
+                )
+            )
+    return resources
+
+
+def _builder_associated_resource_resources(payload: JSONObject) -> list[JSONObject]:
+    parent = _builder_app_parent(payload)
+    readback_by_id = _builder_associated_resource_readback_by_id(payload)
+    resources: list[JSONObject] = []
+    for key, operation in (
+        ("created", "created"),
+        ("updated", "updated"),
+        ("unchanged", "unchanged"),
+        ("removed", "removed"),
+        ("failed", "failed"),
+    ):
+        for item in payload.get(key) or []:
+            if not isinstance(item, dict):
+                continue
+            status = "failed" if operation == "failed" or item.get("status") == "failed" else str(item.get("status") or "success")
+            associated_item_id = item.get("associated_item_id") or item.get("associatedItemId")
+            readback = readback_by_id.get(str(associated_item_id)) if associated_item_id not in (None, "") else None
+            view_key = item.get("view_key") or item.get("viewKey") or (readback or {}).get("view_key") or (readback or {}).get("viewKey")
+            chart_key = item.get("chart_key") or item.get("chartKey") or (readback or {}).get("chart_key") or (readback or {}).get("chartKey")
+            target_app_key = item.get("target_app_key") or (readback or {}).get("target_app_key")
+            name = item.get("name") or item.get("resource_name") or (readback or {}).get("name") or view_key or chart_key
+            resources.append(
+                _builder_resource(
+                    resource_type="associated_resource",
+                    operation=operation if operation != "failed" else "failed",
+                    status=status,
+                    id_value=associated_item_id,
+                    key=view_key or chart_key or associated_item_id,
+                    name=name,
+                    ids={
+                        **({"associated_item_id": associated_item_id} if associated_item_id not in (None, "") else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                        **({"target_app_key": target_app_key} if target_app_key else {}),
+                        **({"view_key": view_key} if view_key else {}),
+                        **({"chart_key": chart_key} if chart_key else {}),
+                    },
+                    parent=parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status == "failed" else None,
+                )
+            )
+    for item in payload.get("view_configs") or []:
+        if isinstance(item, dict):
+            status = str(item.get("status") or "success")
+            view_key = item.get("view_key") or item.get("viewKey")
+            resources.append(
+                _builder_resource(
+                    resource_type="associated_resource_binding",
+                    operation="updated" if status != "failed" else "failed",
+                    status=status,
+                    key=view_key,
+                    name=item.get("view_name") or item.get("viewName") or view_key,
+                    ids={
+                        **({"view_key": view_key} if view_key else {}),
+                        **({"app_key": payload.get("app_key")} if payload.get("app_key") else {}),
+                    },
+                    parent=parent,
+                    error_code=item.get("error_code"),
+                    message=item.get("message") if status == "failed" else None,
+                )
+            )
+    return resources
+
+
+def _builder_associated_resource_readback_by_id(payload: JSONObject) -> dict[str, JSONObject]:
+    result: dict[str, JSONObject] = {}
+
+    def collect(items: object) -> None:
+        if not isinstance(items, list):
+            return
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            associated_item_id = item.get("associated_item_id") or item.get("associatedItemId")
+            if associated_item_id in (None, ""):
+                continue
+            result[str(associated_item_id)] = item
+
+    collect(payload.get("associated_resources"))
+    for config in payload.get("view_configs") or []:
+        if not isinstance(config, dict):
+            continue
+        for key in ("actual", "expected"):
+            value = config.get(key)
+            if isinstance(value, dict):
+                collect(value.get("items"))
+    return result
+
+
 def _coerce_api_error(error: Exception) -> QingflowApiError:
     if isinstance(error, QingflowApiError):
         return error
@@ -2976,6 +4036,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "graphType": "graph_type",
             "targetAppKey": "target_app_key",
             "chartKey": "chart_key",
+            "chartId": "chart_key",
             "viewKey": "view_key",
             "viewgraphKey": "view_key",
             "reportSource": "report_source",
@@ -2990,12 +4051,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view_configs[].limit_type": ["all", "select"],
         },
         "execution_notes": [
+            "this tool manages Qingflow in-app associated report/view display; it does not create or edit QingBI report bodies/configs",
+            "create or edit app-source BI report bodies first with app_charts_apply, then attach the resulting chart_id here with graph_type=chart; dataset BI reports can only be attached when they already exist",
             "this is the default associated report/view path; it manages both the app-level associated resource pool and per-view display config",
             "use patch_resources for partial parameter replacement on existing associated resources; the tool reads the current resource including backend-required raw fields, merges patch_resources[].set/unset, then submits the backend full-save payload internally",
-            "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; it is not chart_id, chart_key, or view_key",
+            "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; view_configs/remove/reorder may also pass an existing associated resource's chart_id/chart_key/view_key and the tool resolves it to the internal id",
             "before creating an associated resource, read app_get.associated_resources and reuse an existing item with patch_resources when target_app_key + view_key/chart_key already matches; repeated upsert_resources without associated_item_id can create duplicate associated items",
             "graph_type=view uses view_key and internally compiles to the Qingflow view source; graph_type=chart uses chart_key and defaults to report_source=app",
-            "report_source=app maps to BI_QINGFLOW; report_source=dataset maps to BI_DATASET; do not pass raw backend sourceType",
+            "report_source=app maps to BI_QINGFLOW; report_source=dataset maps to BI_DATASET for associating an existing dataset report; do not pass raw backend sourceType",
             "use match_mappings for associated view/report filtering; dynamic conditions use source_field and static conditions use value",
             "match_mappings.source_field accepts source schema fields plus system fields 数据ID(-17) and 编号(0); match_mappings compiles to backend matchRules",
             "do not write raw match_rules unless preserving a legacy backend config; match_mappings and match_rules are mutually exclusive",
@@ -3102,11 +4165,40 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_apply": {
-        "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": [
+            "app_key",
+            "package_id",
+            "app_name",
+            "icon",
+            "color",
+            "visibility",
+            "create_if_missing",
+            "publish",
+            "add_fields",
+            "update_fields",
+            "remove_fields",
+            "apps",
+            "apps[].client_key",
+            "apps[].app_key",
+            "apps[].app_name",
+            "apps[].icon",
+            "apps[].color",
+            "apps[].visibility",
+            "apps[].add_fields",
+            "apps[].update_fields",
+            "apps[].remove_fields",
+            "apps[].add_fields[].target_app_ref",
+        ],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
             "packageId": "package_id",
+            "apps[].clientKey": "apps[].client_key",
+            "apps[].appKey": "apps[].app_key",
+            "apps[].appName": "apps[].app_name",
+            "apps[].appTitle": "apps[].app_name",
+            "field.targetAppRef": "field.target_app_ref",
+            "field.targetAppClientKey": "field.target_app_ref",
             "field.title": "field.name",
             "field.label": "field.name",
             "field.fields": "field.subfields",
@@ -3143,6 +4235,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use exactly one resource mode",
             "edit mode: app_key, optional app_name to rename the existing app",
             "create mode: package_id + app_name + create_if_missing=true",
+            "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
+            "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
+            "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
             *_VISIBILITY_EXECUTION_NOTES,
             "update_fields is the field-level partial update path; it reads current form schema and preserves untouched field config",
@@ -3180,6 +4275,36 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "update_fields": [],
             "remove_fields": [],
         },
+        "multi_app_example": {
+            "profile": "default",
+            "package_id": 1001,
+            "create_if_missing": True,
+            "publish": True,
+            "apps": [
+                {
+                    "client_key": "employee",
+                    "app_name": "员工花名册",
+                    "add_fields": [
+                        {"name": "员工名称", "type": "text", "as_data_title": True},
+                        {"name": "员工照片", "type": "attachment", "as_data_cover": True},
+                    ],
+                },
+                {
+                    "client_key": "worklog",
+                    "app_name": "工时表",
+                    "add_fields": [
+                        {"name": "工时标题", "type": "text", "as_data_title": True},
+                        {
+                            "name": "关联员工",
+                            "type": "relation",
+                            "target_app_ref": "employee",
+                            "display_field": {"name": "员工名称"},
+                            "visible_fields": [{"name": "员工名称"}],
+                        },
+                    ],
+                },
+            ],
+        },
         "rename_example": {
             "profile": "default",
             "app_key": "APP_PROJECT",
@@ -3448,7 +4573,25 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_plan": {
-        "allowed_keys": ["app_key", "upsert_views", "patch_views", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility", "upsert_views[].query_conditions", "patch_views[].view_key", "patch_views[].name", "patch_views[].set", "patch_views[].unset"],
+        "allowed_keys": [
+            "app_key",
+            "upsert_views",
+            "patch_views",
+            "remove_views",
+            "preset",
+            "upsert_views[].view_key",
+            "upsert_views[].name",
+            "upsert_views[].type",
+            "upsert_views[].columns",
+            "upsert_views[].filters",
+            "upsert_views[].buttons",
+            "upsert_views[].visibility",
+            "upsert_views[].query_conditions",
+            "patch_views[].view_key",
+            "patch_views[].name",
+            "patch_views[].set",
+            "patch_views[].unset",
+        ],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -3480,7 +4623,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
-            "view.buttons.config_type": ["TOP", "DETAIL"],
+            "view.buttons.config_type": ["TOP", "DETAIL", "INSIDE"],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
@@ -3488,7 +4631,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
             "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
             "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
-            "view associated report/view display is now configured through app_associated_resources_apply, not app_views_apply",
+            "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
+            "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply only keeps legacy associated_resources input compatible",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
@@ -3551,7 +4695,25 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_apply": {
-        "allowed_keys": ["app_key", "publish", "upsert_views", "patch_views", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility", "upsert_views[].query_conditions", "patch_views[].view_key", "patch_views[].name", "patch_views[].set", "patch_views[].unset"],
+        "allowed_keys": [
+            "app_key",
+            "publish",
+            "upsert_views",
+            "patch_views",
+            "remove_views",
+            "upsert_views[].view_key",
+            "upsert_views[].name",
+            "upsert_views[].type",
+            "upsert_views[].columns",
+            "upsert_views[].filters",
+            "upsert_views[].buttons",
+            "upsert_views[].visibility",
+            "upsert_views[].query_conditions",
+            "patch_views[].view_key",
+            "patch_views[].name",
+            "patch_views[].set",
+            "patch_views[].unset",
+        ],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -3582,7 +4744,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
-            "view.buttons.config_type": ["TOP", "DETAIL"],
+            "view.buttons.config_type": ["TOP", "DETAIL", "INSIDE"],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
@@ -3595,7 +4757,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
             "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
             "use patch_views for partial parameter replacement on existing views; the public update mode is patch even though the backend save is still a full view payload",
-            "view associated report/view display is now configured through app_associated_resources_apply; app_views_apply keeps legacy associated_resources input compatible but it is no longer the recommended public contract",
+            "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
+            "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply keeps legacy associated_resources input compatible but it is no longer the recommended public contract",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
@@ -3673,7 +4836,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "can_edit_form covers form/schema routes only and does not imply app base-info writes",
             "returns normalized app visibility when backend auth is readable",
             "custom_buttons[].button_id is the id required by app_custom_buttons_apply view_configs[].buttons[].button_ref",
-            "associated_resources[].associated_item_id is the id required by app_associated_resources_apply.view_configs.associated_item_ids; do not pass chart_id there",
+            "associated_resources[].associated_item_id is the internal id; app_associated_resources_apply.view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3797,6 +4960,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
             "execution_notes": [
+                "this tool manages QingBI report bodies/configs; it does not attach reports to Qingflow app associated-resource display",
+                "app_charts_apply creates/updates app-source QingBI reports only; generated payloads use dataSourceType=qingflow",
+                "dataset BI reports are not created or edited by this tool yet; create them in QingBI first, then attach the existing report with app_associated_resources_apply report_source=dataset",
+                "after creating or updating an app-source report body, use app_associated_resources_apply when the report should appear inside a Qingflow app/view",
                 "app_charts_apply is immediate-live and does not publish",
                 "use patch_charts for partial parameter replacement on existing charts; the tool reads current chart base/config, merges patch_charts[].set/unset, then submits full QingBI base/config payloads internally",
                 "chart matching precedence is chart_id first, then exact unique chart name",