@copilotkit/react-core 1.59.3 → 1.59.5

package/dist/v2/index.umd.js

@@ -220,9 +220,9 @@ _radix_ui_react_dropdown_menu = __toESM(_radix_ui_react_dropdown_menu);
 
 //#endregion
 //#region src/v2/lib/utils.ts
-	const twMerge$7 = (0, tailwind_merge.extendTailwindMerge)({ prefix: "cpk" });
+	const twMerge$8 = (0, tailwind_merge.extendTailwindMerge)({ prefix: "cpk" });
 	function cn(...inputs) {
-		return twMerge$7((0, clsx.clsx)(inputs));
+		return twMerge$8((0, clsx.clsx)(inputs));
 	}
 
 //#endregion
@@ -2940,210 +2940,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).
-	*/
-	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))
-				});
-			}
-		};
-	}
-	/**
-	* Renders a single A2UI surface using the React renderer.
-	* Wraps A2UIProvider + A2UIRenderer and bridges actions back to CopilotKit.
+	* 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.
 	*/
-	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 })]
-			})
-		});
+	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 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"
+	/** 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
 		});
 	}
 	/**
-	* 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 } = (0, _copilotkit_a2ui_renderer.useA2UIActions)();
-		const lastHashRef = (0, react.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] = (0, react.useState)(immediate);
 		(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;
+			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
+		});
+		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
+				}
+			})
+		});
 	}
-	/**
-	* 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",
@@ -3351,8 +3251,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",
@@ -3365,6 +3265,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; }
@@ -3378,6 +3279,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,
@@ -3413,13 +3328,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 })]
+			})
+		});
+	}
+	/**
+	* 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;
+	}
 	/**
-	* Registers the built-in `render_a2ui` tool call renderer via the props-based
-	* `setRenderToolCalls` mechanism (not `useRenderTool`).
+	* 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.
 	*
-	* 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.
+	* 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();
@@ -3427,15 +3571,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]);
@@ -3572,7 +3708,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;
 		}, [
@@ -4797,6 +4934,175 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		};
 	}
 
+//#endregion
+//#region src/v2/lib/record-annotation.ts
+/**
+	* Low-level function that posts an arbitrary annotation to the CopilotKit
+	* runtime's general annotation endpoint (`POST /annotate`).
+	*
+	* This is the single transport entry point for all annotation types. Higher-
+	* level hooks (e.g. `useLearnFromUserAction`) build the `type`/`payload` pair
+	* for their specific annotation shape and delegate the HTTP call here.
+	*
+	* The function uses the same transport as `useLearnFromUserAction`:
+	* - `runtimeUrl` from `copilotkit.runtimeUrl` (BFF proxies to the platform)
+	* - `headers` from `copilotkit.headers` (customer auth forwarded to BFF)
+	* - `clientEventId` auto-generated via `randomUUID()` when omitted
+	* - `userId` is resolved server-side by the runtime; the client never sends it
+	* - Errors propagate to the caller (fire-and-propagate, not fire-and-forget)
+	*
+	* @param args - Transport dependencies plus annotation fields.
+	* @returns The platform result containing the annotation row `id` and a
+	*          `duplicate` flag.
+	* @throws When the network request fails or the runtime returns a non-2xx
+	*         status. Callers that want fire-and-forget behavior should `.catch`
+	*         at the call site.
+	*/
+	async function recordAnnotation(args) {
+		const { runtimeUrl, headers, type, payload, threadId, occurredAt } = args;
+		const body = {
+			type,
+			threadId,
+			clientEventId: args.clientEventId ?? (0, _copilotkit_shared.randomUUID)(),
+			...payload !== void 0 ? { payload } : {},
+			...occurredAt !== void 0 ? { occurredAt } : {}
+		};
+		const response = await fetch(`${runtimeUrl}/annotate`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...headers
+			},
+			body: JSON.stringify(body)
+		});
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			throw new Error(`recordAnnotation: request failed (${response.status})${text ? `: ${text}` : ""}`);
+		}
+		const text = await response.text();
+		if (!text) throw new Error(`recordAnnotation: runtime ${runtimeUrl}/annotate returned ${response.status} with an empty body`);
+		try {
+			return JSON.parse(text);
+		} catch {
+			throw new Error(`recordAnnotation: runtime ${runtimeUrl}/annotate returned a non-JSON body (status ${response.status})`);
+		}
+	}
+
+//#endregion
+//#region src/v2/hooks/use-learn-from-user-action.tsx
+/**
+	* Record a user UI interaction in the Intelligence platform's user-actions
+	* stream. The platform's auto-curated knowledge base agent reads these
+	* (alongside finished agent runs) and writes free-form Obsidian-flavored
+	* markdown to `/project`, where any agent in the same project can later
+	* read it via the `copilotkit_knowledge_base_shell` MCP tool.
+	*
+	* The hook returns a stable function. Calling it issues a request to the
+	* customer's CopilotKit runtime (`POST ${runtimeUrl}/annotate`), which
+	* resolves the Intel user from the BFF's auth and forwards to the
+	* platform — the Intel API key never reaches the browser.
+	*
+	* If `clientEventId` is omitted `recordAnnotation` generates a UUID per call,
+	* so a naive double-call (e.g. React 18 strict-mode double-mount, or a retry
+	* after a network blip on a fresh Promise) is naturally safe. Supply your
+	* own key when a single semantic event must remain idempotent across
+	* multiple `learnFromUserAction(...)` calls.
+	*
+	* @example
+	* ```tsx
+	* import { useLearnFromUserAction } from "@copilotkit/react-core";
+	*
+	* function SettingsPage({ threadId }) {
+	*   const learnFromUserAction = useLearnFromUserAction();
+	*
+	*   const onRename = (oldName: string, newName: string) => {
+	*     void learnFromUserAction({
+	*       threadId,
+	*       title: "Renamed project",
+	*       data: { previous: { name: oldName }, next: { name: newName } },
+	*     });
+	*   };
+	* }
+	* ```
+	*/
+	function useLearnFromUserAction() {
+		const { copilotkit } = useCopilotKit();
+		return (0, react.useCallback)(async (input) => {
+			const runtimeUrl = copilotkit.runtimeUrl;
+			if (!runtimeUrl) throw new Error("useLearnFromUserAction: runtimeUrl is not configured. Set it on <CopilotKitProvider runtimeUrl=...>.");
+			const payload = {
+				...input.title !== void 0 ? { title: input.title } : {},
+				...input.description !== void 0 ? { description: input.description } : {},
+				...input.data !== void 0 ? { data: input.data } : {}
+			};
+			return recordAnnotation({
+				runtimeUrl,
+				headers: copilotkit.headers ?? {},
+				type: "user_action",
+				payload: Object.keys(payload).length > 0 ? payload : void 0,
+				threadId: input.threadId,
+				clientEventId: input.clientEventId,
+				occurredAt: input.occurredAt
+			});
+		}, [copilotkit]);
+	}
+
+//#endregion
+//#region src/v2/hooks/use-learn-from-user-action-in-current-thread.tsx
+/**
+	* Record a user UI interaction against the **current chat's** thread. The
+	* `threadId` is sourced from the surrounding
+	* `<CopilotChatConfigurationProvider>` (the same provider `<CopilotChat>`,
+	* `<CopilotSidebar>`, and friends set up), so callers in a chat-aware
+	* subtree don't need to thread an id through manually.
+	*
+	* Throws on **call** (not on mount) when there is no chat-config provider
+	* in scope — matches the "throw on call when runtimeUrl is missing"
+	* behavior of {@link useLearnFromUserAction}. Mounting the hook in a branch
+	* that never fires is harmless.
+	*
+	* The recorder does NOT accept a `threadId` override. If you need to
+	* record against an explicit thread, use {@link useLearnFromUserAction}
+	* directly — two hooks, two crisp contracts, no mode confusion.
+	*
+	* This hook always uses `config.threadId`, regardless of whether the
+	* surrounding chat config minted it internally or received one from
+	* the caller. Auto-minted threads simply mean the action lands under
+	* a thread the platform never saw — the writer agent still distills
+	* user-action-only threads (it does not require the thread to exist
+	* in `cpki.threads`), so the loop keeps learning.
+	*
+	* @example
+	* ```tsx
+	* import { useLearnFromUserActionInCurrentThread } from "@copilotkit/react-core";
+	*
+	* function SettingsPanel() {
+	*   const learnFromUserAction = useLearnFromUserActionInCurrentThread();
+	*
+	*   const onRename = (oldName: string, newName: string) => {
+	*     void learnFromUserAction({
+	*       title: "Renamed project",
+	*       data: { previous: { name: oldName }, next: { name: newName } },
+	*     });
+	*   };
+	*
+	*   // ...
+	* }
+	* ```
+	*/
+	function useLearnFromUserActionInCurrentThread() {
+		const config = useCopilotChatConfiguration();
+		const learnFromUserAction = useLearnFromUserAction();
+		return (0, react.useCallback)(async (input) => {
+			const threadId = config?.threadId;
+			if (!threadId) throw new Error("useLearnFromUserActionInCurrentThread: no CopilotChatConfigurationProvider in scope. Wrap the call site in <CopilotChat>, <CopilotSidebar>, or <CopilotChatConfigurationProvider>, or use `useLearnFromUserAction()` and pass `threadId` explicitly.");
+			return learnFromUserAction({
+				...input,
+				threadId
+			});
+		}, [config?.threadId, learnFromUserAction]);
+	}
+
 //#endregion
 //#region src/v2/hooks/use-attachments.tsx
 /**
@@ -4955,6 +5261,153 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		};
 	}
 
+//#endregion
+//#region src/v2/hooks/use-learning-containers.tsx
+/** The default learning containers value. Matches the backend default. */
+	const DEFAULT_CONTAINERS = ["project"];
+	/**
+	* Declaratively keeps a thread's learning containers in sync by emitting
+	* `set_learning_containers` annotations via the CopilotKit runtime annotate
+	* endpoint (`POST ${runtimeUrl}/annotate`).
+	*
+	* **Emit rules:**
+	* - On mount with `["project"]` (the backend default) → does NOT emit.
+	*   Absence of an annotation equals the default, so the round-trip is skipped.
+	* - On mount with any other value → emits immediately.
+	* - On any subsequent content change (including a switch back to
+	*   `["project"]`) → emits (a deliberate switch is always recorded).
+	* - On unmount or threadId change → emits a reset to `["project"]`
+	*   so the backend is left in a clean state for the next consumer.
+	*   Changing `learningContainers` within the same thread does NOT reset the
+	*   thread; only the new value is emitted.
+	*
+	* Content-equality is evaluated via `JSON.stringify` so a fresh array literal
+	* with the same items does NOT trigger a redundant emit.
+	*
+	* If `runtimeUrl` is absent, all emits are silently skipped.
+	*
+	* @example
+	* ```tsx
+	* function ThreadPane({ threadId, userScope }: Props) {
+	*   useLearningContainers({
+	*     threadId,
+	*     learningContainers: [userScope],
+	*   });
+	*   // ...
+	* }
+	* ```
+	*/
+	function useLearningContainers({ threadId, learningContainers }) {
+		const { copilotkit } = useCopilotKit();
+		/**
+		* Tracks the last-synced container list so content-identical rerenders
+		* (fresh array, same values) do not fire a redundant emit.
+		* `null` = nothing synced yet (initial state or after a threadId reset).
+		*/
+		const lastSyncedRef = (0, react.useRef)(null);
+		/** Guards the missing-runtimeUrl warning so it fires at most once per hook instance. */
+		const warnedMissingUrlRef = (0, react.useRef)(false);
+		const runtimeUrlRef = (0, react.useRef)(copilotkit.runtimeUrl);
+		const headersRef = (0, react.useRef)(copilotkit.headers ?? {});
+		runtimeUrlRef.current = copilotkit.runtimeUrl;
+		headersRef.current = copilotkit.headers ?? {};
+		const key = JSON.stringify(learningContainers);
+		const defaultKey = JSON.stringify(DEFAULT_CONTAINERS);
+		(0, react.useEffect)(() => {
+			const runtimeUrl = copilotkit.runtimeUrl;
+			const headers = copilotkit.headers ?? {};
+			/**
+			* Fire-and-forget emit; errors must not surface in render.
+			* Failures are logged as warnings so they are diagnosable without
+			* propagating into the React render cycle.
+			*/
+			const emit = (containers) => {
+				if (!runtimeUrl) {
+					if (!warnedMissingUrlRef.current) {
+						warnedMissingUrlRef.current = true;
+						console.warn("useLearningContainers: runtimeUrl not configured; learning-container sync disabled");
+					}
+					return;
+				}
+				recordAnnotation({
+					runtimeUrl,
+					headers,
+					type: "set_learning_containers",
+					payload: { containers },
+					threadId
+				}).catch((err) => {
+					console.warn("useLearningContainers: failed to record set_learning_containers", err);
+				});
+			};
+			if (lastSyncedRef.current === null) {
+				if (key === defaultKey) {
+					lastSyncedRef.current = learningContainers;
+					return;
+				}
+				emit(learningContainers);
+				lastSyncedRef.current = learningContainers;
+			} else if (key !== JSON.stringify(lastSyncedRef.current)) {
+				emit(learningContainers);
+				lastSyncedRef.current = learningContainers;
+			}
+		}, [threadId, key]);
+		(0, react.useEffect)(() => {
+			const capturedThreadId = threadId;
+			return () => {
+				const capturedRuntimeUrl = runtimeUrlRef.current;
+				const capturedHeaders = headersRef.current;
+				if (capturedRuntimeUrl) recordAnnotation({
+					runtimeUrl: capturedRuntimeUrl,
+					headers: capturedHeaders,
+					type: "set_learning_containers",
+					payload: { containers: DEFAULT_CONTAINERS },
+					threadId: capturedThreadId
+				}).catch((err) => {
+					console.warn("useLearningContainers: failed to record set_learning_containers", err);
+				});
+				lastSyncedRef.current = null;
+			};
+		}, [threadId]);
+	}
+
+//#endregion
+//#region src/v2/hooks/use-learning-containers-in-current-thread.tsx
+/**
+	* Declaratively keeps the **current chat thread's** learning containers in
+	* sync. The `threadId` is sourced from the surrounding
+	* `<CopilotChatConfigurationProvider>` (the same provider `<CopilotChat>`,
+	* `<CopilotSidebar>`, and friends set up), so callers in a chat-aware
+	* subtree don't need to thread an id through manually.
+	*
+	* **Throws on render** when there is no chat-config provider in scope or
+	* when the provider does not yet have an active `threadId`. Mount the hook
+	* inside a subtree that is guaranteed to have a thread context.
+	*
+	* If you need to manage an explicit thread, use {@link useLearningContainers}
+	* directly — two hooks, two crisp contracts, no mode confusion.
+	*
+	* @throws When no `CopilotChatConfigurationProvider` is in scope or when the
+	*         active `threadId` is absent/empty.
+	*
+	* @example
+	* ```tsx
+	* function ThreadPanel({ scope }: Props) {
+	*   useLearningContainersInCurrentThread({
+	*     learningContainers: [scope],
+	*   });
+	*   // ...
+	* }
+	* ```
+	*/
+	function useLearningContainersInCurrentThread({ learningContainers }) {
+		const threadId = useCopilotChatConfiguration()?.threadId;
+		if (!threadId) throw new Error("useLearningContainersInCurrentThread must be used within a thread context (no active threadId). Wrap the component in <CopilotChat>, <CopilotSidebar>, or <CopilotChatConfigurationProvider>, or use `useLearningContainers()` and pass `threadId` explicitly.");
+		useLearningContainers({
+			threadId,
+			learningContainers
+		});
+	}
+
 //#endregion
 //#region src/v2/components/chat/CopilotChatToolCallsView.tsx
 	function CopilotChatToolCallsView({ message, messages = [] }) {
@@ -5727,33 +6180,174 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 	*/
 	const ScrollElementContext = react.default.createContext(null);
 
+//#endregion
+//#region src/v2/components/intelligence-indicator/IntelligenceIndicatorView.tsx
+/**
+	* The presentational "CopilotKit Intelligence" face — the default
+	* 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.
+	*
+	* 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.
+	*
+	* 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.
+	*
+	* Customize via the `intelligenceIndicator` slot on `CopilotChat`:
+	* a className string restyles the wrapper, a props object tweaks
+	* the default (`{ label }`), and a component replaces it entirely
+	* with full control over visuals and timing.
+	*/
+	function IntelligenceIndicatorView({ message, status, label, className, ...rest }) {
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+			className: (0, tailwind_merge.twMerge)("cpk-intelligence-indicator", className),
+			role: "status",
+			"aria-live": "polite",
+			"data-testid": `cpk-intelligence-indicator-${message.id}`,
+			"data-status": status,
+			title: label,
+			...rest,
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: "cpk-intelligence-indicator__chrome",
+				"aria-hidden": "true"
+			}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+				className: "cpk-intelligence-indicator__content",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+					className: "cpk-intelligence-indicator__icon",
+					viewBox: "0 0 24 24",
+					width: "14",
+					height: "14",
+					"aria-hidden": "true",
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { className: "cpk-intelligence-indicator__icon-path" })
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: "cpk-intelligence-indicator__label",
+					children: label
+				})]
+			})]
+		});
+	}
+
 //#endregion
 //#region src/v2/components/intelligence-indicator/IntelligenceIndicator.tsx
 /**
 	* Grace window before showing the spinner. A matching tool call must
 	* remain unresolved (no `tool`-role result message in `agent.messages`)
-	* for at least this long before the pill appears. This filters out
-	* history-replay flashes — during `connectAgent` replay, tool calls and
-	* their results arrive back-to-back in sub-millisecond bursts, so the
-	* timer is cancelled before it fires. Live runs cross the threshold
-	* easily because the tool actually has to execute.
+	* for at least this long before the indicator transitions out of
+	* `hidden`. This filters out history-replay flashes — during
+	* `connectAgent` replay, tool calls and their results arrive
+	* back-to-back in sub-millisecond bursts, so the timer is cancelled
+	* before it fires. Live runs cross the threshold easily because the
+	* tool actually has to execute.
 	*/
 	const PENDING_THRESHOLD_MS = 100;
