@copilotkit/react-core 1.59.4 → 1.59.5-canary.1781104893

package/dist/{copilotkit-DoIlZQqa.mjs → copilotkit-DBOofUYQ.mjs}

@@ -1995,7 +1995,7 @@ function LicenseWarningBanner({ type, featureName, expiryDate, graceRemaining, o
 			severity: "warning",
 			message: `Your CopilotKit license expires in ${graceRemaining} day${graceRemaining !== 1 ? "s" : ""}. Please renew.`,
 			actionLabel: "Renew",
-			actionUrl: "https://cloud.copilotkit.ai",
+			actionUrl: "https://dashboard.operations.copilotkit.ai",
 			onDismiss
 		});
 		case "expired": return /* @__PURE__ */ jsx(BannerShell, {
@@ -2924,210 +2924,110 @@ const OpenGenerativeUIToolRenderer = function OpenGenerativeUIToolRenderer(props
 };
 
 //#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) {
-		initializeDefaultCatalog();
-		injectStyles();
-		initialized = true;
-	}
-}
-function createA2UIMessageRenderer(options) {
-	const { theme, catalog, loadingComponent } = options;
-	return {
-		activityType: "a2ui-surface",
-		content: z.any(),
-		render: ({ content, agent }) => {
-			ensureInitialized();
-			const [operations, setOperations] = useState([]);
-			const { copilotkit } = useCopilotKit();
-			const lastContentRef = useRef(null);
-			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 = useMemo(() => {
-				const groups = /* @__PURE__ */ new Map();
-				for (const operation of operations) {
-					const surfaceId = getOperationSurfaceId(operation) ?? DEFAULT_SURFACE_ID;
-					if (!groups.has(surfaceId)) groups.set(surfaceId, []);
-					groups.get(surfaceId).push(operation);
-				}
-				return groups;
-			}, [operations]);
-			if (!groupedOperations.size) return /* @__PURE__ */ jsx(loadingComponent ?? DefaultA2UILoading, {});
-			return /* @__PURE__ */ 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__ */ jsx(ReactSurfaceHost, {
-					surfaceId,
-					operations: ops,
-					theme,
-					agent,
-					copilotkit,
-					catalog
-				}, surfaceId))
-			});
-		}
-	};
-}
-/**
-* 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__ */ jsx("div", {
-		className: "cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4",
-		children: /* @__PURE__ */ jsxs(A2UIProvider, {
-			onAction: 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__ */ jsx(SurfaceMessageProcessor, {
-				surfaceId,
-				operations
-			}), /* @__PURE__ */ jsx(A2UISurfaceOrError, { surfaceId })]
-		})
-	});
+const A2UILifecycleFields = {
+	status: z.enum([
+		"building",
+		"retrying",
+		"failed"
+	]).optional(),
+	attempt: z.number().optional(),
+	maxAttempts: z.number().optional(),
+	progressTokens: z.number().optional(),
+	error: z.string().optional(),
+	errors: z.array(z.any()).optional(),
+	attempts: z.array(z.any()).optional(),
+	debugExposure: 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 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 = useA2UIError();
-	if (error) return /* @__PURE__ */ 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__ */ jsx(A2UIRenderer, {
-		surfaceId,
-		className: "cpk:flex cpk:flex-1"
+/** building: the generic skeleton + optional live token count. */
+function A2UIBuildingState({ content }) {
+	return /* @__PURE__ */ jsx(A2UIGeneratingSkeleton, {
+		label: "Building interface",
+		tokens: typeof content?.progressTokens === "number" ? content.progressTokens : void 0
 	});
 }
 /**
-* Processes A2UI operations into the provider's message processor.
-* Must be a child of A2UIProvider to access the actions context.
+* 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 SurfaceMessageProcessor({ surfaceId, operations }) {
-	const { processMessages, getSurface } = useA2UIActions();
-	const lastHashRef = useRef("");
+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] = useState(immediate);
 	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;
+		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__ */ jsx(A2UIGeneratingSkeleton, {
+		label: "Building interface",
+		tokens
+	});
+	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__ */ jsx(A2UIGeneratingSkeleton, {
+		label,
+		tokens,
+		children: debugExposure !== "hidden" && errors.length > 0 && /* @__PURE__ */ jsx(A2UIDebugDetails, {
+			label: "validation issues",
+			open: debugExposure === "verbose",
+			payload: {
+				attempt: content?.attempt,
+				errors
+			}
+		})
+	});
 }
-/**
-* 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__ */ 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__ */ jsxs("div", {
-				className: "cpk:flex cpk:items-center cpk:gap-2",
-				children: [/* @__PURE__ */ 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__ */ jsx("span", {
-					className: "cpk:text-xs cpk:font-medium cpk:text-gray-400",
-					children: "Generating UI..."
-				})]
+			/* @__PURE__ */ jsx("div", {
+				className: "cpk:font-medium",
+				children: "Couldn't generate the UI"
 			}),
 			/* @__PURE__ */ jsx("div", {
-				className: "cpk:flex cpk:flex-col cpk:gap-2",
-				children: [
-					.8,
-					.6,
-					.4
-				].map((width, i) => /* @__PURE__ */ 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__ */ jsx("style", { children: `
-        @keyframes cpk-a2ui-pulse {
-          0%, 100% { opacity: 0.4; }
-          50% { opacity: 1; }
-        }
-      ` })
+			debugExposure !== "hidden" && /* @__PURE__ */ 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.
+* 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.
 */
-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", ... })`.
-*/
-function A2UIProgressIndicator({ parameters }) {
-	const lastRef = 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__ */ jsxs("div", {
 		style: {
 			margin: "12px 0",
@@ -3335,8 +3235,8 @@ function A2UIProgressIndicator({ parameters }) {
 						color: "#a1a1aa",
 						letterSpacing: "0.025em"
 					},
-					children: "Building interface"
-				}), tokens > 0 && /* @__PURE__ */ jsxs("span", {
+					children: label
+				}), typeof tokens === "number" && tokens > 0 && /* @__PURE__ */ jsxs("span", {
 					style: {
 						fontSize: 11,
 						color: "#d4d4d8",
@@ -3349,6 +3249,7 @@ function A2UIProgressIndicator({ parameters }) {
 					]
 				})]
 			}),
+			children,
 			/* @__PURE__ */ jsx("style", { children: `
         @keyframes cpk-a2ui-fade {
           0%, 100% { opacity: 1; }
@@ -3362,6 +3263,20 @@ function A2UIProgressIndicator({ parameters }) {
 		]
 	});
 }
+function A2UIDebugDetails({ label, open, payload }) {
+	return /* @__PURE__ */ jsxs("details", {
+		open,
+		className: "cpk:mt-2 cpk:text-xs",
+		children: [/* @__PURE__ */ jsx("summary", {
+			className: "cpk:cursor-pointer cpk:text-gray-500",
+			children: label
+		}), /* @__PURE__ */ 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__ */ jsx("div", { style: {
 		width: 7,
@@ -3397,13 +3312,242 @@ function Row({ children, show, delay = 0 }) {
 		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) {
+		initializeDefaultCatalog();
+		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 = z.object({
+	a2ui_operations: z.array(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] = useState([]);
+			const { copilotkit } = useCopilotKit();
+			const lastContentRef = useRef(null);
+			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 = useMemo(() => {
+				const groups = /* @__PURE__ */ new Map();
+				for (const operation of operations) {
+					const surfaceId = getOperationSurfaceId(operation) ?? 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__ */ jsx(A2UIRecoveryFailure, {
+					content: c,
+					debugExposure
+				});
+				if (status === "retrying") return /* @__PURE__ */ jsx(A2UIRetryingState, {
+					content: c,
+					showAfterMs,
+					showAfterAttempts,
+					debugExposure
+				});
+				if (loadingComponent) return /* @__PURE__ */ jsx(loadingComponent, {});
+				return /* @__PURE__ */ jsx(A2UIBuildingState, { content: c });
+			};
+			const lastLoaderContentRef = useRef(null);
+			if (!(Array.isArray(content?.[A2UI_OPERATIONS_KEY]) && content[A2UI_OPERATIONS_KEY].length > 0)) lastLoaderContentRef.current = content;
+			const [surfaceReady, setSurfaceReady] = useState(false);
+			const readyRef = useRef(false);
+			const markSurfaceReady = useCallback(() => {
+				if (readyRef.current) return;
+				readyRef.current = true;
+				requestAnimationFrame(() => setSurfaceReady(true));
+			}, []);
+			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__ */ 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__ */ jsx(ReactSurfaceHost, {
+					surfaceId,
+					operations: ops,
+					theme,
+					agent,
+					copilotkit,
+					catalog,
+					onReady: markSurfaceReady
+				}, surfaceId))
+			});
+			return /* @__PURE__ */ jsxs("div", {
+				style: { position: "relative" },
+				children: [/* @__PURE__ */ 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__ */ jsx("div", {
+		className: "cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4",
+		children: /* @__PURE__ */ jsxs(A2UIProvider, {
+			onAction: 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__ */ jsx(SurfaceMessageProcessor, {
+				surfaceId,
+				operations,
+				onReady
+			}), /* @__PURE__ */ jsx(A2UISurfaceOrError, { surfaceId })]
+		})
+	});
+}
+/**
+* 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 = useA2UIError();
+	if (error) return /* @__PURE__ */ 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__ */ jsx(A2UIRenderer, {
+		surfaceId,
+		className: "cpk:flex cpk:flex-1"
+	});
+}
 /**
-* Registers the built-in `render_a2ui` tool call renderer via the props-based
-* `setRenderToolCalls` mechanism (not `useRenderTool`).
+* 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 } = useA2UIActions();
+	const lastHashRef = useRef("");
+	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.
 *
-* 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.
+* 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();
@@ -3411,15 +3555,7 @@ function A2UIBuiltInToolCallRenderer() {
 		const renderer = defineToolCallRenderer({
 			name: RENDER_A2UI_TOOL_NAME,
 			args: z.any(),
-			render: ({ status, args: parameters }) => {
-				if (status === "complete") return /* @__PURE__ */ jsx(Fragment$1, {});
-				const params = parameters;
-				const items = params?.items;
-				if (Array.isArray(items) && items.length > 0) return /* @__PURE__ */ jsx(Fragment$1, {});
-				const components = params?.components;
-				if (Array.isArray(components) && components.length > 2) return /* @__PURE__ */ jsx(Fragment$1, {});
-				return /* @__PURE__ */ jsx(A2UIProgressIndicator, { parameters });
-			}
+			render: () => /* @__PURE__ */ jsx(Fragment$1, {})
 		});
 		const existing = copilotkit._renderToolCalls ?? [];
 		copilotkit.setRenderToolCalls([...existing.filter((rc) => rc.name !== RENDER_A2UI_TOOL_NAME), renderer]);
@@ -3556,7 +3692,8 @@ const CopilotKitProvider = ({ children, runtimeUrl, headers: headersProp = EMPTY
 		if (runtimeA2UIEnabled) renderers.unshift(createA2UIMessageRenderer({
 			theme: a2ui?.theme ?? viewerTheme,
 			catalog: a2ui?.catalog,
-			loadingComponent: a2ui?.loadingComponent
+			loadingComponent: a2ui?.loadingComponent,
+			recovery: a2ui?.recovery
 		}));
 		return renderers;
 	}, [
@@ -6034,40 +6171,28 @@ const ScrollElementContext = React.createContext(null);
 * rendered by the {@link IntelligenceIndicator} brain and the default
 * value for the `intelligenceIndicator` slot.
 *
-* Single-element three-stage design:
-*  1. **In-progress.** Glassmorphism pill chrome around a 270° arc icon
-*     and the label. The arc has a single continuous visible stroke
-*     (one `stroke-dasharray` dash + one gap, summing to the path
-*     length) and the whole SVG rotates — so the viewer sees one
-*     C-shaped arc spinning around the visual center.
-*  2. **Icon morph (~250 ms).** On status flip the single icon path
-*     interpolates from the arc to a checkmark via CSS `d:` while the
-*     dashed stroke transitions to solid (filling in the gap that was
-*     the spinner's open portion). The SVG rotation animation is
-*     removed; the snap back to identity is masked by the simultaneous
-*     shape change. Chrome and text stay at full opacity throughout.
-*  3. **Settle (~400 ms, starts at +250 ms).** Chrome (background,
-*     border, shadow, backdrop-blur) fades to zero opacity. The label
-*     and icon stroke color transitions from saturated purple to a
-*     true-neutral gray at 0.8 alpha — no hue cast, reads as "settled
-*     history metadata." The label simultaneously skews to ~10° (a
-*     transform-based italic feel that interpolates smoothly with the
-*     color, rather than the discrete `font-style: italic` snap that
-*     would cause a layout pop). The label text stays put — only its
-*     color and slant change — so there is no "bump" where the brand
-*     text disappears and reappears.
-*
-* Hard sequence: stage 3 has a 250 ms transition-delay so it waits
-* for stage 2 to finish. Total settle time ~650 ms in production.
+* Layout: a glassmorphism pill (the `__chrome` layer) wrapping an icon
+* and a label. The icon is two overlaid SVG paths — a spinner arc and a
+* checkmark — whose geometry lives in each path's `d` ATTRIBUTE so it
+* renders in every browser (the CSS `d:` property is Chrome-only).
 *
-* Both shapes are 3-segment cubic Bézier paths with matched command
-* structure (one `M` plus three `C`s), which is what makes the d
-* morph interpolate as a continuous shape change rather than snapping.
+* Two states, driven by the `data-status` attribute (see globals.css
+* for the exact timing):
+*  1. **In-progress.** The arc spins (CSS rotation) inside the pill and
+*     the checkmark is hidden. Label + icon are a saturated purple.
+*  2. **Finished.** The arc fades out mid-spin while the checkmark draws
+*     itself in upright (animated `stroke-dashoffset`); the pill chrome
+*     fades away; and the label + icon settle from purple to a neutral
+*     gray, with the label slanting slightly (a `transform: skewX`
+*     faux-italic, so it interpolates with the color instead of snapping
+*     and never reflows). The result reads as quiet "history metadata"
+*     rather than an active spinner. The label text itself never changes
+*     — the static check plus the color/slant shift carry the "done"
+*     meaning, so no wording change is needed.
 *
-* The label is identical in both states (default "CopilotKit
-* Intelligence"). The static check icon carries the "done" semantic;
-* the color + slant transition does the "settle" work without needing
-* any wording change.
+* All motion is gated behind `prefers-reduced-motion` (globals.css):
+* when reduced motion is requested the arc does not spin and the two
+* states swap instantly, without transitions.
 *
 * Customize via the `intelligenceIndicator` slot on `CopilotChat`:
 * a className string restyles the wrapper, a props object tweaks
@@ -6088,13 +6213,21 @@ function IntelligenceIndicatorView({ message, status, label, className, ...rest
 			"aria-hidden": "true"
 		}), /* @__PURE__ */ jsxs("span", {
 			className: "cpk-intelligence-indicator__content",
-			children: [/* @__PURE__ */ jsx("svg", {
+			children: [/* @__PURE__ */ jsxs("svg", {
 				className: "cpk-intelligence-indicator__icon",
 				viewBox: "0 0 24 24",
 				width: "14",
 				height: "14",
 				"aria-hidden": "true",
-				children: /* @__PURE__ */ jsx("path", { className: "cpk-intelligence-indicator__icon-path" })
+				children: [/* @__PURE__ */ jsx("path", {
+					className: "cpk-intelligence-indicator__icon-arc",
+					pathLength: 1,
+					d: "M 12 3 C 17 3 21 7 21 12 C 21 17 17 21 12 21 C 7 21 3 17 3 12 C 3 7 7 3 12 3"
+				}), /* @__PURE__ */ jsx("path", {
+					className: "cpk-intelligence-indicator__icon-check",
+					pathLength: 1,
+					d: "M 5 12.5 L 9 16.5 L 19 6.5"
+				})]
 			}), /* @__PURE__ */ jsx("span", {
 				className: "cpk-intelligence-indicator__label",
 				children: label
@@ -6314,6 +6447,58 @@ function IntelligenceIndicator(props) {
 //#endregion
 //#region src/v2/components/chat/CopilotChatMessageView.tsx
 /**
+* Builds a map of message.id → stable per-row React key for an entire message
+* list. A message's canonical `id` is not stable within a turn: some backends
+* re-key a message mid-stream (e.g. LangChain replaces its transient
+* `lc_run--…` streaming id with the provider's final `resp_…` id in the
+* MESSAGES_SNAPSHOT). Keying rows by `id` made React unmount/remount the row
+* on that swap — the visible HITL chat flash. Tool-call ids survive the
+* rename, so an assistant message anchored by a tool call is keyed by its
+* first tool-call id (`tc:<anchorToolCallId>`); everything else falls back to
+* `id`.
+*
+* Load-bearing assumption: this only helps when the first tool-call id itself
+* is stable across the rename; backends that re-key tool-call ids mid-stream
+* still remount.
+*
+* Collision rule: two distinct assistant messages can occasionally share a
+* first-tool-call id (e.g. due to upstream bugs or replayed state). First
+* occurrence (in list order) claims `tc:<id>`; later collisions fall back to
+* `message.id`. Every assigned key is checked against the claimed set, so
+* keys are unique even for pathological ids (e.g. a raw message id beginning
+* with "tc:"); collisions disambiguate with a deterministic numeric suffix.
+*
+* Precondition: callers must pass a deduplicated list (see
+* `deduplicateMessages`); duplicate message ids would silently overwrite map
+* entries.
+*
+* Order caveat: the collision rule is order-sensitive — if two messages
+* sharing a first tool-call id swap list positions across renders, the
+* claimant changes and both rows remount. Acceptable: that situation already
+* indicates an upstream id bug, and keys remain unique.
+*/
+function buildRowRenderKeys(messages) {
+	const keys = /* @__PURE__ */ new Map();
+	const claimed = /* @__PURE__ */ new Set();
+	for (const message of messages) {
+		let candidate;
+		if (message.role === "assistant") {
+			const anchorToolCallId = message.toolCalls?.[0]?.id;
+			if (anchorToolCallId) candidate = `tc:${anchorToolCallId}`;
+		}
+		let assigned = message.id;
+		if (candidate && !claimed.has(candidate)) assigned = candidate;
+		else if (claimed.has(assigned)) {
+			let n = 2;
+			while (claimed.has(`${assigned}:${n}`)) n += 1;
+			assigned = `${assigned}:${n}`;
+		}
+		keys.set(message.id, assigned);
+		claimed.add(assigned);
+	}
+	return keys;
+}
+/**
 * Resolves a slot value into a { Component, slotProps } pair, handling the three
 * slot forms: a component type, a className string, or a partial-props object.
 */
@@ -6492,6 +6677,7 @@ function CopilotChatMessageView({ messages = [], assistantMessage, userMessage,
 		return copilotkit.getStateByRun(config.agentId, config.threadId, resolvedRunId);
 	};
 	const deduplicatedMessages = useMemo(() => deduplicateMessages(messages), [messages]);
+	const rowRenderKeys = useMemo(() => buildRowRenderKeys(deduplicatedMessages), [deduplicatedMessages]);
 	if (process.env.NODE_ENV === "development" && deduplicatedMessages.length < messages.length) console.warn(`CopilotChatMessageView: Merged ${messages.length - deduplicatedMessages.length} message(s) with duplicate IDs.`);
 	const { Component: AssistantComponent, slotProps: assistantSlotProps } = useMemo(() => resolveSlotComponent(assistantMessage, CopilotChatAssistantMessage_default), [assistantMessage]);
 	const { Component: UserComponent, slotProps: userSlotProps } = useMemo(() => resolveSlotComponent(userMessage, CopilotChatUserMessage_default), [userMessage]);
@@ -6522,41 +6708,42 @@ function CopilotChatMessageView({ messages = [], assistantMessage, userMessage,
 	const renderMessageBlock = (message) => {
 		const elements = [];
 		const stateSnapshot = getStateSnapshotForMessage(message.id);
+		const rowKey = rowRenderKeys.get(message.id) ?? message.id;
 		if (renderCustomMessage) elements.push(/* @__PURE__ */ jsx(MemoizedCustomMessage, {
 			message,
 			position: "before",
 			renderCustomMessage,
 			stateSnapshot
-		}, `${message.id}-custom-before`));
+		}, `${rowKey}-custom-before`));
 		if (message.role === "assistant") elements.push(/* @__PURE__ */ jsx(MemoizedAssistantMessage, {
 			message,
 			messages,
 			isRunning,
 			AssistantMessageComponent: AssistantComponent,
 			slotProps: assistantSlotProps
-		}, message.id));
+		}, rowKey));
 		else if (message.role === "user") elements.push(/* @__PURE__ */ jsx(MemoizedUserMessage, {
 			message,
 			UserMessageComponent: UserComponent,
 			slotProps: userSlotProps
-		}, message.id));
+		}, rowKey));
 		else if (message.role === "activity") elements.push(/* @__PURE__ */ jsx(MemoizedActivityMessage, {
 			message,
 			renderActivityMessage
-		}, message.id));
+		}, rowKey));
 		else if (message.role === "reasoning") elements.push(/* @__PURE__ */ jsx(MemoizedReasoningMessage, {
 			message,
 			messages,
 			isRunning,
 			ReasoningMessageComponent: ReasoningComponent,
 			slotProps: reasoningSlotProps
-		}, message.id));
+		}, rowKey));
 		if (renderCustomMessage) elements.push(/* @__PURE__ */ jsx(MemoizedCustomMessage, {
 			message,
 			position: "after",
 			renderCustomMessage,
 			stateSnapshot
-		}, `${message.id}-custom-after`));
+		}, `${rowKey}-custom-after`));
 		const intelligenceTurnId = intelligenceTurnAnchors.get(message.id);
 		if (intelligenceTurnId !== void 0) elements.push(/* @__PURE__ */ jsx(IntelligenceIndicator, {
 			message,
@@ -6602,7 +6789,7 @@ function CopilotChatMessageView({ messages = [], assistantMessage, userMessage,
 							transform: `translateY(${virtualItem.start}px)`
 						},
 						children: renderMessageBlock(message)
-					}, message.id);
+					}, rowRenderKeys.get(message.id) ?? message.id);
 				})
 			}) : messageElements,
 			interruptElement,
@@ -9319,7 +9506,7 @@ const getErrorActions = (error) => {
 		} };
 		case CopilotKitErrorCode.UPGRADE_REQUIRED_ERROR: return { primary: {
 			label: "Upgrade",
-			onClick: () => window.open("https://cloud.copilotkit.ai", "_blank", "noopener,noreferrer")
+			onClick: () => window.open("https://dashboard.operations.copilotkit.ai", "_blank", "noopener,noreferrer")
 		} };
 		default: return;
 	}
@@ -10527,4 +10714,4 @@ function validateProps(props) {
 
 //#endregion
 export { useHumanInTheLoop as $, INTELLIGENCE_TURN_HEAD as A, CopilotChatToolCallsView as B, CopilotChatToggleButton as C, useCopilotChatConfiguration as Ct, CopilotChatView_default as D, CopilotChat as E, CopilotChatSuggestionPill as F, useLearnFromUserAction as G, useLearningContainers as H, CopilotChatReasoningMessage_default as I, useConfigureSuggestions as J, useThreads$1 as K, CopilotChatUserMessage_default as L, getIntelligenceTurnAnchors as M, IntelligenceIndicatorView as N, CopilotChatAttachmentQueue as O, CopilotChatSuggestionView as P, useAgent as Q, CopilotChatAttachmentRenderer as R, CopilotModalHeader as S, CopilotChatConfigurationProvider as St, DefaultOpenIcon as T, useAttachments as U, useLearningContainersInCurrentThread as V, useLearnFromUserActionInCurrentThread as W, useCapabilities as X, useSuggestions as Y, UseAgentUpdate as Z, WildcardToolCallRender as _, useCopilotKit as _t, ThreadsProvider as a, useAgentContext as at, CopilotPopupView as b, AudioRecorderError as bt, CoAgentStateRendersProvider as c, useSandboxFunctions as ct, shouldShowDevConsole as d, MCPAppsActivityType as dt, useComponent as et, useToast as f, CopilotKitInspector as ft, useCopilotContext as g, defineToolCallRenderer as gt, CopilotContext as h, useRenderTool as ht, ThreadsContext as i, CopilotKitProvider as it, IntelligenceIndicator as j, CopilotChatMessageView as k, useCoAgentStateRenders as l, MCPAppsActivityContentSchema as lt, useCopilotMessagesContext as m, useDefaultRenderTool as mt, defaultCopilotContextCategories as n, useRenderActivityMessage as nt, useThreads as o, createA2UIMessageRenderer as ot, CopilotMessagesContext as p, useRenderToolCall as pt, useInterrupt as q, CoAgentStateRenderBridge as r, useRenderCustomMessages as rt, CoAgentStateRendersContext as s, SandboxFunctionsContext as st, CopilotKit as t, useFrontendTool as tt, useAsyncCallback as u, MCPAppsActivityRenderer as ut, CopilotPopup as v, CopilotKitCoreReact as vt, DefaultCloseIcon as w, CopilotSidebarView as x, CopilotChatAudioRecorder as xt, CopilotSidebar as y, CopilotChatInput_default as yt, CopilotChatAssistantMessage_default as z };
-//# sourceMappingURL=copilotkit-DoIlZQqa.mjs.map
+//# sourceMappingURL=copilotkit-DBOofUYQ.mjs.map