agents 0.21.0 → 0.22.0

package/dist/chat/react.d.ts

@@ -208,7 +208,10 @@ type OnToolCallCallback = (options: {
 type UseAgentChatOptions<
   State = unknown,
   ChatMessage extends UIMessage = UIMessage
-> = Omit<UseChatParams<ChatMessage>, "fetch" | "onToolCall"> & {
+> = Omit<
+  UseChatParams<ChatMessage>,
+  "fetch" | "onToolCall" | "throttle" | "experimental_throttle"
+> & {
   /** Agent connection from useAgent (accepts both typed and untyped agents) */ agent: AgentConnection & {
     agent: string;
     name: string;
@@ -227,6 +230,16 @@ type UseAgentChatOptions<
       ) => Promise<ChatMessage[]>) /** Request credentials */;
   credentials?: RequestCredentials /** Request headers */;
   headers?: HeadersInit;
+  /**
+   * Milliseconds to coalesce chat state updates before re-rendering,
+   * defaulting to 50.
+   *
+   * Streaming writes chat state once per chunk, so without a throttle a fast
+   * burst of chunks renders once per chunk. The first chunk is never delayed.
+   * Pass `false` to render every chunk as it arrives.
+   */
+  throttle?: number | false /** @deprecated Use `throttle`. */;
+  experimental_throttle?: number;
   /**
    * Callback for handling client-side tool execution.
    * Called when a tool without server-side `execute` is invoked by the LLM.

package/dist/chat/react.js

@@ -1,10 +1,40 @@
-import { n as STREAM_RESUME_NONE_REASONS, r as transition } from "../protocol-Dqc2MQxo.js";
+import { n as STREAM_RESUME_NONE_REASONS, r as transition } from "../protocol-B0nh6KNf.js";
 import "../wire-types-CnMt6_HR.js";
-import { t as WebSocketChatTransport } from "../ws-chat-transport-CIoOBbO7.js";
+import { t as WebSocketChatTransport } from "../ws-chat-transport-rWwta645.js";
 import { getToolName, isToolUIPart } from "ai";
 import { nanoid } from "nanoid";
 import { use, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useChat } from "@ai-sdk/react";
+/**
+* Picks the throttle from an explicit caller value, the deprecated alias, or
+* the default — in that order. `false` turns throttling off.
+*/
+function resolveChatThrottleMs(options) {
+	if (options.throttle === false) return void 0;
+	return options.throttle ?? options.experimental_throttle ?? 50;
+}
+/**
+* The throttle spelled under both option names, or neither name when it is off.
+*
+* The two names are not interchangeable across the peer range. `@ai-sdk/react`
+* v3 only reads `experimental_throttle`; v4 renamed it to `throttle` and reads
+* `throttle ?? experimental_throttle`. Our peer range allows both majors, so
+* sending one name would silently do nothing on the other. Unknown option keys
+* are ignored by both, so sending both names is safe.
+*
+* Turning throttling off omits both names rather than inventing a numeric
+* value. Both majors also treat an explicit `0` as unthrottled, so callers that
+* pass `0` keep that value under both spellings.
+*/
+function chatThrottleOptions(options) {
+	const ms = resolveChatThrottleMs(options);
+	if (ms === void 0) return {};
+	return {
+		experimental_throttle: ms,
+		throttle: ms
+	};
+}
+//#endregion
 //#region src/chat/react.tsx
 /**
 * One-shot deprecation warnings (warns once per key per session).
@@ -186,7 +216,7 @@ function detectToolsRequiringConfirmation(tools) {
 	return Object.entries(tools).filter(([_name, tool]) => !tool.execute).map(([name]) => name);
 }
 function useAgentChat(options) {
-	const { agent, getInitialMessages, messages: optionsInitialMessages, onToolCall, onData, experimental_automaticToolResolution, tools, toolsRequiringConfirmation: manualToolsRequiringConfirmation, autoContinueAfterToolResult = true, autoSendAfterAllConfirmationsResolved = true, resume = true, cancelOnClientAbort = false, syncMessagesToServer = true, body: bodyOption, prepareSendMessagesRequest, ...rest } = options;
+	const { agent, getInitialMessages, messages: optionsInitialMessages, onToolCall, onData, experimental_automaticToolResolution, tools, toolsRequiringConfirmation: manualToolsRequiringConfirmation, autoContinueAfterToolResult = true, autoSendAfterAllConfirmationsResolved = true, resume = true, cancelOnClientAbort = false, syncMessagesToServer = true, body: bodyOption, prepareSendMessagesRequest, throttle, experimental_throttle, ...rest } = options;
 	if (manualToolsRequiringConfirmation) warnDeprecated("useAgentChat.toolsRequiringConfirmation", "The 'toolsRequiringConfirmation' option is deprecated. Use needsApproval on server-side tools instead. Will be removed in the next major version.");
 	if (experimental_automaticToolResolution) warnDeprecated("useAgentChat.experimental_automaticToolResolution", "The 'experimental_automaticToolResolution' option is deprecated. Use the onToolCall callback instead. Will be removed in the next major version.");
 	if (options.autoSendAfterAllConfirmationsResolved !== void 0) warnDeprecated("useAgentChat.autoSendAfterAllConfirmationsResolved", "The 'autoSendAfterAllConfirmationsResolved' option is deprecated. Use sendAutomaticallyWhen from AI SDK instead. Will be removed in the next major version.");
@@ -312,6 +342,10 @@ function useAgentChat(options) {
 	const customTransport = customTransportRef.current;
 	const useChatHelpers = useChat({
 		...rest,
+		...chatThrottleOptions({
+			experimental_throttle,
+			throttle
+		}),
 		onData,
 		messages: initialMessages,
 		transport: customTransport,
@@ -415,8 +449,6 @@ function useAgentChat(options) {
 	const isResolvingToolsRef = useRef(false);
 	const [toolResolutionTrigger, setToolResolutionTrigger] = useState(0);
 	const [clientToolResults, setClientToolResults] = useState(/* @__PURE__ */ new Map());
-	const messagesRef = useRef(chatMessages);
-	messagesRef.current = chatMessages;
 	const initialMessagesRef = useRef(initialMessages);
 	initialMessagesRef.current = initialMessages;
 	const seededInitialMessagesKeyRef = useRef(null);
@@ -436,7 +468,7 @@ function useAgentChat(options) {
 	]);
 	const localResponseMessageIdsRef = useRef(/* @__PURE__ */ new Map());
 	const protectedStreamingAssistantRef = useRef(null);
-	const preserveProtectedStreamingAssistant = useCallback((messages) => {
+	const preserveProtectedStreamingAssistant = useCallback((messages, currentMessages) => {
 		const protection = protectedStreamingAssistantRef.current;
 		if (!protection) return [...messages];
 		const protectedIndex = messages.findIndex((message) => message.id === protection.assistantId);
@@ -444,22 +476,20 @@ function useAgentChat(options) {
 			protectedStreamingAssistantRef.current = null;
 			return [...messages];
 		}
-		const protectedAssistant = messagesRef.current.find((message) => message.id === protection.assistantId) ?? messages.find((message) => message.id === protection.assistantId);
+		const protectedAssistant = currentMessages.find((message) => message.id === protection.assistantId) ?? messages.find((message) => message.id === protection.assistantId);
 		if (!protectedAssistant) return [...messages];
 		return [...messages.filter((message) => message.id !== protection.assistantId), protectedAssistant];
 	}, []);
 	const protectStreamingAssistantTail = useCallback(() => {
 		if (statusRef.current !== "streaming") return;
-		const assistantInfo = findLastAssistantMessage(messagesRef.current);
-		if (!assistantInfo) return;
-		if (protectedStreamingAssistantRef.current?.assistantId !== assistantInfo.message.id) protectedStreamingAssistantRef.current = {
-			assistantId: assistantInfo.message.id,
-			anchorMessageId: messagesRef.current[assistantInfo.index - 1]?.id ?? null
-		};
-		setMessages((prevMessages) => {
-			const protection = protectedStreamingAssistantRef.current;
-			if (!protection) return prevMessages;
-			return moveMessageToEnd(prevMessages, protection.assistantId);
+		setMessages((currentMessages) => {
+			const assistantInfo = findLastAssistantMessage(currentMessages);
+			if (!assistantInfo) return currentMessages;
+			if (protectedStreamingAssistantRef.current?.assistantId !== assistantInfo.message.id) protectedStreamingAssistantRef.current = {
+				assistantId: assistantInfo.message.id,
+				anchorMessageId: currentMessages[assistantInfo.index - 1]?.id ?? null
+			};
+			return moveMessageToEnd(currentMessages, assistantInfo.message.id);
 		});
 	}, [setMessages]);
 	const restoreProtectedStreamingAssistant = useCallback((assistantId) => {
@@ -740,17 +770,18 @@ function useAgentChat(options) {
 				case "cf_agent_chat_recovering":
 					setIsRecovering(Boolean(data.recovering));
 					break;
-				case "cf_agent_chat_messages": {
-					let next = preserveProtectedStreamingAssistant(data.messages);
-					const observed = streamStateRef.current;
-					if (observed.status === "observing" && observed.accumulator.parts.length > 0) {
-						const snapshotIdx = next.findIndex((m) => m.id === observed.accumulator.messageId);
-						const snapshotParts = snapshotIdx >= 0 ? next[snapshotIdx].parts.length : 0;
-						if (observed.accumulator.parts.length >= snapshotParts) next = observed.accumulator.mergeInto(next);
-					}
-					setMessages(next);
+				case "cf_agent_chat_messages":
+					setMessages((currentMessages) => {
+						let next = preserveProtectedStreamingAssistant(data.messages, currentMessages);
+						const observed = streamStateRef.current;
+						if (observed.status === "observing" && observed.accumulator.parts.length > 0) {
+							const snapshotIdx = next.findIndex((m) => m.id === observed.accumulator.messageId);
+							const snapshotParts = snapshotIdx >= 0 ? next[snapshotIdx].parts.length : 0;
+							if (observed.accumulator.parts.length >= snapshotParts) next = observed.accumulator.mergeInto(next);
+						}
+						return next;
+					});
 					break;
-				}
 				case "cf_agent_message_updated":
 					setMessages((prevMessages) => {
 						const updatedMessage = data.message;
@@ -818,21 +849,21 @@ function useAgentChat(options) {
 						if (data.body?.trim()) try {
 							const chunkData = JSON.parse(data.body);
 							if (chunkData.type === "start" && typeof chunkData.messageId === "string") {
-								localResponseIds.set(data.id, chunkData.messageId);
+								const messageId = chunkData.messageId;
+								localResponseIds.set(data.id, messageId);
 								if (!data.continuation) {
-									if (protectedStreamingAssistantRef.current?.assistantId !== chunkData.messageId) {
-										const msgs = messagesRef.current;
-										const idx = msgs.findIndex((m) => m.id === chunkData.messageId);
-										const anchorMessageId = idx >= 0 ? msgs[idx - 1]?.id ?? null : msgs[msgs.length - 1]?.id ?? null;
+									if (protectedStreamingAssistantRef.current?.assistantId !== messageId) setMessages((currentMessages) => {
+										const idx = currentMessages.findIndex((message) => message.id === messageId);
 										protectedStreamingAssistantRef.current = {
-											assistantId: chunkData.messageId,
-											anchorMessageId
+											assistantId: messageId,
+											anchorMessageId: idx >= 0 ? currentMessages[idx - 1]?.id ?? null : currentMessages[currentMessages.length - 1]?.id ?? null
 										};
-									}
+										return currentMessages;
+									});
 								}
 								if (data.replay && !data.continuation && !resumingToolContinuationRef.current && observedToolContinuationRequestIdRef.current !== data.id) {
 									pendingReplayResumeRequestIdsRef.current.delete(data.id);
-									resetMatchingHydratedAssistantForReplay(chunkData.messageId);
+									resetMatchingHydratedAssistantForReplay(messageId);
 								}
 							}
 						} catch {}
@@ -892,8 +923,7 @@ function useAgentChat(options) {
 						error: data.error,
 						replay: data.replay,
 						replayComplete: data.replayComplete,
-						continuation: data.continuation,
-						currentMessages: data.continuation ? messagesRef.current : void 0
+						continuation: data.continuation
 					});
 					streamStateRef.current = result.state;
 					if (result.messagesUpdate) setMessages(result.messagesUpdate);
@@ -1013,13 +1043,13 @@ function useAgentChat(options) {
 	const addToolApprovalResponseAndNotifyServer = (args) => {
 		const { id: approvalId, approved } = args;
 		let toolCallId;
-		for (const msg of messagesRef.current) {
-			for (const part of msg.parts) if ("toolCallId" in part && "approval" in part && part.approval?.id === approvalId) {
+		setMessages((currentMessages) => {
+			for (const msg of currentMessages) for (const part of msg.parts) if ("toolCallId" in part && "approval" in part && part.approval?.id === approvalId) {
 				toolCallId = part.toolCallId;
-				break;
+				return currentMessages;
 			}
-			if (toolCallId) break;
-		}
+			return currentMessages;
+		});
 		if (toolCallId) sendToolApprovalToServer(toolCallId, approved);
 		else console.warn(`[useAgentChat] addToolApprovalResponse: Could not find toolCallId for approval ID "${approvalId}". Server will not be notified, which may cause duplicate messages.`);
 		addToolApprovalResponse(args);
@@ -1118,15 +1148,15 @@ function useAgentChat(options) {
 			agent.send(JSON.stringify({ type: "cf_agent_chat_clear" }));
 		},
 		setMessages: (messagesOrUpdater) => {
-			let resolvedMessages;
-			if (typeof messagesOrUpdater === "function") resolvedMessages = messagesOrUpdater(messagesRef.current);
-			else resolvedMessages = messagesOrUpdater;
-			if (resolvedMessages.length === 0) markInitialMessagesSeeded();
-			setMessages(resolvedMessages);
-			if (syncMessagesToServer) agent.send(JSON.stringify({
-				messages: resolvedMessages,
-				type: "cf_agent_chat_messages"
-			}));
+			setMessages((currentMessages) => {
+				const resolvedMessages = typeof messagesOrUpdater === "function" ? messagesOrUpdater(currentMessages) : messagesOrUpdater;
+				if (resolvedMessages.length === 0) markInitialMessagesSeeded();
+				if (syncMessagesToServer) agent.send(JSON.stringify({
+					messages: resolvedMessages,
+					type: "cf_agent_chat_messages"
+				}));
+				return resolvedMessages;
+			});
 		}
 	};
 }