-	/** Hold the checkmark briefly before fading out. */
-	const CHECK_HOLD_MS = 800;
 	/**
-	* Duration of the fade-out animation. Must match
-	* `cpk-intelligence-pill-fade-out` keyframes in `v2/styles/globals.css`.
+	* Tool-name regex patterns that trigger the indicator. Matches any tool
+	* name *containing* the Intelligence MCP server's canonical tool name, so
+	* both the bare `copilotkit_knowledge_base_shell` and the namespaced
+	* `mcp__<server>__copilotkit_knowledge_base_shell` form (emitted by
+	* `@ag-ui/mcp-middleware`) light up the pill. If we add per-instance
+	* customization later (e.g. a `CopilotKitProvider` prop or a runtime-info
+	* field), this constant becomes the fallback.
 	*/
-	const FADE_OUT_ANIMATION_MS = 480;
+	const DEFAULT_TOOL_PATTERNS = [/copilotkit_knowledge_base_shell/];
 	/**
-	* Tool-name regex patterns that trigger the indicator. Currently
-	* hardcoded to the Intelligence MCP server's canonical tool name. If
-	* we add per-instance customization later (e.g. a `CopilotKitProvider`
-	* prop or a runtime-info field), this constant becomes the fallback.
+	* Phase to start in when an indicator first mounts. A turn that is already
+	* complete at mount jumps straight to `finished` — no `hidden` flash, no
+	* spinner blip — which is what makes scrolled-back / replayed history render
+	* its indicators directly in the finished state.
+	*
+	* Pure and timing-free on purpose: the grace window ({@link
+	* PENDING_THRESHOLD_MS}) only controls *when* the live transition is applied;
+	* these functions decide *what* it resolves to, so the decision can be unit
+	* tested deterministically without any timers.
 	*/
