@copilotkit/react-core 1.59.4 → 1.59.5

package/dist/index.umd.js

@@ -1673,210 +1673,110 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 	};
 
 //#endregion
-//#region src/v2/a2ui/A2UIMessageRenderer.tsx
+//#region src/v2/a2ui/A2UIRecoveryStates.tsx
 /**
-	* The container key used to wrap A2UI operations for explicit detection.
-	* Must match A2UI_OPERATIONS_KEY in @ag-ui/a2ui-middleware and copilotkit.a2ui (Python).
+	* The pre-paint lifecycle fields the middleware stamps onto the `a2ui-surface`
+	* activity content (alongside `a2ui_operations` on paint). `.passthrough()` keeps
+	* `a2ui_operations` and any future fields intact.
 	*/
-	const A2UI_OPERATIONS_KEY = "a2ui_operations";
-	let initialized = false;
-	function ensureInitialized() {
-		if (!initialized) {
-			(0, _copilotkit_a2ui_renderer.initializeDefaultCatalog)();
-			(0, _copilotkit_a2ui_renderer.injectStyles)();
-			initialized = true;
-		}
-	}
-	function createA2UIMessageRenderer(options) {
-		const { theme, catalog, loadingComponent } = options;
-		return {
-			activityType: "a2ui-surface",
-			content: zod.z.any(),
-			render: ({ content, agent }) => {
-				ensureInitialized();
-				const [operations, setOperations] = (0, react.useState)([]);
-				const { copilotkit } = useCopilotKit();
-				const lastContentRef = (0, react.useRef)(null);
-				(0, react.useEffect)(() => {
-					if (content === lastContentRef.current) return;
-					lastContentRef.current = content;
-					const incoming = content?.[A2UI_OPERATIONS_KEY];
-					if (!content || !Array.isArray(incoming)) {
-						setOperations([]);
-						return;
-					}
-					setOperations(incoming);
-				}, [content]);
-				const groupedOperations = (0, react.useMemo)(() => {
-					const groups = /* @__PURE__ */ new Map();
-					for (const operation of operations) {
-						const surfaceId = getOperationSurfaceId(operation) ?? _copilotkit_a2ui_renderer.DEFAULT_SURFACE_ID;
-						if (!groups.has(surfaceId)) groups.set(surfaceId, []);
-						groups.get(surfaceId).push(operation);
-					}
-					return groups;
-				}, [operations]);
-				if (!groupedOperations.size) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(loadingComponent ?? DefaultA2UILoading, {});
-				return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-					className: "cpk:flex cpk:min-h-0 cpk:flex-1 cpk:flex-col cpk:gap-6 cpk:overflow-auto cpk:py-6",
-					children: Array.from(groupedOperations.entries()).map(([surfaceId, ops]) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReactSurfaceHost, {
-						surfaceId,
-						operations: ops,
-						theme,
-						agent,
-						copilotkit,
-						catalog
-					}, surfaceId))
-				});
-			}
-		};
+	const A2UILifecycleFields = {
+		status: zod.z.enum([
+			"building",
+			"retrying",
+			"failed"
+		]).optional(),
+		attempt: zod.z.number().optional(),
+		maxAttempts: zod.z.number().optional(),
+		progressTokens: zod.z.number().optional(),
+		error: zod.z.string().optional(),
+		errors: zod.z.array(zod.z.any()).optional(),
+		attempts: zod.z.array(zod.z.any()).optional(),
+		debugExposure: zod.z.enum([
+			"hidden",
+			"collapsed",
+			"verbose"
+		]).optional()
+	};
+	/** Server-stamped debugExposure wins; else the client option; else "collapsed". */
+	function resolveDebugExposure(content, optionDebugExposure) {
+		return content?.debugExposure ?? optionDebugExposure;
 	}
