@economic/agents-react 1.5.0 → 1.6.1

package/README.md

@@ -123,22 +123,27 @@ function Chat({ userId, authToken }: { userId: string; authToken: string }) {
 | Field             | Type                    | Description                                                                 |
 | ----------------- | ----------------------- | --------------------------------------------------------------------------- |
 | `status`          | `AgentConnectionStatus` | Connection status of the assistant, or of the active chat once one is open. |
-| `chats`           | `ChatSummary[]`         | The user's chats, most recently updated first.                              |
+| `chats`           | `ChatSummary[]`         | Started chats plus the active empty draft, most recently updated first.     |
 | `currentChatName` | `string \| undefined`   | Id of the active chat, if any.                                              |
-| `assistant`       | `AssistantActions`      | `getChats`, `createChat`, `openChat`, `deleteChat`.                         |
+| `assistant`       | `AssistantActions`      | `getChats`, `createChat`, `openChat`, `deleteChat`, `renameChat`.           |
 | `chat`            | `useChat` result        | The active chat — `chat.chat` is the message interface (see below).         |
 
 `assistant` actions:
 
-| Action               | Signature                           | Description                                      |
-| -------------------- | ----------------------------------- | ------------------------------------------------ |
-| `createChat()`       | `() => Promise<string>`             | Creates a chat, makes it active, returns its id. |
-| `openChat(chatId)`   | `(chatId: string) => void`          | Switches the active chat.                        |
-| `getChats()`         | `() => Promise<ChatSummary[]>`      | Refreshes and returns the chat list.             |
-| `deleteChat(chatId)` | `(chatId: string) => Promise<void>` | Deletes a chat and clears the active selection.  |
+| Action               | Signature                                          | Description                                      |
+| -------------------- | -------------------------------------------------- | ------------------------------------------------ |
+| `createChat()`       | `() => Promise<string>`                            | Creates a chat, makes it active, returns its id. |
+| `openChat(chatId)`   | `(chatId: string) => void`                         | Switches the active chat.                        |
+| `getChats()`         | `() => Promise<ChatSummary[]>`                     | Refreshes and returns the chat list.             |
+| `deleteChat(chatId)` | `(chatId: string) => Promise<void>`                | Deletes a chat and clears the active selection.  |
+| `renameChat(chatId)` | `(chatId: string, title: string) => Promise<void>` | Renames a registered chat.                       |
 
 > Titles and summaries are generated server-side a few seconds after the first message, so refetch with `getChats()` shortly after sending the opening message if you want the new title to appear.
 
+The active empty chat is represented locally until its first turn registers it on the server.
+
+After the active draft's first turn finishes, `useAssistant` refreshes the chat list automatically so the temporary entry is replaced by its persisted title and summary.
+
 ---
 
 ## Options
@@ -174,6 +179,7 @@ type AgentConnectionState = {
 
 type ChatSummary = {
   name: string;
+  isTemporary?: boolean; // true for the active chat before its first turn is registered
   title?: string;
   summary?: string;
   created_at: number;

package/dist/index.d.mts

@@ -10,7 +10,8 @@ type Chat = ReturnType<typeof useAgentChat>;
 type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized" | "error";
 type AgentConnectionType = "agent" | "chat" | "assistant";
 type ChatSummary = {
-  name: string;
+  name: string; /** True when this entry only represents the active, unregistered chat facet. */
+  isTemporary?: boolean;
   title?: string;
   summary?: string;
   title_set_by_user?: number;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { useAgent as useAgent$1 } from "agents/react";
 import { getToolApproval, getToolCallId, getToolPartState, useAgentChat } from "@cloudflare/ai-chat/react";
 //#region src/util.ts
@@ -11,6 +11,16 @@ function getTokenArgs(authToken) {
 }
 //#endregion
 //#region src/useAgent.ts
+function getAgentConnectionStatus(state, connectionId) {
+	return state.connectionId === connectionId ? state.status : "connecting";
+}
+function getNextAgentConnectionState(state, connectionId, status) {
+	if (status === "disconnected" && state.connectionId === connectionId && state.status === "error") return state;
+	return {
+		connectionId,
+		status
+	};
+}
 function getCloseReason(code) {
 	return {
 		1e3: "normal-closure",
@@ -29,46 +39,168 @@ function getCloseReason(code) {
 		1015: "tls-handshake-failure"
 	}[code] ?? "unknown";
 }
+function getDefaultHost() {
+	return globalThis.window?.location?.host || "dummy-domain.com";
+}
+function normalizeAgentName(name) {
+	if (name === name.toUpperCase() && name !== name.toLowerCase()) return name.toLowerCase().replace(/_/g, "-");
+	const kebabified = name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+	return (kebabified.startsWith("-") ? kebabified.slice(1) : kebabified).replace(/_/g, "-").replace(/-$/, "");
+}
+function getSubPath(sub) {
+	if (!sub?.length) return void 0;
+	return sub.flatMap(({ agent, name }) => [
+		"sub",
+		normalizeAgentName(agent),
+		encodeURIComponent(name)
+	]).join("/");
+}
+function getAgentConnectionTarget(options) {
+	const effectiveName = options.actorId ? `${options.actorId}:${options.name}` : options.name;
+	return {
+		enabled: options.enabled ?? true,
+		host: options.host || getDefaultHost(),
+		agentName: normalizeAgentName(options.agentName),
+		name: effectiveName || "default",
+		subPath: getSubPath(options.sub),
+		authToken: options.authToken || void 0
+	};
+}
+function getAgentSocketTarget(agent) {
+	const options = agent.partySocketOptions;
+	if (typeof options?.host !== "string" || typeof options.party !== "string" || typeof options.room !== "string") return;
+	const protocols = options.protocols;
+	const authToken = Array.isArray(protocols) && protocols[0] === "bearer" && typeof protocols[1] === "string" ? protocols[1] : void 0;
+	return {
+		host: options.host,
+		agentName: options.party,
+		name: options.room,
+		subPath: typeof options.path === "string" && options.path ? options.path : void 0,
+		authToken
+	};
+}
+function isSameSocketTarget(a, b) {
+	return a.host === b.host && a.agentName === b.agentName && a.name === b.name && a.subPath === b.subPath && a.authToken === b.authToken;
+}
+function isSameConnectionTarget(a, b) {
+	return a.enabled === b.enabled && isSameSocketTarget(a, b);
+}
+function getNextAgentConnection(connection, target) {
+	return isSameConnectionTarget(connection.target, target) ? connection : {
+		id: connection.id + 1,
+		target
+	};
+}
+function isCurrentAgentSocketTarget(eventConnection, connection) {
+	if (!connection.target.enabled || !eventConnection) return false;
+	const socketTarget = getAgentSocketTarget(eventConnection);
+	return socketTarget !== void 0 && isSameSocketTarget(socketTarget, connection.target);
+}
 function useAgent(options) {
 	const { enabled, host, agentName, actorId, name, sub, authToken, onError, onOpen, onClose, onMessage } = options;
-	const [type, setType] = useState(void 0);
-	const [status, setStatus] = useState("connecting");
+	const target = getAgentConnectionTarget(options);
+	const [connection, setConnection] = useState({
+		id: 0,
+		target
+	});
+	const nextConnection = getNextAgentConnection(connection, target);
+	if (nextConnection !== connection) setConnection(nextConnection);
+	const connectionId = nextConnection.id;
+	const [connectionType, setConnectionType] = useState();
+	const type = connectionType?.connectionId === connectionId ? connectionType.type : void 0;
+	const [connectionStatus, setConnectionStatus] = useState({
+		connectionId,
+		status: "connecting"
+	});
+	const status = getAgentConnectionStatus(connectionStatus, connectionId);
+	const committedConnection = useRef({
+		connection: nextConnection,
+		callbacks: {
+			onOpen,
+			onClose,
+			onError,
+			onMessage
+		}
+	});
+	const setStatus = useCallback((nextStatus) => {
+		const committedConnectionId = committedConnection.current.connection.id;
+		setConnectionStatus((current) => getNextAgentConnectionState(current, committedConnectionId, nextStatus));
+	}, []);
+	const setType = useCallback((nextType) => {
+		setConnectionType({
+			connectionId: committedConnection.current.connection.id,
+			type: nextType
+		});
+	}, []);
+	const isCurrentConnectionEvent = useCallback((event) => {
+		const committed = committedConnection.current;
+		return isCurrentAgentSocketTarget(event.target, committed.connection);
+	}, []);
+	const handleOpen = useCallback((event) => {
+		if (!isCurrentConnectionEvent(event)) return;
+		committedConnection.current.callbacks.onOpen?.(event);
+	}, [isCurrentConnectionEvent]);
+	const handleClose = useCallback((event) => {
+		if (!isCurrentConnectionEvent(event)) return;
+		if (event.code >= 3e3) setStatus("unauthorized");
+		else {
+			setStatus("disconnected");
+			if (!event.wasClean) console.warn("[useAgent] WebSocket closed unexpectedly", {
+				code: event.code,
+				reason: event.reason,
+				closeReason: getCloseReason(event.code),
+				wasClean: event.wasClean
+			});
+		}
+		committedConnection.current.callbacks.onClose?.(event);
+	}, [isCurrentConnectionEvent, setStatus]);
+	const handleMessage = useCallback((event) => {
+		if (!isCurrentConnectionEvent(event)) return;
+		const msg = JSON.parse(event.data);
+		if (msg.type === "connection_status") {
+			if (msg.status === "unauthorized") event.target.close(3e3);
+			setStatus(msg.status);
+		} else if (msg.type === "agent_type") setType(msg.agentType);
+		committedConnection.current.callbacks.onMessage?.(event);
+	}, [
+		isCurrentConnectionEvent,
+		setStatus,
+		setType
+	]);
+	const handleError = useCallback((event) => {
+		if (!isCurrentConnectionEvent(event)) return;
+		setStatus("error");
+		committedConnection.current.callbacks.onError?.(event);
+	}, [isCurrentConnectionEvent, setStatus]);
 	const agent = useAgent$1({
 		enabled,
 		host,
 		agent: agentName,
 		name: actorId ? `${actorId}:${name}` : name,
 		sub,
-		onOpen: (event) => {
-			onOpen?.(event);
-		},
-		onClose: (event) => {
-			if (event.code >= 3e3) setStatus("unauthorized");
-			else {
-				setStatus("disconnected");
-				if (!event.wasClean) console.warn("[useAgent] WebSocket closed unexpectedly", {
-					code: event.code,
-					reason: event.reason,
-					closeReason: getCloseReason(event.code),
-					wasClean: event.wasClean
-				});
-			}
-			onClose?.(event);
-		},
-		onMessage: (event) => {
-			const msg = JSON.parse(event.data);
-			if (msg.type === "connection_status") {
-				if (msg.status === "unauthorized") agent.close(3e3);
-				setStatus(msg.status);
-			} else if (msg.type === "agent_type") setType(msg.agentType);
-			onMessage?.(event);
-		},
-		onError: (event) => {
-			setStatus("error");
-			onError?.(event);
-		},
+		onOpen: handleOpen,
+		onClose: handleClose,
+		onMessage: handleMessage,
+		onError: handleError,
 		...getTokenArgs(authToken)
 	});
+	useLayoutEffect(() => {
+		committedConnection.current = {
+			connection: nextConnection,
+			callbacks: {
+				onOpen,
+				onClose,
+				onError,
+				onMessage
+			}
+		};
+	}, [
+		nextConnection,
+		onOpen,
+		onClose,
+		onError,
+		onMessage
+	]);
 	return {
 		agent,
 		status,
@@ -126,10 +258,25 @@ function useChat(options) {
 }
 //#endregion
 //#region src/useAssistant.ts
+function getAssistantConnectionStatus(currentChatName, isChatEnabled, assistantStatus, chatStatus) {
+	if (currentChatName === void 0) return assistantStatus;
+	if (!isChatEnabled) return assistantStatus === "connected" ? "connecting" : assistantStatus;
+	return chatStatus;
+}
 function useAssistant(options) {
 	const { toolContext, welcomeMessage, initialChatId, ...agentOptions } = options;
 	const [chatId, setChatId] = useState(initialChatId);
 	const [chats, setChats] = useState([]);
+	const [draftChat, setDraftChat] = useState(() => {
+		if (!initialChatId) return void 0;
+		const now = Date.now();
+		return {
+			name: initialChatId,
+			isTemporary: true,
+			created_at: now,
+			updated_at: now
+		};
+	});
 	const [subAgentName, setSubAgentName] = useState(void 0);
 	const { agent: assistant, status: assistantStatus } = useAgent({
 		...agentOptions,
@@ -148,8 +295,29 @@ function useAssistant(options) {
 			return c;
 		});
 		setChats(fetched);
+		setDraftChat((current) => {
+			if (current && fetched.some((chat) => chat.name === current.name)) return;
+			return current;
+		});
 		return fetched;
 	}, [assistant]);
+	const refreshChatsRef = useRef(refreshChats);
+	refreshChatsRef.current = refreshChats;
+	const draftRefreshTimeouts = useRef(/* @__PURE__ */ new Map());
+	const scheduleDraftRefresh = useCallback((draftId) => {
+		const existingTimeout = draftRefreshTimeouts.current.get(draftId);
+		if (existingTimeout) clearTimeout(existingTimeout);
+		const timeout = setTimeout(() => {
+			draftRefreshTimeouts.current.delete(draftId);
+			refreshChatsRef.current().catch(console.error);
+		}, 3e3);
+		draftRefreshTimeouts.current.set(draftId, timeout);
+	}, []);
+	useEffect(() => {
+		return () => {
+			for (const timeout of draftRefreshTimeouts.current.values()) clearTimeout(timeout);
+		};
+	}, []);
 	useEffect(() => {
 		if (assistantStatus === "connected") refreshChats().catch(console.error);
 	}, [assistantStatus, refreshChats]);
@@ -157,17 +325,26 @@ function useAssistant(options) {
 		return refreshChats();
 	};
 	const createChat = async () => {
+		if (draftChat && draftChat.name === chatId) scheduleDraftRefresh(draftChat.name);
 		const newChatId = await assistant.call("createChat");
+		const now = Date.now();
 		setChatId(newChatId);
-		await refreshChats();
+		setDraftChat({
+			name: newChatId,
+			isTemporary: true,
+			created_at: now,
+			updated_at: now
+		});
 		return newChatId;
 	};
-	const openChat = (chatId) => {
-		setChatId(chatId);
+	const openChat = (nextChatId) => {
+		if (draftChat && draftChat.name === chatId) scheduleDraftRefresh(draftChat.name);
+		setChatId(nextChatId);
 	};
 	const deleteChat = async (chatId) => {
 		await assistant.call("deleteChat", [chatId]);
 		setChatId(void 0);
+		setDraftChat((current) => current?.name === chatId ? void 0 : current);
 		await refreshChats();
 	};
 	const renameChat = async (chatId, title) => {
@@ -175,7 +352,6 @@ function useAssistant(options) {
 		await refreshChats();
 	};
 	const isChatEnabled = !!chatId && !!subAgentName;
-	const isChatReady = isChatEnabled && assistantStatus === "connected";
 	const chat = useChat({
 		...agentOptions,
 		enabled: isChatEnabled,
@@ -183,14 +359,27 @@ function useAssistant(options) {
 			agent: subAgentName,
 			name: chatId
 		}] : void 0,
-		getInitialMessages: isChatReady ? void 0 : null,
 		toolContext,
 		welcomeMessage
 	});
+	const previousChatStatus = useRef(chat.chat.status);
+	useEffect(() => {
+		const wasRunning = previousChatStatus.current === "submitted" || previousChatStatus.current === "streaming";
+		const hasFinished = chat.chat.status === "ready" || chat.chat.status === "error";
+		previousChatStatus.current = chat.chat.status;
+		if (!draftChat || draftChat.name !== chatId || !wasRunning || !hasFinished) return;
+		scheduleDraftRefresh(draftChat.name);
+	}, [
+		chat.chat.status,
+		chatId,
+		draftChat,
+		scheduleDraftRefresh
+	]);
+	const status = getAssistantConnectionStatus(chatId, isChatEnabled, assistantStatus, chat.status);
 	return {
 		currentChatName: chatId,
-		chats,
-		status: isChatEnabled && chat.status !== "connecting" ? chat.status : assistantStatus,
+		chats: draftChat && draftChat.name === chatId && !chats.some((persistedChat) => persistedChat.name === draftChat.name) ? [draftChat, ...chats] : chats,
+		status,
 		assistant: {
 			agent: assistant,
 			getChats,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents-react",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "license": "MIT",
   "files": [
     "dist"