@copilotkit/react-core 1.59.3 → 1.59.5

package/dist/{copilotkit-BRNy5UvX.mjs → copilotkit-DEGlMWM0.mjs}

@@ -1,6 +1,6 @@
 import * as React$1 from "react";
 import React, { createContext, forwardRef, memo, useCallback, useContext, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore } from "react";
-import { CopilotKitCore, CopilotKitCoreRuntimeConnectionStatus, ProxiedCopilotRuntimeAgent, ToolCallStatus, ɵcreateThreadStore, ɵselectHasNextPage, ɵselectIsFetchingNextPage, ɵselectThreads, ɵselectThreadsError, ɵselectThreadsIsLoading } from "@copilotkit/core";
+import { CopilotKitCore, CopilotKitCoreRuntimeConnectionStatus, ProxiedCopilotRuntimeAgent, ToolCallStatus, isRunCompletionAware, ɵcreateThreadStore, ɵselectHasNextPage, ɵselectIsFetchingNextPage, ɵselectThreads, ɵselectThreadsError, ɵselectThreadsIsLoading } from "@copilotkit/core";
 import { HttpAgent } from "@ag-ui/client";
 import { extendTailwindMerge, twMerge } from "tailwind-merge";
 import { ArrowUp, Check, ChevronDown, ChevronLeft, ChevronRight, ChevronRightIcon, Copy, Edit, Loader2, MessageCircle, Mic, Play, Plus, RefreshCw, Square, ThumbsDown, ThumbsUp, Upload, Volume2, X } from "lucide-react";
@@ -2924,210 +2924,110 @@ const OpenGenerativeUIToolRenderer = function OpenGenerativeUIToolRenderer(props
 };
 
 //#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;