-	/**
-	* Renders a single A2UI surface using the React renderer.
-	* Wraps A2UIProvider + A2UIRenderer and bridges actions back to CopilotKit.
-	*/
-	function ReactSurfaceHost({ surfaceId, operations, theme, agent, copilotkit, catalog }) {
-		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-			className: "cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4",
-			children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(_copilotkit_a2ui_renderer.A2UIProvider, {
-				onAction: (0, react.useCallback)(async (message) => {
-					if (!agent) return;
-					message.userAction;
-					try {
-						copilotkit.setProperties({
-							...copilotkit.properties,
-							a2uiAction: message
-						});
-						await copilotkit.runAgent({ agent });
-					} finally {
-						if (copilotkit.properties) {
-							const { a2uiAction, ...rest } = copilotkit.properties;
-							copilotkit.setProperties(rest);
-						}
-					}
-				}, [agent, copilotkit]),
-				theme,
-				catalog,
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SurfaceMessageProcessor, {
-					surfaceId,
-					operations
-				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UISurfaceOrError, { surfaceId })]
-			})
+	/** building: the generic skeleton + optional live token count. */
+	function A2UIBuildingState({ content }) {
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIGeneratingSkeleton, {
+			label: "Building interface",
+			tokens: typeof content?.progressTokens === "number" ? content.progressTokens : void 0
 		});
 	}
 	/**
-	* Renders the A2UI surface, or an error message if processing failed.
-	* Must be a child of A2UIProvider to access the error state.
+	* retrying: stays the generic skeleton through fast/transient retries; only once
+	* the retry is perceptible (after `showAfterMs`, or once `attempt` crosses
+	* `showAfterAttempts`) does the sub-label reveal "Retrying generation… (N/M)".
 	*/
-	function A2UISurfaceOrError({ surfaceId }) {
-		const error = (0, _copilotkit_a2ui_renderer.useA2UIError)();
-		if (error) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-			className: "cpk:rounded-lg cpk:border cpk:border-red-200 cpk:bg-red-50 cpk:p-3 cpk:text-sm cpk:text-red-700",
-			children: ["A2UI render error: ", error]
+	function A2UIRetryingState({ content, showAfterMs, showAfterAttempts, debugExposure }) {
+		const attempt = typeof content?.attempt === "number" ? content.attempt : void 0;
+		const maxAttempts = typeof content?.maxAttempts === "number" ? content.maxAttempts : void 0;
+		const immediate = attempt !== void 0 && attempt >= showAfterAttempts;
+		const [revealed, setRevealed] = (0, react.useState)(immediate);
+		(0, react.useEffect)(() => {
+			if (immediate) {
+				setRevealed(true);
+				return;
+			}
+			const timer = setTimeout(() => setRevealed(true), showAfterMs);
+			return () => clearTimeout(timer);
+		}, [immediate, showAfterMs]);
+		const tokens = typeof content?.progressTokens === "number" ? content.progressTokens : void 0;
+		if (!revealed) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIGeneratingSkeleton, {
+			label: "Building interface",
+			tokens
 		});
-		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_copilotkit_a2ui_renderer.A2UIRenderer, {
-			surfaceId,
-			className: "cpk:flex cpk:flex-1"
+		const label = attempt !== void 0 && maxAttempts !== void 0 ? `Retrying generation… (${attempt}/${maxAttempts} attempts)` : "Retrying generation…";
+		const errors = Array.isArray(content?.errors) ? content.errors : [];
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIGeneratingSkeleton, {
+			label,
+			tokens,
+			children: debugExposure !== "hidden" && errors.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIDebugDetails, {
+				label: "validation issues",
+				open: debugExposure === "verbose",
+				payload: {
+					attempt: content?.attempt,
+					errors
+				}
+			})
 		});
 	}
-	/**
-	* Processes A2UI operations into the provider's message processor.
-	* Must be a child of A2UIProvider to access the actions context.
-	*/
-	function SurfaceMessageProcessor({ surfaceId, operations }) {
-		const { processMessages, getSurface } = (0, _copilotkit_a2ui_renderer.useA2UIActions)();
-		const lastHashRef = (0, react.useRef)("");
-		(0, react.useEffect)(() => {
-			const hash = JSON.stringify(operations);
-			if (hash === lastHashRef.current) return;
-			lastHashRef.current = hash;
-			processMessages(getSurface(surfaceId) ? operations.filter((op) => !op?.createSurface) : operations);
-		}, [
-			processMessages,
-			getSurface,
-			surfaceId,
-			operations
-		]);
-		return null;
-	}
-	/**
-	* Default loading component shown while an A2UI surface is generating.
-	* Displays an animated shimmer skeleton.
-	*/
-	function DefaultA2UILoading() {
+	/** failed: a clean hard-failure card that replaces the skeleton in place. */
+	function A2UIRecoveryFailure({ content, debugExposure }) {
 		return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-			className: "cpk:flex cpk:flex-col cpk:gap-3 cpk:rounded-xl cpk:border cpk:border-gray-100 cpk:bg-gray-50/50 cpk:p-5",
-			style: { minHeight: 120 },
+			className: "cpk:rounded-lg cpk:border cpk:border-amber-200 cpk:bg-amber-50 cpk:p-3 cpk:text-sm cpk:text-amber-800",
 			children: [
-				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-					className: "cpk:flex cpk:items-center cpk:gap-2",
-					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-						className: "cpk:h-3 cpk:w-3 cpk:rounded-full cpk:bg-gray-200",
-						style: { animation: "cpk-a2ui-pulse 1.5s ease-in-out infinite" }
-					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-						className: "cpk:text-xs cpk:font-medium cpk:text-gray-400",
-						children: "Generating UI..."
-					})]
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: "cpk:font-medium",
+					children: "Couldn't generate the UI"
 				}),
 				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-					className: "cpk:flex cpk:flex-col cpk:gap-2",