-	const DEFAULT_TOOL_PATTERNS = [/^copilotkit_knowledge_base_shell$/];
+	function initialIndicatorPhase(turnComplete) {
+		return turnComplete ? "finished" : "hidden";
+	}
+	/**
+	* Phase the grace window resolves to once it elapses:
+	*   - completed turn → `finished` (replay-flash suppression: a tool whose
+	*     result lands within the window skips the spinner entirely),
+	*   - a still-pending matching tool call → `spinner`,
+	*   - otherwise stay `hidden` (the matching tool call hasn't landed yet).
+	*/
+	function resolveGracePhase(turnComplete, hasPending) {
+		if (turnComplete) return "finished";
+		if (hasPending) return "spinner";
+		return "hidden";
+	}
 	const isMatchingToolCallName = (name) => typeof name === "string" && DEFAULT_TOOL_PATTERNS.some((p) => p.test(name));
+	const messageHasMatchingToolCall = (m) => {
+		if (m.role !== "assistant") return false;
+		return (Array.isArray(m.toolCalls) ? m.toolCalls : []).some((tc) => isMatchingToolCallName(tc?.function?.name));
+	};
+	/**
+	* Stable turn id for the messages that precede the first user message (a turn
+	* with no opening user message of its own). Used as the React key so the
+	* indicator for that turn never collides with a real user-message id.
+	*/
+	const INTELLIGENCE_TURN_HEAD = "__cpk_turn_head__";
+	/**
+	* Map each Intelligence-using turn to its anchor message — the FIRST bash-using
+	* assistant message of the turn — and a stable turn id (the id of the user
+	* message that opened the turn, or {@link INTELLIGENCE_TURN_HEAD} for the
+	* pre-first-user turn). Returns `Map<anchorMessageId, turnId>`.
+	*
+	* Anchoring to the FIRST (not last) bash-using message keeps the indicator
+	* fixed in place for the whole turn: later bash steps don't reposition it, so
+	* the spinner never abruptly jumps mid-turn (bug 1). `CopilotChatMessageView`
+	* emits exactly one `IntelligenceIndicator` per entry, keyed by the turn id and
+	* positioned at the anchor; the per-turn key also lets every past turn keep its
+	* own indicator in scroll-back.
+	*/
+	function getIntelligenceTurnAnchors(messages) {
+		const anchors = /* @__PURE__ */ new Map();
+		let turnId = INTELLIGENCE_TURN_HEAD;
+		let anchorId = null;
+		const commit = () => {
+			if (anchorId !== null) anchors.set(anchorId, turnId);
+			anchorId = null;
+		};
+		for (const m of messages) {
+			if (m.role === "user") {
+				commit();
+				turnId = m.id;
+				continue;
+			}
+			if (anchorId === null && messageHasMatchingToolCall(m)) anchorId = m.id;
+		}
+		commit();
+		return anchors;
+	}
 	/**
 	* "Tool-call-like" messages do NOT count as a real follow-up: tool
 	* result messages, assistant messages that carry tool calls, and
@@ -5772,45 +6366,51 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		return false;
 	};
 	/**
-	* The "Using CopilotKit Intelligence" pill. Auto-mounted by
-	* `CopilotChatMessageView` for every message slot when
-	* `copilotkit.intelligence` is configured — callers do not register
-	* this themselves. Self-gates so only the canonical message renders a
-	* pill.
+	* The "Using CopilotKit Intelligence" indicator brain. Auto-mounted by
+	* `CopilotChatMessageView` — once per Intelligence-using turn, at that
+	* turn's anchor message and keyed by the turn id (see
+	* {@link getIntelligenceTurnAnchors}). Callers do not register this
+	* themselves. It owns the run subscription and the phase machine and
+	* renders its swappable face via the `intelligenceIndicator` slot.
+	*
+	* Placement (which message anchors the turn) is decided by the view, so
+	* this component does not self-gate its own placement; it only derives
+	* in-progress/finished for the turn it was mounted on.
 	*
 	* Render gates (all must hold):
 	*   1. `copilotkit.intelligence !== undefined`
-	*   2. The message is an assistant message with at least one tool call
-	*      whose name matches {@link DEFAULT_TOOL_PATTERNS}
-	*   3. The message is the *latest* such matching-assistant message in
-	*      `agent.messages` — tool-result messages and prose-only assistant
-	*      messages don't invalidate the slot, so the pill stays
-	*      continuously through a multi-step tool chain.
-	*   4. The phase machine is past `idle` (the pending-grace timer fired)
-	*      and not yet `hidden`.
+	*   2. The (anchor) message is an assistant message with at least one
+	*      tool call whose name matches {@link DEFAULT_TOOL_PATTERNS}.
+	*   3. The phase machine is past `hidden`.
+	*
+	* Because the view keys each indicator by its turn id, the instance moves
+	* with the anchor across a hand-off (no remount, no spinner restart), and
+	* every prior Intelligence-using turn keeps its own persistent indicator
+	* in chat history.
 	*
 	* Phase machine (per-instance, all timers local):
-	*   - Starts in `idle` — nothing rendered.
-	*   - `idle → spinner` once a matching tool call has been pending
+	*   - Starts in `hidden`, unless the message mounts onto an
+	*     already-completed turn (no pending work, agent stopped or a
+	*     real follow-up already present), in which case the lazy
+	*     `useState` initializer starts directly in `finished`. This is
+	*     what avoids a "hidden flash" on history replay.
+	*   - `hidden → spinner` once a matching tool call has been pending
 	*     (no `tool`-role result with a matching `toolCallId`) for
 	*     {@link PENDING_THRESHOLD_MS}. Replay flashes (tool call + result
 	*     in the same tick) never cross this threshold.
-	*   - `spinner → check` as soon as EITHER `agent.isRunning` flips
+	*   - `hidden → finished` if after the grace window the turn is
+	*     already complete (no pending work AND
+	*     `sawRealFollowup || !agent.isRunning`). Handles very fast tools
+	*     whose result lands within the grace window.
+	*   - `spinner → finished` as soon as EITHER `agent.isRunning` flips
 	*     false OR a non-tool-call-like message appears later in
-	*     `agent.messages` (i.e. the agent has produced a "real"
-	*     follow-up — prose answer or a new user turn).
-	*   - `check → fading` after {@link CHECK_HOLD_MS}.
-	*   - `fading → hidden` after {@link FADE_OUT_ANIMATION_MS}.
-	*
-	* Once `hidden`, the phase is sticky — a finished pill never re-spawns
-	* on the same message. New runs mount fresh indicator instances on
-	* their own assistant messages.
-	*
-	* The "exactly one pill at a time" guarantee is structural: only one
-	* message satisfies the latest-matching-assistant gate at any moment.
+	*     `agent.messages` (i.e. the agent produced a "real" follow-up —
+	*     prose answer or a new user turn).
+	*   - `finished` is terminal: the indicator settles into its
+	*     persistent tag form and stays mounted.
 	*/
 	function IntelligenceIndicator(props) {
-		const { message, agentId, label = "Using CopilotKit Intelligence" } = props;
+		const { message, agentId, label = "CopilotKit Intelligence", intelligenceIndicator } = props;
 		const { copilotkit } = useCopilotKit();
 		const config = useCopilotChatConfiguration();
 		const { agent } = useAgent({
@@ -5830,84 +6430,37 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			for (const m of agent.messages) if (m.role === "tool" && m.toolCallId) resolved.add(m.toolCallId);
 			return matchingToolCallIds.some((id) => !resolved.has(id));
 		}, [matchingToolCallIds, agent.messages]);
-		const sawRealFollowup = (0, react.useMemo)(() => {
+		const turnComplete = (0, react.useMemo)(() => {
 			const idx = agent.messages.findIndex((m) => m.id === message.id);
 			if (idx < 0) return false;
 			for (let i = idx + 1; i < agent.messages.length; i += 1) if (!isToolCallLikeMessage(agent.messages[i])) return true;
 			return false;
-		}, [agent.messages, message.id]);
-		const [phase, setPhase] = (0, react.useState)("idle");
+		}, [agent.messages, message.id]) || !agent.isRunning;
+		const [phase, setPhase] = (0, react.useState)(() => initialIndicatorPhase(turnComplete));
 		(0, react.useEffect)(() => {
-			if (phase !== "idle") return void 0;
-			if (!hasPending) return void 0;
-			const t = setTimeout(() => setPhase("spinner"), PENDING_THRESHOLD_MS);
+			if (phase !== "hidden") return void 0;
+			const t = setTimeout(() => {
+				setPhase(resolveGracePhase(turnComplete, hasPending));
+			}, PENDING_THRESHOLD_MS);
 			return () => clearTimeout(t);
-		}, [phase, hasPending]);
-		(0, react.useEffect)(() => {
-			if (phase !== "spinner") return void 0;
-			if (!agent.isRunning || sawRealFollowup) setPhase("check");
 		}, [
 			phase,
-			agent.isRunning,
-			sawRealFollowup
+			hasPending,
+			turnComplete
 		]);
 		(0, react.useEffect)(() => {
-			if (phase !== "check") return void 0;
-			const t = setTimeout(() => setPhase("fading"), CHECK_HOLD_MS);
-			return () => clearTimeout(t);
-		}, [phase]);
-		(0, react.useEffect)(() => {
-			if (phase !== "fading") return void 0;
-			const t = setTimeout(() => setPhase("hidden"), FADE_OUT_ANIMATION_MS);
-			return () => clearTimeout(t);
-		}, [phase]);
+			if (phase !== "spinner") return void 0;
+			if (turnComplete) setPhase("finished");
+		}, [phase, turnComplete]);
 		if (copilotkit.intelligence === void 0) return null;
 		if (!config) return null;