-	}
-}
-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))
-			});
-		}
-	};
-}
+//#region src/v2/a2ui/A2UIRecoveryStates.tsx
 /**
-* 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__ */ 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"
+	});
+}
+/**
+* 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
 /**
-* Registers the built-in `render_a2ui` tool call renderer via the props-based
-* `setRenderToolCalls` mechanism (not `useRenderTool`).
+* 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();
@@ -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;
 	}, [
@@ -4781,6 +4918,175 @@ function useThreads$1({ agentId, includeArchived, limit }) {
 	};
 }
 
+//#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 ?? 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 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 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
 /**
@@ -4939,6 +5245,153 @@ function useAttachments({ config }) {
 	};
 }
 
+//#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 = useRef(null);
+	/** Guards the missing-runtimeUrl warning so it fires at most once per hook instance. */
+	const warnedMissingUrlRef = useRef(false);
+	const runtimeUrlRef = useRef(copilotkit.runtimeUrl);
+	const headersRef = useRef(copilotkit.headers ?? {});
+	runtimeUrlRef.current = copilotkit.runtimeUrl;
+	headersRef.current = copilotkit.headers ?? {};
+	const key = JSON.stringify(learningContainers);
+	const defaultKey = JSON.stringify(DEFAULT_CONTAINERS);
+	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]);
+	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 = [] }) {
@@ -5711,33 +6164,174 @@ CopilotChatSuggestionView.displayName = "CopilotChatSuggestionView";
 */
 const ScrollElementContext = React.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__ */ jsxs("span", {
+		className: 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__ */ jsx("span", {
+			className: "cpk-intelligence-indicator__chrome",
+			"aria-hidden": "true"
+		}), /* @__PURE__ */ jsxs("span", {
+			className: "cpk-intelligence-indicator__content",
+			children: [/* @__PURE__ */ jsx("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" })
+			}), /* @__PURE__ */ 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
@@ -5756,45 +6350,51 @@ const isToolCallLikeMessage = (m) => {
 	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({
@@ -5814,84 +6414,37 @@ function IntelligenceIndicator(props) {
 		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 = useMemo(() => {
+	const turnComplete = 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] = useState("idle");
+	}, [agent.messages, message.id]) || !agent.isRunning;
+	const [phase, setPhase] = useState(() => initialIndicatorPhase(turnComplete));
 	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]);
-	useEffect(() => {
-		if (phase !== "spinner") return void 0;
-		if (!agent.isRunning || sawRealFollowup) setPhase("check");
 	}, [
 		phase,
-		agent.isRunning,
-		sawRealFollowup
+		hasPending,
+		turnComplete
 	]);
 	useEffect(() => {
-		if (phase !== "check") return void 0;
-		const t = setTimeout(() => setPhase("fading"), CHECK_HOLD_MS);
-		return () => clearTimeout(t);
-	}, [phase]);
-	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__ */ 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__ */ jsxs("svg", {
-			className: "cpk-intelligence-pill__icon",
-			viewBox: "0 0 24 24",
-			width: "14",
-			height: "14",
-			"aria-hidden": "true",
-			children: [/* @__PURE__ */ 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__ */ 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__ */ jsx("span", { children: label })]
+	if (!messageHasMatchingToolCall(message)) return null;
+	return renderSlot(intelligenceIndicator, IntelligenceIndicatorView, {
+		message,
+		status: phase === "finished" ? "finished" : "in-progress",
+		label
 	});
 }
 
@@ -6044,7 +6597,7 @@ function deduplicateMessages(messages) {
 	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();
@@ -6102,6 +6655,7 @@ function CopilotChatMessageView({ messages = [], assistantMessage, userMessage,
 		if (!shouldVirtualize || !deduplicatedMessages.length) return;
 		virtualizer.scrollToIndex(deduplicatedMessages.length - 1, { align: "end" });
 	}, [shouldVirtualize, firstMessageId]);
+	const intelligenceTurnAnchors = useMemo(() => getIntelligenceTurnAnchors(deduplicatedMessages), [deduplicatedMessages]);
 	const renderMessageBlock = (message) => {
 		const elements = [];
 		const stateSnapshot = getStateSnapshotForMessage(message.id);
@@ -6140,10 +6694,12 @@ function CopilotChatMessageView({ messages = [], assistantMessage, userMessage,
 			renderCustomMessage,
 			stateSnapshot
 		}, `${message.id}-custom-after`));
-		if (copilotkit.intelligence !== void 0 && message.role === "assistant") elements.push(/* @__PURE__ */ jsx(IntelligenceIndicator, {
+		const intelligenceTurnId = intelligenceTurnAnchors.get(message.id);
+		if (intelligenceTurnId !== void 0) elements.push(/* @__PURE__ */ jsx(IntelligenceIndicator, {
 			message,
-			agentId: config?.agentId ?? DEFAULT_AGENT_ID
-		}, `${message.id}-intelligence`));
+			agentId: config?.agentId ?? DEFAULT_AGENT_ID,
+			intelligenceIndicator
+		}, `intelligence-${intelligenceTurnId}`));
 		return elements.filter(Boolean);
 	};
 	const messageElements = shouldVirtualize ? [] : deduplicatedMessages.flatMap(renderMessageBlock);
@@ -6580,7 +7136,7 @@ function DropOverlay() {
 		})
 	});
 }
-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] = useState(null);
 	const [inputContainerHeight, setInputContainerHeight] = useState(0);
 	const [isResizing, setIsResizing] = useState(false);