-					children: [
-						.8,
-						.6,
-						.4
-					].map((width, i) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-						className: "cpk:h-3 cpk:rounded cpk:bg-gray-200/70",
-						style: {
-							width: `${width * 100}%`,
-							animation: `cpk-a2ui-pulse 1.5s ease-in-out ${i * .15}s infinite`
-						}
-					}, i))
+					className: "cpk:mt-1 cpk:text-xs cpk:text-amber-700",
+					children: "Something went wrong rendering this. You can keep chatting and try again."
 				}),
-				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: `
-        @keyframes cpk-a2ui-pulse {
-          0%, 100% { opacity: 0.4; }
-          50% { opacity: 1; }
-        }
-      ` })
+				debugExposure !== "hidden" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIDebugDetails, {
+					label: "developer details",
+					open: debugExposure === "verbose",
+					payload: {
+						error: content?.error,
+						attempts: content?.attempts
+					}
+				})
 			]
 		});
 	}
-	function getOperationSurfaceId(operation) {
-		if (!operation || typeof operation !== "object") return null;
-		if (typeof operation.surfaceId === "string") return operation.surfaceId;
-		return operation?.createSurface?.surfaceId ?? operation?.updateComponents?.surfaceId ?? operation?.updateDataModel?.surfaceId ?? operation?.deleteSurface?.surfaceId ?? null;
-	}
-
-//#endregion
-//#region src/v2/a2ui/A2UIToolCallRenderer.tsx
-/**
-	* Tool name used by the dynamic A2UI generation secondary LLM.
-	* This renderer is auto-registered when A2UI is enabled.
-	*/
-	const RENDER_A2UI_TOOL_NAME = "render_a2ui";
 	/**
-	* Built-in progress indicator for dynamic A2UI generation.
-	* Shows a skeleton wireframe that progressively reveals as tokens stream in.
-	*
-	* Registered automatically when A2UI is enabled. Users can override by
-	* providing their own `useRenderTool({ name: "render_a2ui", ... })`.
+	* Animated wireframe skeleton with a label, an optional live token count, and an
+	* optional debug-detail slot below it. Pure CSS animation (no data dependency).
+	* The `tokens` count drives a progressive reveal of skeleton rows.
 	*/
-	function A2UIProgressIndicator({ parameters }) {
-		const lastRef = (0, react.useRef)({
-			time: 0,
-			tokens: 0
-		});
-		const now = Date.now();
-		let { tokens } = lastRef.current;
-		if (now - lastRef.current.time > 200) {
-			const chars = JSON.stringify(parameters ?? {}).length;
-			tokens = Math.round(chars / 4);
-			lastRef.current = {
-				time: now,
-				tokens
-			};
-		}
-		const phase = tokens < 50 ? 0 : tokens < 200 ? 1 : tokens < 400 ? 2 : 3;
+	function A2UIGeneratingSkeleton({ label, tokens, children }) {
+		const phase = tokens == null ? 3 : tokens < 50 ? 0 : tokens < 200 ? 1 : tokens < 400 ? 2 : 3;
 		return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 			style: {
 				margin: "12px 0",
@@ -2084,8 +1984,8 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 							color: "#a1a1aa",
 							letterSpacing: "0.025em"
 						},
-						children: "Building interface"
-					}), tokens > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+						children: label
+					}), typeof tokens === "number" && tokens > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 						style: {
 							fontSize: 11,
 							color: "#d4d4d8",
@@ -2098,6 +1998,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 						]
 					})]
 				}),