-		if (phase === "idle" || phase === "hidden") return null;
+		if (phase === "hidden") return null;
 		if (message.role !== "assistant") return null;
-		if (!(Array.isArray(message.toolCalls) ? message.toolCalls : []).some((tc) => isMatchingToolCallName(tc?.function?.name))) return null;
-		let latestMatchingAssistantId;
-		for (let i = agent.messages.length - 1; i >= 0; i -= 1) {
-			const m = agent.messages[i];
-			if (m.role !== "assistant") continue;
-			if ((Array.isArray(m.toolCalls) ? m.toolCalls : []).some((tc) => isMatchingToolCallName(tc?.function?.name))) {
-				latestMatchingAssistantId = m.id;
-				break;
-			}
-		}
-		if (latestMatchingAssistantId !== message.id) return null;
-		const showSpinner = phase === "spinner";
-		const isFading = phase === "fading";
-		return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
-			className: "cpk-intelligence-pill" + (isFading ? " cpk-intelligence-pill--fading" : ""),
-			role: "status",
-			"aria-live": "polite",
-			"aria-hidden": isFading || void 0,
-			"data-testid": `cpk-intelligence-pill-${message.id}`,
-			title: label,
-			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("svg", {
-				className: "cpk-intelligence-pill__icon",
-				viewBox: "0 0 24 24",
-				width: "14",
-				height: "14",
-				"aria-hidden": "true",
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("circle", {
-					cx: "12",
-					cy: "12",
-					r: "9",
-					fill: "none",
-					strokeWidth: "2.5",
-					strokeLinecap: "round",
-					className: "cpk-intelligence-pill__ring" + (showSpinner ? "" : " cpk-intelligence-pill__ring--done")
-				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", {
-					d: "M8 12.5l3 3 5-6",
-					fill: "none",
-					strokeWidth: "2.5",
-					strokeLinecap: "round",
-					strokeLinejoin: "round",
-					className: "cpk-intelligence-pill__check" + (showSpinner ? "" : " cpk-intelligence-pill__check--shown")
-				})]
-			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: label })]
+		if (!messageHasMatchingToolCall(message)) return null;
+		return renderSlot(intelligenceIndicator, IntelligenceIndicatorView, {
+			message,
+			status: phase === "finished" ? "finished" : "in-progress",
+			label
 		});
 	}
 
