@copilotkit/react-core 1.61.0 → 1.61.2

package/dist/v2/headless.mjs

@@ -3,7 +3,7 @@ import React, { createContext, useCallback, useContext, useEffect, useLayoutEffe
 import { DEFAULT_AGENT_ID, randomUUID } from "@copilotkit/shared";
 import { twMerge } from "tailwind-merge";
 import { jsx } from "react/jsx-runtime";
-import { HttpAgent } from "@ag-ui/client";
+import { HttpAgent, buildResumeArray, isInterruptExpired, randomUUID as randomUUID$1 } from "@ag-ui/client";
 import { CopilotKitCoreRuntimeConnectionStatus, ProxiedCopilotRuntimeAgent, ToolCallStatus, ɵcreateThreadStore, ɵselectHasNextPage, ɵselectIsFetchingNextPage, ɵselectThreads, ɵselectThreadsError, ɵselectThreadsIsLoading } from "@copilotkit/core";
 import { z } from "zod";
 
@@ -204,7 +204,7 @@ function useAgent({ agentId, updates, throttleMs } = {}) {
 		if (isRuntimeConfigured && (status === CopilotKitCoreRuntimeConnectionStatus.Disconnected || status === CopilotKitCoreRuntimeConnectionStatus.Connecting)) {
 			const cached = provisionalAgentCache.current.get(agentId);
 			if (cached) {
-				cached.headers = { ...copilotkit.headers };
+				copilotkit.applyHeadersToAgent(cached);
 				return cached;
 			}
 			const provisional = new ProxiedCopilotRuntimeAgent({
@@ -213,14 +213,14 @@ function useAgent({ agentId, updates, throttleMs } = {}) {
 				transport: copilotkit.runtimeTransport,
 				runtimeMode: "pending"
 			});
-			provisional.headers = { ...copilotkit.headers };
+			copilotkit.applyHeadersToAgent(provisional);
 			provisionalAgentCache.current.set(agentId, provisional);
 			return provisional;
 		}
 		if (isRuntimeConfigured && status === CopilotKitCoreRuntimeConnectionStatus.Error) {
 			const cached = provisionalAgentCache.current.get(agentId);
 			if (cached) {
-				cached.headers = { ...copilotkit.headers };
+				copilotkit.applyHeadersToAgent(cached);
 				return cached;
 			}
 			const provisional = new ProxiedCopilotRuntimeAgent({
@@ -229,7 +229,7 @@ function useAgent({ agentId, updates, throttleMs } = {}) {
 				transport: copilotkit.runtimeTransport,
 				runtimeMode: "pending"
 			});
-			provisional.headers = { ...copilotkit.headers };
+			copilotkit.applyHeadersToAgent(provisional);
 			provisionalAgentCache.current.set(agentId, provisional);
 			return provisional;
 		}
@@ -280,7 +280,7 @@ function useAgent({ agentId, updates, throttleMs } = {}) {
 		updateFlags
 	]);
 	useEffect(() => {
-		if (agent instanceof HttpAgent) agent.headers = { ...copilotkit.headers };
+		if (agent instanceof HttpAgent) copilotkit.applyHeadersToAgent(agent);
 	}, [agent, JSON.stringify(copilotkit.headers)]);
 	const chatConfig = useCopilotChatConfiguration();
 	const configThreadId = chatConfig?.threadId;
@@ -402,15 +402,34 @@ function useComponent(config, deps) {
 function useHumanInTheLoop(tool, deps) {
 	const { copilotkit } = useCopilotKit();
 	const resolvePromiseRef = useRef(null);
+	const cleanupAbortRef = useRef(null);
 	const respond = useCallback(async (result) => {
 		if (resolvePromiseRef.current) {
+			cleanupAbortRef.current?.();
+			cleanupAbortRef.current = null;
 			resolvePromiseRef.current(result);
 			resolvePromiseRef.current = null;
 		}
 	}, []);
-	const handler = useCallback(async () => {
-		return new Promise((resolve) => {
+	const handler = useCallback(async (_args, context) => {
+		const signal = context?.signal;
+		return new Promise((resolve, reject) => {
+			if (signal?.aborted) {
+				reject(/* @__PURE__ */ new Error("Human-in-the-loop interaction aborted"));
+				return;
+			}
 			resolvePromiseRef.current = resolve;
+			if (signal) {
+				const onAbort = () => {
+					cleanupAbortRef.current = null;
+					resolvePromiseRef.current = null;
+					reject(/* @__PURE__ */ new Error("Human-in-the-loop interaction aborted"));
+				};
+				signal.addEventListener("abort", onAbort, { once: true });
+				cleanupAbortRef.current = () => {
+					signal.removeEventListener("abort", onAbort);
+				};
+			}
 		});
 	}, []);
 	const RenderComponent = useCallback((props) => {
@@ -473,114 +492,165 @@ const INTERRUPT_EVENT_NAME = "on_interrupt";
 function isPromiseLike(value) {
 	return (typeof value === "object" || typeof value === "function") && value !== null && typeof Reflect.get(value, "then") === "function";
 }
+/** Derive the legacy-compatible `event` for any pending interrupt. */
+function toLegacyEvent(pending) {
+	if (pending.kind === "legacy") return pending.event;
+	return {
+		name: INTERRUPT_EVENT_NAME,
+		value: pending.interrupts[0]
+	};
+}
 /**
-* Handles agent interrupts (`on_interrupt`) with optional filtering, preprocessing, and resume behavior.
-*
-* The hook listens to custom events on the active agent, stores interrupt payloads per run,
-* and surfaces a render callback once the run finalizes. Call `resolve` from your UI to resume
-* execution with user-provided data.
+* Handles agent interrupts with optional filtering, preprocessing, and resume behavior.
 *
-* - `renderInChat: true` (default): the element is published into `<CopilotChat>` and this hook returns `void`.
-* - `renderInChat: false`: the hook returns the interrupt element so you can place it anywhere in your component tree.
-*
-* `event.value` is typed as `any` since the interrupt payload shape depends on your agent.
-* Type-narrow it in your callbacks (e.g. `handler`, `enabled`, `render`) as needed.
-*
-* @typeParam TResult - Inferred from `handler` return type. Exposed as `result` in `render`.
-* @param config - Interrupt configuration (renderer, optional handler/filter, and render mode).
-* @returns When `renderInChat` is `false`, returns the interrupt element (or `null` when idle).
-* Otherwise returns `void` and publishes the element into chat. In `render`, `result` is always
-* either the handler's resolved return value or `null` (including when no handler is provided,
-* when filtering skips the interrupt, or when handler execution fails).
-*
-* @example
-* ```tsx
-* import { useInterrupt } from "@copilotkit/react-core/v2";
-*
-* function InterruptUI() {
-*   useInterrupt({
-*     render: ({ event, resolve }) => (
-*       <div>
-*         <p>{event.value.question}</p>
-*         <button onClick={() => resolve({ approved: true })}>Approve</button>
-*         <button onClick={() => resolve({ approved: false })}>Reject</button>
-*       </div>
-*     ),
-*   });
+* Supports both the AG-UI standard interrupt flow (`RUN_FINISHED` with
+* `outcome.type === "interrupt"`) and the legacy custom-event flow
+* (`on_interrupt`). For standard interrupts, `render` receives `interrupt`
+* (the primary one) and `interrupts` (the full open set); call `resolve(payload)`
+* to resume or `cancel()` to cancel. Resuming addresses the targeted interrupt
+* and, once every open interrupt is addressed, submits a single spec `resume`
+* array via `copilotkit.runAgent`.
 *
-*   return null;
-* }
-* ```
+* - `renderInChat: true` (default): the element is published into `<CopilotChat>`; returns `void`.
+* - `renderInChat: false`: the hook returns the interrupt element for manual placement.
 *
 * @example
 * ```tsx
-* import { useInterrupt } from "@copilotkit/react-core/v2";
-*
-* function CustomPanel() {
-*   const interruptElement = useInterrupt({
-*     renderInChat: false,
-*     enabled: (event) => event.value.startsWith("approval:"),
-*     handler: async ({ event }) => ({ label: event.value.toUpperCase() }),
-*     render: ({ event, result, resolve }) => (
-*       <aside>
-*         <strong>{result?.label ?? ""}</strong>
-*         <button onClick={() => resolve({ value: event.value })}>Continue</button>
-*       </aside>
-*     ),
-*   });
-*
-*   return <>{interruptElement}</>;
-* }
+* useInterrupt({
+*   render: ({ interrupt, resolve, cancel }) => (
+*     <div>
+*       <p>{interrupt?.message}</p>
+*       <button onClick={() => resolve({ approved: true })}>Approve</button>
+*       <button onClick={() => cancel()}>Cancel</button>
+*     </div>
+*   ),
+* });
 * ```
 */
 function useInterrupt(config) {
 	const { copilotkit } = useCopilotKit();
 	const { agent } = useAgent({ agentId: config.agentId });
-	const [pendingEvent, setPendingEvent] = useState(null);
-	const pendingEventRef = useRef(pendingEvent);
-	pendingEventRef.current = pendingEvent;
+	const [pending, setPending] = useState(null);
+	const pendingRef = useRef(pending);
+	pendingRef.current = pending;
 	const [handlerResult, setHandlerResult] = useState(null);
+	const responsesRef = useRef({});
 	useEffect(() => {
-		let localInterrupt = null;
+		let localLegacy = null;
+		let localStandard = null;
 		const subscription = agent.subscribe({
 			onCustomEvent: ({ event }) => {
-				if (event.name === INTERRUPT_EVENT_NAME) localInterrupt = {
+				if (event.name === INTERRUPT_EVENT_NAME) localLegacy = {
 					name: event.name,
 					value: event.value
 				};
 			},
+			onRunFinishedEvent: (params) => {
+				if (params.outcome === "interrupt") localStandard = params.interrupts;
+			},
 			onRunStartedEvent: () => {
-				localInterrupt = null;
-				setPendingEvent(null);
+				localLegacy = null;
+				localStandard = null;
+				responsesRef.current = {};
+				setPending(null);
 			},
 			onRunFinalized: () => {
-				if (localInterrupt) {
-					setPendingEvent(localInterrupt);
-					localInterrupt = null;
-				}
+				if (localStandard && localStandard.length > 0) setPending({
+					kind: "standard",
+					interrupts: localStandard
+				});
+				else if (localLegacy) setPending({
+					kind: "legacy",
+					event: localLegacy
+				});
+				localLegacy = null;
+				localStandard = null;
 			},
 			onRunFailed: () => {
-				localInterrupt = null;
-				setPendingEvent(null);
+				localLegacy = null;
+				localStandard = null;
+				responsesRef.current = {};
+				setPending(null);
 			}
 		});
 		return () => subscription.unsubscribe();
 	}, [agent]);
-	const resolve = useCallback(async (response) => {
+	const submitStandardIfComplete = useCallback(async (interrupts) => {
+		if (!interrupts.every((i) => responsesRef.current[i.id])) return;
+		const expired = interrupts.find((i) => isInterruptExpired(i));
+		if (expired) {
+			console.error(`[CopilotKit] useInterrupt: interrupt ${expired.id} expired at ${expired.expiresAt}; not resuming.`);
+			responsesRef.current = {};
+			setPending(null);
+			return;
+		}
+		const resume = buildResumeArray(interrupts, responsesRef.current);
+		for (const i of interrupts) {
+			if (!i.toolCallId) continue;
+			const response = responsesRef.current[i.id];
+			const content = response.status === "cancelled" ? { status: "cancelled" } : response.payload ?? { status: "resolved" };
+			agent.addMessage({
+				id: randomUUID$1(),
+				role: "tool",
+				toolCallId: i.toolCallId,
+				content: JSON.stringify(content)
+			});
+		}
+		responsesRef.current = {};
 		try {
+			return await copilotkit.runAgent({
+				agent,
+				resume
+			});
+		} catch (err) {
+			console.error("[CopilotKit] useInterrupt resolve: runAgent rejected; clearing pending + rethrowing", err);
+			setPending(null);
+			throw err;
+		}
+	}, [agent, copilotkit]);
+	const resolve = useCallback(async (payload, interruptId) => {
+		const current = pendingRef.current;
+		if (!current) return;
+		if (current.kind === "legacy") try {
 			return await copilotkit.runAgent({
 				agent,
 				forwardedProps: { command: {
-					resume: response,
-					interruptEvent: pendingEventRef.current?.value
+					resume: payload,
+					interruptEvent: current.event.value
 				} }
 			});
 		} catch (err) {
 			console.error("[CopilotKit] useInterrupt resolve: runAgent rejected; clearing pending + rethrowing", err);
-			setPendingEvent(null);
+			setPending(null);
 			throw err;
 		}
-	}, [agent, copilotkit]);
+		if (current.interrupts.length > 1 && interruptId === void 0) console.warn(`[CopilotKit] useInterrupt: resolve()/cancel() called without an interruptId while ${current.interrupts.length} interrupts are open; defaulting to the first. Pass an interruptId to address a specific interrupt.`);
+		const id = interruptId ?? current.interrupts[0]?.id;
+		if (!id) return;
+		responsesRef.current[id] = {
+			status: "resolved",
+			payload
+		};
+		return submitStandardIfComplete(current.interrupts);
+	}, [
+		agent,
+		copilotkit,
+		submitStandardIfComplete
+	]);
+	const cancel = useCallback(async (interruptId) => {
+		const current = pendingRef.current;
+		if (!current) return;
+		if (current.kind === "legacy") {
+			console.warn("[CopilotKit] useInterrupt: cancel() is not supported for legacy on_interrupt interrupts; dismissing.");
+			setPending(null);
+			return;
+		}
+		if (current.interrupts.length > 1 && interruptId === void 0) console.warn(`[CopilotKit] useInterrupt: resolve()/cancel() called without an interruptId while ${current.interrupts.length} interrupts are open; defaulting to the first. Pass an interruptId to address a specific interrupt.`);
+		const id = interruptId ?? current.interrupts[0]?.id;
+		if (!id) return;
+		responsesRef.current[id] = { status: "cancelled" };
+		return submitStandardIfComplete(current.interrupts);
+	}, [submitStandardIfComplete]);
 	const renderRef = useRef(config.render);
 	renderRef.current = config.render;
 	const enabledRef = useRef(config.enabled);
@@ -589,6 +659,8 @@ function useInterrupt(config) {
 	handlerRef.current = config.handler;
 	const resolveRef = useRef(resolve);
 	resolveRef.current = resolve;
+	const cancelRef = useRef(cancel);
+	cancelRef.current = cancel;
 	const isEnabled = (event) => {
 		const predicate = enabledRef.current;
 		if (!predicate) return true;
@@ -600,11 +672,12 @@ function useInterrupt(config) {
 		}
 	};
 	useEffect(() => {
-		if (!pendingEvent) {
+		if (!pending) {
 			setHandlerResult(null);
 			return;
 		}
-		if (!isEnabled(pendingEvent)) {
+		const legacyEvent = toLegacyEvent(pending);
+		if (!isEnabled(legacyEvent)) {
 			setHandlerResult(null);
 			return;
 		}
@@ -617,8 +690,11 @@ function useInterrupt(config) {
 		let maybePromise;
 		try {
 			maybePromise = handler({
-				event: pendingEvent,
-				resolve: resolveRef.current
+				event: legacyEvent,
+				interrupt: pending.kind === "standard" ? pending.interrupts[0] : null,
+				interrupts: pending.kind === "standard" ? pending.interrupts : [],
+				resolve: resolveRef.current,
+				cancel: cancelRef.current
 			});
 		} catch (err) {
 			console.error("[CopilotKit] useInterrupt handler threw; result will be null:", err);
@@ -637,19 +713,24 @@ function useInterrupt(config) {
 		return () => {
 			cancelled = true;
 		};
-	}, [pendingEvent]);
+	}, [pending]);
 	const element = useMemo(() => {
-		if (!pendingEvent) return null;
-		if (!isEnabled(pendingEvent)) return null;
+		if (!pending) return null;
+		const legacyEvent = toLegacyEvent(pending);
+		if (!isEnabled(legacyEvent)) return null;
 		return renderRef.current({
-			event: pendingEvent,
+			event: legacyEvent,
+			interrupt: pending.kind === "standard" ? pending.interrupts[0] : null,
+			interrupts: pending.kind === "standard" ? pending.interrupts : [],
 			result: handlerResult,
-			resolve
+			resolve,
+			cancel
 		});
 	}, [
-		pendingEvent,
+		pending,
 		handlerResult,
-		resolve
+		resolve,
+		cancel
 	]);
 	useEffect(() => {
 		if (config.renderInChat === false) return;
@@ -922,9 +1003,9 @@ function useThreadStoreSelector(store, selector) {
 * current without polling — thread creates, renames, archives, and deletes
 * from any client are reflected immediately.
 *
-* Mutation methods (`renameThread`, `archiveThread`, `deleteThread`) return
-* promises that resolve once the platform confirms the operation and reject
-* with an `Error` on failure.
+* Mutation methods (`renameThread`, `archiveThread`, `unarchiveThread`,
+* `deleteThread`) return promises that resolve once the platform confirms the
+* operation and reject with an `Error` on failure.
 *
 * @param input - Agent identifier and optional list controls.
 * @returns Thread list state and stable mutation callbacks.
@@ -974,21 +1055,32 @@ function useThreads({ agentId, includeArchived, limit }) {
 	const headersKey = useMemo(() => {
 		return JSON.stringify(Object.entries(copilotkit.headers ?? {}).sort(([left], [right]) => left.localeCompare(right)));
 	}, [copilotkit.headers]);
+	const runtimeStatus = copilotkit.runtimeConnectionStatus;
+	const threadListEndpointSupported = copilotkit.threadEndpoints?.list !== false;
+	const threadMutationsSupported = copilotkit.threadEndpoints?.mutations !== false;
+	const threadEndpointsUnavailable = !!copilotkit.runtimeUrl && runtimeStatus === CopilotKitCoreRuntimeConnectionStatus.Connected && !threadListEndpointSupported;
 	const runtimeError = useMemo(() => {
 		if (copilotkit.runtimeUrl) return null;
 		return /* @__PURE__ */ new Error("Runtime URL is not configured");
 	}, [copilotkit.runtimeUrl]);
+	const threadEndpointsError = useMemo(() => {
+		if (!threadEndpointsUnavailable) return null;
+		return /* @__PURE__ */ new Error("Thread endpoints are not available on this CopilotKit runtime");
+	}, [threadEndpointsUnavailable]);
+	const threadMutationsError = useMemo(() => {
+		if (threadMutationsSupported) return null;
+		return /* @__PURE__ */ new Error("Thread mutations are not available on this CopilotKit runtime");
+	}, [threadMutationsSupported]);
 	const [hasDispatchedContext, setHasDispatchedContext] = useState(false);
-	const preConnectLoading = !!copilotkit.runtimeUrl && !hasDispatchedContext;
-	const isLoading = runtimeError ? false : preConnectLoading || storeIsLoading;
-	const error = runtimeError ?? storeError;
+	const preConnectLoading = !!copilotkit.runtimeUrl && !threadEndpointsUnavailable && !hasDispatchedContext;
+	const isLoading = runtimeError || threadEndpointsError ? false : preConnectLoading || storeIsLoading;
+	const error = runtimeError ?? threadEndpointsError ?? storeError;
 	useEffect(() => {
 		store.start();
 		return () => {
 			store.stop();
 		};
 	}, [store]);
-	const runtimeStatus = copilotkit.runtimeConnectionStatus;
 	useEffect(() => {
 		copilotkit.registerThreadStore(agentId, store);
 		return () => {
@@ -1002,9 +1094,15 @@ function useThreads({ agentId, includeArchived, limit }) {
 	useEffect(() => {
 		if (!copilotkit.runtimeUrl) {
 			store.setContext(null);
+			setHasDispatchedContext(false);
 			return;
 		}
 		if (runtimeStatus !== CopilotKitCoreRuntimeConnectionStatus.Connected) return;
+		if (!threadListEndpointSupported) {
+			store.setContext(null);
+			setHasDispatchedContext(false);
+			return;
+		}
 		const context = {
 			runtimeUrl: copilotkit.runtimeUrl,
 			headers: { ...copilotkit.headers },
@@ -1021,13 +1119,21 @@ function useThreads({ agentId, includeArchived, limit }) {
 		runtimeStatus,
 		headersKey,
 		copilotkit.intelligence?.wsUrl,
+		threadListEndpointSupported,
 		agentId,
 		includeArchived,
 		limit
 	]);
-	const renameThread = useCallback((threadId, name) => store.renameThread(threadId, name), [store]);
-	const archiveThread = useCallback((threadId) => store.archiveThread(threadId), [store]);
-	const deleteThread = useCallback((threadId) => store.deleteThread(threadId), [store]);
+	const guardMutation = useCallback((mutation) => {
+		return (...args) => {
+			if (threadMutationsError) return Promise.reject(threadMutationsError);
+			return mutation(...args);
+		};
+	}, [threadMutationsError]);
+	const renameThread = useMemo(() => guardMutation((threadId, name) => store.renameThread(threadId, name)), [store, guardMutation]);
+	const archiveThread = useMemo(() => guardMutation((threadId) => store.archiveThread(threadId)), [store, guardMutation]);
+	const unarchiveThread = useMemo(() => guardMutation((threadId) => store.unarchiveThread(threadId)), [store, guardMutation]);
+	const deleteThread = useMemo(() => guardMutation((threadId) => store.deleteThread(threadId)), [store, guardMutation]);
 	return {
 		threads,
 		isLoading,
@@ -1037,6 +1143,7 @@ function useThreads({ agentId, includeArchived, limit }) {
 		fetchMoreThreads: useCallback(() => store.fetchNextPage(), [store]),
 		renameThread,
 		archiveThread,
+		unarchiveThread,
 		deleteThread
 	};
 }
@@ -1111,10 +1218,20 @@ function useRenderTool(config, deps) {
 		}) : defineToolCallRenderer({
 			name: config.name,
 			args: config.parameters,
-			render: (props) => config.render({
-				...props,
-				parameters: props.args
-			}),
+			render: (props) => {
+				if (props.status === ToolCallStatus.InProgress) return config.render({
+					...props,
+					parameters: props.args
+				});
+				if (props.status === ToolCallStatus.Executing) return config.render({
+					...props,
+					parameters: props.args
+				});
+				return config.render({
+					...props,
+					parameters: props.args
+				});
+			},
 			...config.agentId ? { agentId: config.agentId } : {}
 		});
 		copilotkit.addHookRenderToolCall(renderer);