@@ -6617,7 +7173,8 @@ function CopilotChatView({ messageView, input, scrollView, suggestionView, welco
 	}, [inputContainerEl]);
 	const BoundMessageView = renderSlot(messageView, CopilotChatMessageView, {
 		messages,
-		isRunning
+		isRunning,
+		intelligenceIndicator
 	});
 	const BoundInput = renderSlot(input, CopilotChatInput_default, {
 		onSubmitMessage,
@@ -7162,6 +7719,13 @@ function CopilotChat({ agentId, threadId, labels, chatView, isModalDefaultOpen,
 		resolvedAgentId,
 		hasExplicitThreadId
 	]);
+	const waitForActiveRunToSettle = useCallback(async () => {
+		if (agent.isRunning && isRunCompletionAware(agent) && agent.activeRunCompletionPromise) try {
+			await agent.activeRunCompletionPromise;
+		} catch (error) {
+			console.error("CopilotChat: in-flight run rejected while queuing send", error);
+		}
+	}, [agent]);
 	const onSubmitInput = useCallback(async (value) => {
 		if (selectedAttachmentsRef.current.some((a) => a.status === "uploading")) {
 			console.error("[CopilotKit] Cannot send while attachments are uploading (pre-await guard)");
@@ -7169,11 +7733,7 @@ function CopilotChat({ agentId, threadId, labels, chatView, isModalDefaultOpen,
 			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.");
@@ -7210,8 +7770,13 @@ function CopilotChat({ agentId, threadId, labels, chatView, isModalDefaultOpen,
 		} catch (error) {
 			console.error("CopilotChat: runAgent failed", error);
 		}
-	}, [agent, consumeAttachments]);
+	}, [
+		agent,
+		consumeAttachments,
+		waitForActiveRunToSettle
+	]);
 	const handleSelectSuggestion = useCallback(async (suggestion) => {
+		await waitForActiveRunToSettle();
 		agent.addMessage({
 			id: randomUUID(),
 			role: "user",
@@ -7222,7 +7787,7 @@ function CopilotChat({ agentId, threadId, labels, chatView, isModalDefaultOpen,
 		} catch (error) {
 			console.error("CopilotChat: runAgent failed after selecting suggestion", error);
 		}
-	}, [agent]);
+	}, [agent, waitForActiveRunToSettle]);
 	const stopCurrentRun = useCallback(() => {
 		try {
 			copilotkit.stopAgent({ agent });
@@ -10098,5 +10663,5 @@ function validateProps(props) {
 }
 
 //#endregion
-export { createA2UIMessageRenderer as $, IntelligenceIndicator as A, useInterrupt as B, CopilotChatToggleButton as C, CopilotChatView_default as D, CopilotChat as E, CopilotChatAttachmentRenderer as F, useAgent as G, useSuggestions as H, CopilotChatAssistantMessage_default as I, useFrontendTool as J, useHumanInTheLoop as K, CopilotChatToolCallsView as L, CopilotChatSuggestionPill as M, CopilotChatReasoningMessage_default as N, CopilotChatAttachmentQueue as O, CopilotChatUserMessage_default as P, useAgentContext as Q, useAttachments as R, CopilotModalHeader as S, DefaultOpenIcon as T, useCapabilities as U, useConfigureSuggestions as V, UseAgentUpdate as W, useRenderCustomMessages as X, useRenderActivityMessage as Y, CopilotKitProvider as Z, WildcardToolCallRender as _, ThreadsProvider as a, CopilotKitInspector as at, CopilotPopupView as b, CoAgentStateRendersProvider as c, useRenderTool as ct, shouldShowDevConsole as d, CopilotKitCoreReact as dt, SandboxFunctionsContext as et, useToast as f, CopilotChatInput_default as ft, useCopilotContext as g, useCopilotChatConfiguration as gt, CopilotContext as h, CopilotChatConfigurationProvider as ht, ThreadsContext as i, MCPAppsActivityType as it, CopilotChatSuggestionView as j, CopilotChatMessageView as k, useCoAgentStateRenders as l, defineToolCallRenderer as lt, useCopilotMessagesContext as m, CopilotChatAudioRecorder as mt, defaultCopilotContextCategories as n, MCPAppsActivityContentSchema as nt, useThreads as o, useRenderToolCall as ot, CopilotMessagesContext as p, AudioRecorderError as pt, useComponent as q, CoAgentStateRenderBridge as r, MCPAppsActivityRenderer as rt, CoAgentStateRendersContext as s, useDefaultRenderTool as st, CopilotKit as t, useSandboxFunctions as tt, useAsyncCallback as u, useCopilotKit as ut, CopilotPopup as v, DefaultCloseIcon as w, CopilotSidebarView as x, CopilotSidebar as y, useThreads$1 as z };
-//# sourceMappingURL=copilotkit-BRNy5UvX.mjs.map
+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-DEGlMWM0.mjs.map