+				children,
 				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: `
         @keyframes cpk-a2ui-fade {
           0%, 100% { opacity: 1; }
@@ -2111,6 +2012,20 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			]
 		});
 	}
+	function A2UIDebugDetails({ label, open, payload }) {
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("details", {
+			open,
+			className: "cpk:mt-2 cpk:text-xs",
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("summary", {
+				className: "cpk:cursor-pointer cpk:text-gray-500",
+				children: label
+			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
+				className: "cpk:mt-1 cpk:overflow-auto cpk:rounded cpk:bg-gray-100 cpk:p-2 cpk:text-gray-700",
+				style: { fontSize: 11 },
+				children: JSON.stringify(payload, null, 2)
+			})]
+		});
+	}
 	function Dot() {
 		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { style: {
 			width: 7,
@@ -2146,13 +2061,242 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			children
 		});
 	}
+
+//#endregion
+//#region src/v2/a2ui/A2UIMessageRenderer.tsx
+/**
+	* The container key used to wrap A2UI operations for explicit detection.
+	* Must match A2UI_OPERATIONS_KEY in @ag-ui/a2ui-middleware and copilotkit.a2ui (Python).
+	*/
+	const A2UI_OPERATIONS_KEY = "a2ui_operations";
+	let initialized = false;
+	function ensureInitialized() {
+		if (!initialized) {
+			(0, _copilotkit_a2ui_renderer.initializeDefaultCatalog)();
+			(0, _copilotkit_a2ui_renderer.injectStyles)();
+			initialized = true;
+		}
+	}
+	/**
+	* The `a2ui-surface` activity carries the WHOLE generative-UI lifecycle on one
+	* stable messageId (OSS-162): pre-paint `status` ("building" | "retrying" |
+	* "failed") with recovery detail, then `a2ui_operations` on paint. The states
+	* swap in place, so the painted surface replaces the skeleton with no extra
+	* coordination. `.passthrough()` preserves operations + any future fields.
+	*/
+	const A2UISurfaceContentSchema = zod.z.object({
+		a2ui_operations: zod.z.array(zod.z.any()).optional(),
+		...A2UILifecycleFields
+	}).passthrough();
+	function createA2UIMessageRenderer(options) {
+		const { theme, catalog, loadingComponent, recovery } = options;
+		const showAfterMs = recovery?.showAfterMs ?? 2e3;
+		const showAfterAttempts = recovery?.showAfterAttempts ?? 2;
+		const optionDebugExposure = recovery?.debugExposure ?? "collapsed";
+		return {
+			activityType: "a2ui-surface",
+			content: A2UISurfaceContentSchema,
+			render: ({ content, agent }) => {
+				ensureInitialized();
+				const [operations, setOperations] = (0, react.useState)([]);
+				const { copilotkit } = useCopilotKit();
+				const lastContentRef = (0, react.useRef)(null);
+				(0, react.useEffect)(() => {
+					if (content === lastContentRef.current) return;
+					lastContentRef.current = content;
+					const incoming = content?.[A2UI_OPERATIONS_KEY];
+					if (!content || !Array.isArray(incoming)) {
+						setOperations([]);
+						return;
+					}
+					setOperations(incoming);
+				}, [content]);
+				const groupedOperations = (0, react.useMemo)(() => {
+					const groups = /* @__PURE__ */ new Map();
+					for (const operation of operations) {
+						const surfaceId = getOperationSurfaceId(operation) ?? _copilotkit_a2ui_renderer.DEFAULT_SURFACE_ID;
+						if (!groups.has(surfaceId)) groups.set(surfaceId, []);
+						groups.get(surfaceId).push(operation);
+					}
+					return groups;
+				}, [operations]);
+				const hasOps = groupedOperations.size > 0;
+				const renderLifecycle = (c) => {
+					const status = c?.status;
+					const debugExposure = resolveDebugExposure(c, optionDebugExposure);
+					if (status === "failed") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIRecoveryFailure, {
+						content: c,
+						debugExposure
+					});
+					if (status === "retrying") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIRetryingState, {
+						content: c,
+						showAfterMs,
+						showAfterAttempts,
+						debugExposure
+					});
+					if (loadingComponent) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(loadingComponent, {});
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIBuildingState, { content: c });
+				};
+				const lastLoaderContentRef = (0, react.useRef)(null);
+				if (!(Array.isArray(content?.[A2UI_OPERATIONS_KEY]) && content[A2UI_OPERATIONS_KEY].length > 0)) lastLoaderContentRef.current = content;
+				const [surfaceReady, setSurfaceReady] = (0, react.useState)(false);
+				const readyRef = (0, react.useRef)(false);
+				const markSurfaceReady = (0, react.useCallback)(() => {
+					if (readyRef.current) return;
+					readyRef.current = true;
+					requestAnimationFrame(() => setSurfaceReady(true));
+				}, []);
+				(0, react.useEffect)(() => {
+					if (!hasOps) {
+						setSurfaceReady(false);
+						readyRef.current = false;
+						return;
+					}
+					const t = setTimeout(() => setSurfaceReady(true), 8e3);
+					return () => clearTimeout(t);
+				}, [hasOps]);
+				if (!hasOps) return renderLifecycle(content);
+				const surfaces = /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: "cpk:flex cpk:min-h-0 cpk:flex-1 cpk:flex-col cpk:gap-6 cpk:overflow-auto cpk:py-6",
+					children: Array.from(groupedOperations.entries()).map(([surfaceId, ops]) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReactSurfaceHost, {
+						surfaceId,
+						operations: ops,
+						theme,
+						agent,
+						copilotkit,
+						catalog,
+						onReady: markSurfaceReady
+					}, surfaceId))
+				});
+				return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					style: { position: "relative" },
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						"aria-hidden": !surfaceReady,
+						style: surfaceReady ? void 0 : {
+							position: "absolute",
+							inset: 0,
+							opacity: 0,
+							pointerEvents: "none"
+						},
+						children: surfaces
+					}), !surfaceReady && renderLifecycle(lastLoaderContentRef.current ?? content)]
+				});
+			}
+		};
+	}
+	/**
+	* Renders a single A2UI surface using the React renderer.
+	* Wraps A2UIProvider + A2UIRenderer and bridges actions back to CopilotKit.
+	*/
+	function ReactSurfaceHost({ surfaceId, operations, theme, agent, copilotkit, catalog, onReady }) {
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: "cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4",
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(_copilotkit_a2ui_renderer.A2UIProvider, {
+				onAction: (0, react.useCallback)(async (message) => {
+					if (!agent) return;
+					message.userAction;
+					try {
+						copilotkit.setProperties({
+							...copilotkit.properties,
+							a2uiAction: message
+						});
+						await copilotkit.runAgent({ agent });
+					} finally {
+						if (copilotkit.properties) {
+							const { a2uiAction, ...rest } = copilotkit.properties;
+							copilotkit.setProperties(rest);
+						}
+					}
+				}, [agent, copilotkit]),
+				theme,
+				catalog,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SurfaceMessageProcessor, {
+					surfaceId,
+					operations,
+					onReady
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UISurfaceOrError, { surfaceId })]
+			})
+		});
+	}
 	/**
-	* Registers the built-in `render_a2ui` tool call renderer via the props-based
-	* `setRenderToolCalls` mechanism (not `useRenderTool`).
-	*
-	* This ensures user-registered `useRenderTool({ name: "render_a2ui", ... })`
-	* hooks automatically override the built-in, since the merge logic in
-	* react-core.ts gives hook-based entries priority over prop-based entries.
+	* Renders the A2UI surface, or an error message if processing failed.
+	* Must be a child of A2UIProvider to access the error state.
+	*/
+	function A2UISurfaceOrError({ surfaceId }) {
+		const error = (0, _copilotkit_a2ui_renderer.useA2UIError)();
+		if (error) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: "cpk:rounded-lg cpk:border cpk:border-red-200 cpk:bg-red-50 cpk:p-3 cpk:text-sm cpk:text-red-700",
+			children: ["A2UI render error: ", error]
+		});
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_copilotkit_a2ui_renderer.A2UIRenderer, {
+			surfaceId,
+			className: "cpk:flex cpk:flex-1"
+		});
+	}
+	/**
+	* Processes A2UI operations into the provider's message processor.
+	* Must be a child of A2UIProvider to access the actions context.
+	*/
+	function SurfaceMessageProcessor({ surfaceId, operations, onReady }) {
+		const { processMessages, getSurface } = (0, _copilotkit_a2ui_renderer.useA2UIActions)();
+		const lastHashRef = (0, react.useRef)("");
+		(0, react.useEffect)(() => {
+			const hash = JSON.stringify(operations);
+			if (hash === lastHashRef.current) return;
+			lastHashRef.current = hash;
+			processMessages(getSurface(surfaceId) ? operations.filter((op) => !op?.createSurface) : operations);
+			if (onReady && surfaceHasRenderableContent(operations)) onReady();
+		}, [
+			processMessages,
+			getSurface,
+			surfaceId,
+			operations,
+			onReady
+		]);
+		return null;
+	}
+	/**
+	* Whether the surface's operations are enough to paint a visible card yet.
+	* A data-bound surface references its data via `path` and renders nothing until
+	* the data model has ≥1 value; a static surface (no path refs) paints from its
+	* components alone. Used to time the loader→surface cross-over to actual content
+	* arrival rather than a fixed delay. (OSS-162)
+	*/
+	function surfaceHasRenderableContent(operations) {
+		const componentOps = operations.filter((o) => o?.updateComponents);
+		if (!componentOps.length) return false;
+		if (!JSON.stringify(componentOps).includes("\"path\"")) return true;
+		return operations.some((o) => {
+			const v = o?.updateDataModel?.value;
+			if (!v || typeof v !== "object") return false;
+			return Object.values(v).some((x) => Array.isArray(x) ? x.length > 0 : x !== null && x !== void 0 && x !== "");
+		});
+	}
+	function getOperationSurfaceId(operation) {
+		if (!operation || typeof operation !== "object") return null;
+		if (typeof operation.surfaceId === "string") return operation.surfaceId;
+		return operation?.createSurface?.surfaceId ?? operation?.updateComponents?.surfaceId ?? operation?.updateDataModel?.surfaceId ?? operation?.deleteSurface?.surfaceId ?? null;
+	}
+
+//#endregion
+//#region src/v2/a2ui/A2UIToolCallRenderer.tsx
+/**
+	* Tool name used by the dynamic A2UI generation secondary LLM.
+	*/
+	const RENDER_A2UI_TOOL_NAME = "render_a2ui";
+	/**
+	* Registers a no-op renderer for the `render_a2ui` tool call so its raw streamed
+	* args are never surfaced in the transcript.
+	*
+	* The generation skeleton / retry / failure UX is NO LONGER owned here (OSS-162):
+	* the A2UI middleware drives the whole lifecycle on the `a2ui-surface` activity
+	* (one stable messageId, building → retrying → failed → painted), rendered in
+	* place by `createA2UIMessageRenderer`. Owning a skeleton per tool call caused a
+	* duplicate skeleton on retries / multi-call generations and a skeleton that
+	* lingered after the surface painted — both fixed by retiring it here.
+	*
+	* Users can still override with their own `useRenderTool({ name: "render_a2ui" })`
+	* (hook-based entries take priority over this prop-based registration).
 	*/
 	function A2UIBuiltInToolCallRenderer() {
 		const { copilotkit } = useCopilotKit();
@@ -2160,15 +2304,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			const renderer = defineToolCallRenderer({
 				name: RENDER_A2UI_TOOL_NAME,
 				args: zod.z.any(),
-				render: ({ status, args: parameters }) => {
-					if (status === "complete") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {});
-					const params = parameters;
-					const items = params?.items;
-					if (Array.isArray(items) && items.length > 0) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {});
-					const components = params?.components;
-					if (Array.isArray(components) && components.length > 2) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {});
-					return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIProgressIndicator, { parameters });
-				}
+				render: () => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {})
 			});
 			const existing = copilotkit._renderToolCalls ?? [];
 			copilotkit.setRenderToolCalls([...existing.filter((rc) => rc.name !== RENDER_A2UI_TOOL_NAME), renderer]);
@@ -2305,7 +2441,8 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			if (runtimeA2UIEnabled) renderers.unshift(createA2UIMessageRenderer({
 				theme: a2ui?.theme ?? _copilotkit_a2ui_renderer.viewerTheme,
 				catalog: a2ui?.catalog,
-				loadingComponent: a2ui?.loadingComponent
+				loadingComponent: a2ui?.loadingComponent,
+				recovery: a2ui?.recovery
 			}));
 			return renderers;
 		}, [