@@ -6060,7 +6613,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		return [...acc.values()];
 	}
 	const VIRTUALIZE_THRESHOLD = 50;
-	function CopilotChatMessageView({ messages = [], assistantMessage, userMessage, reasoningMessage, cursor, isRunning = false, children, className, ...props }) {
+	function CopilotChatMessageView({ messages = [], assistantMessage, userMessage, reasoningMessage, cursor, intelligenceIndicator, isRunning = false, children, className, ...props }) {
 		const renderCustomMessage = useRenderCustomMessages();
 		const { renderActivityMessage } = useRenderActivityMessage();
 		const { copilotkit } = useCopilotKit();
@@ -6118,6 +6671,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			if (!shouldVirtualize || !deduplicatedMessages.length) return;
 			virtualizer.scrollToIndex(deduplicatedMessages.length - 1, { align: "end" });
 		}, [shouldVirtualize, firstMessageId]);
+		const intelligenceTurnAnchors = (0, react.useMemo)(() => getIntelligenceTurnAnchors(deduplicatedMessages), [deduplicatedMessages]);
 		const renderMessageBlock = (message) => {
 			const elements = [];
 			const stateSnapshot = getStateSnapshotForMessage(message.id);
@@ -6156,10 +6710,12 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 				renderCustomMessage,
 				stateSnapshot
 			}, `${message.id}-custom-after`));
-			if (copilotkit.intelligence !== void 0 && message.role === "assistant") elements.push(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(IntelligenceIndicator, {
+			const intelligenceTurnId = intelligenceTurnAnchors.get(message.id);
+			if (intelligenceTurnId !== void 0) elements.push(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(IntelligenceIndicator, {
 				message,
-				agentId: config?.agentId ?? _copilotkit_shared.DEFAULT_AGENT_ID
-			}, `${message.id}-intelligence`));
+				agentId: config?.agentId ?? _copilotkit_shared.DEFAULT_AGENT_ID,
+				intelligenceIndicator
+			}, `intelligence-${intelligenceTurnId}`));
 			return elements.filter(Boolean);
 		};
 		const messageElements = shouldVirtualize ? [] : deduplicatedMessages.flatMap(renderMessageBlock);
@@ -6596,7 +7152,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			})
 		});
 	}
-	function CopilotChatView({ messageView, input, scrollView, suggestionView, welcomeScreen, messages = [], autoScroll = true, isRunning = false, suggestions, suggestionLoadingIndexes, onSelectSuggestion, onSubmitMessage, onStop, inputMode, inputValue, onInputChange, onStartTranscribe, onCancelTranscribe, onFinishTranscribe, onFinishTranscribeWithAudio, attachments, onRemoveAttachment, onAddFile, dragOver, onDragOver, onDragLeave, onDrop, isConnecting = false, hasExplicitThreadId = false, disclaimer, children, className, ...props }) {
+	function CopilotChatView({ messageView, input, scrollView, suggestionView, welcomeScreen, messages = [], autoScroll = true, isRunning = false, suggestions, suggestionLoadingIndexes, onSelectSuggestion, onSubmitMessage, onStop, inputMode, inputValue, onInputChange, onStartTranscribe, onCancelTranscribe, onFinishTranscribe, onFinishTranscribeWithAudio, attachments, onRemoveAttachment, onAddFile, dragOver, onDragOver, onDragLeave, onDrop, isConnecting = false, hasExplicitThreadId = false, disclaimer, intelligenceIndicator, children, className, ...props }) {
 		const [inputContainerEl, setInputContainerEl] = (0, react.useState)(null);
 		const [inputContainerHeight, setInputContainerHeight] = (0, react.useState)(0);
 		const [isResizing, setIsResizing] = (0, react.useState)(false);
@@ -6633,7 +7189,8 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		}, [inputContainerEl]);
 		const BoundMessageView = renderSlot(messageView, CopilotChatMessageView, {
 			messages,
-			isRunning
+			isRunning,
+			intelligenceIndicator
 		});
 		const BoundInput = renderSlot(input, CopilotChatInput_default, {
 			onSubmitMessage,
@@ -7178,6 +7735,13 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			resolvedAgentId,
 			hasExplicitThreadId
 		]);
+		const waitForActiveRunToSettle = (0, react.useCallback)(async () => {
+			if (agent.isRunning && (0, _copilotkit_core.isRunCompletionAware)(agent) && agent.activeRunCompletionPromise) try {
+				await agent.activeRunCompletionPromise;
+			} catch (error) {
+				console.error("CopilotChat: in-flight run rejected while queuing send", error);
+			}
+		}, [agent]);
 		const onSubmitInput = (0, react.useCallback)(async (value) => {
 			if (selectedAttachmentsRef.current.some((a) => a.status === "uploading")) {
 				console.error("[CopilotKit] Cannot send while attachments are uploading (pre-await guard)");
@@ -7185,11 +7749,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 				return;
 			}
 			setInputValue("");
-			if (agent.isRunning && "activeRunCompletionPromise" in agent && agent.activeRunCompletionPromise) try {
-				await agent.activeRunCompletionPromise;
-			} catch (error) {
-				console.error("CopilotChat: in-flight run rejected while queuing send", error);
-			}
+			await waitForActiveRunToSettle();
 			if (selectedAttachmentsRef.current.some((a) => a.status === "uploading")) {
 				console.error("[CopilotKit] Cannot send while attachments are uploading (post-await re-check)");
 				setTranscriptionError("Cannot send while attachments are uploading.");
@@ -7226,8 +7786,13 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			} catch (error) {
 				console.error("CopilotChat: runAgent failed", error);
 			}
-		}, [agent, consumeAttachments]);
+		}, [
+			agent,
+			consumeAttachments,
+			waitForActiveRunToSettle
+		]);
 		const handleSelectSuggestion = (0, react.useCallback)(async (suggestion) => {
+			await waitForActiveRunToSettle();
 			agent.addMessage({
 				id: (0, _copilotkit_shared.randomUUID)(),
 				role: "user",
@@ -7238,7 +7803,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			} catch (error) {
 				console.error("CopilotChat: runAgent failed after selecting suggestion", error);
 			}
-		}, [agent]);
+		}, [agent, waitForActiveRunToSettle]);
 		const stopCurrentRun = (0, react.useCallback)(() => {
 			try {
 				copilotkit.stopAgent({ agent });
@@ -10047,7 +10612,9 @@ Object.defineProperty(exports, 'CopilotSidebarView', {
     return CopilotSidebarView;
   }
 });
+exports.INTELLIGENCE_TURN_HEAD = INTELLIGENCE_TURN_HEAD;
 exports.IntelligenceIndicator = IntelligenceIndicator;
+exports.IntelligenceIndicatorView = IntelligenceIndicatorView;
 exports.MCPAppsActivityContentSchema = MCPAppsActivityContentSchema;
 exports.MCPAppsActivityRenderer = MCPAppsActivityRenderer;
 exports.MCPAppsActivityType = MCPAppsActivityType;
@@ -10062,6 +10629,7 @@ Object.defineProperty(exports, 'a2uiDefaultTheme', {
 });
 exports.createA2UIMessageRenderer = createA2UIMessageRenderer;
 exports.defineToolCallRenderer = defineToolCallRenderer;
+exports.getIntelligenceTurnAnchors = getIntelligenceTurnAnchors;
 exports.useAgent = useAgent;
 exports.useAgentContext = useAgentContext;
 exports.useAttachments = useAttachments;
@@ -10074,6 +10642,10 @@ exports.useDefaultRenderTool = useDefaultRenderTool;
 exports.useFrontendTool = useFrontendTool;
 exports.useHumanInTheLoop = useHumanInTheLoop;
 exports.useInterrupt = useInterrupt;
+exports.useLearnFromUserAction = useLearnFromUserAction;
+exports.useLearnFromUserActionInCurrentThread = useLearnFromUserActionInCurrentThread;
+exports.useLearningContainers = useLearningContainers;
+exports.useLearningContainersInCurrentThread = useLearningContainersInCurrentThread;
 exports.useRenderActivityMessage = useRenderActivityMessage;
 exports.useRenderCustomMessages = useRenderCustomMessages;
 exports.useRenderTool = useRenderTool;