@economic/agents-react 1.1.9 → 1.2.0

package/README.md

@@ -1,65 +1,199 @@
 # @economic/agents-react
 
-React hooks for connecting to AI chat agents.
+React hooks for connecting to agents built with [`@economic/agents`](../agents/README.md). They wrap the Cloudflare `agents` and `@cloudflare/ai-chat` hooks and add typed connection state, message feedback, and the per-user multi-chat model used by `Assistant`.
 
-## Installation
+## Install
 
-```bash
+```sh
 npm install @economic/agents-react
 ```
 
-## Usage
+React 19 is a peer dependency.
+
+## Which hook do I use?
+
+The package exports three hooks, layered on top of each other:
+
+- **`useAgent`** — the thin connection primitive both build on. Reach for it only when you need raw access to the connection.
+- **`useChat`** — connects directly to a **single** chat agent by name. Use it when you address one conversation yourself (e.g. one chat per route) rather than going through an `Assistant`.
+- **`useAssistant`** — the high-level hook for the v2 model: **one assistant per user, many chats**. It manages the chat list (create / open / delete), connects to the right chat facet, and exposes the active chat. Use this when your server uses an `Assistant`.
+
+---
+
+## `useAgent`
+
+The connection primitive `useChat` and `useAssistant` are built on. Connects to an agent by name and exposes its connection and `call` for invoking `@callable` methods.
 
 ```tsx
-import { useAIChatAgent } from "@economic/agents-react";
-
-const { agent, chat } = useAIChatAgent({
-  agent: "my-agent",
-  host: "https://my-agent.workers.dev",
-  chatId: "session-123",
-  toolContext: {
-    currentDateTime: new Date().toISOString(),
-  },
-  connectionParams: {
-    userId: "user-id",
-    token: "auth-token",
-  },
-  onConnectionStatusChange: (status) => {
-    console.log("Connection status:", status);
-  },
+import { useAgent } from "@economic/agents-react";
+
+const agent = useAgent({
+  host: "localhost:8787",
+  agentName: "SupportAgent",
+  name: "support",
+  actorId: userId, // when set, the DO name becomes `${actorId}:${name}`
+  authToken,
 });
+
+await agent.call("checkOrder", ["1234"]);
+console.log(agent.state?.status);
+```
+
+---
+
+## `useChat`
+
+Connects to a single chat agent by name — no `Assistant` needed. Returns the connection, the message interface, and message-feedback helpers.
+
+```tsx
+import { useChat } from "@economic/agents-react";
+
+const { status, chat, submitMessageFeedback, getMessageFeedback } = useChat({
+  host: "localhost:8787",
+  agentName: "MyChatAgent",
+  name: `${userId}:${chatId}`,
+  authToken,
+  toolContext: { locale: "en-DK" },
+});
+
+// send a message
+chat.sendMessage({ role: "user", parts: [{ type: "text", text: "Hello" }] });
+
+// rate a message (1 = up, -1 = down) and read all feedback
+await submitMessageFeedback(messageId, 1, "Helpful!");
+const feedback = await getMessageFeedback();
 ```
 
-## API
+### Returns
+
+| Field                   | Type                                             | Description                                                   |
+| ----------------------- | ------------------------------------------------ | ------------------------------------------------------------- |
+| `status`                | `AgentConnectionStatus`                          | Connection status.                                            |
+| `agent`                 | connection object                                | The underlying `useAgent` connection.                         |
+| `chat`                  | `useAgentChat` result                            | `messages`, `sendMessage`, `setMessages`, `status`, `stop`, … |
+| `submitMessageFeedback` | `(id, rating, comment?) => Promise<void>`        | Submit thumbs up/down feedback for a message.                 |
+| `getMessageFeedback`    | `() => Promise<Record<string, MessageFeedback>>` | All feedback for the chat, keyed by message id.               |
+
+---
+
+## `useAssistant`
+
+For the per-user, many-chats model: connects to the user's `Assistant` DO, keeps the chat list in sync, and manages which chat is active.
+
+```tsx
+import { useAssistant } from "@economic/agents-react";
+
+function Chat({ userId, authToken }: { userId: string; authToken: string }) {
+  const { status, chats, currentChatName, assistant, chat } = useAssistant({
+    host: "localhost:8787",
+    agentName: "MyAssistant", // matches the Assistant DO binding/class name
+    name: userId, // the Assistant is keyed by user
+    authToken,
+    toolContext: { locale: "en-DK" }, // forwarded to server tools as the request body
+    welcomeMessage: "Hi! How can I help?",
+  });
+
+  return (
+    <div>
+      <button onClick={() => assistant.createChat()}>New chat</button>
+
+      <ul>
+        {chats.map((c) => (
+          <li key={c.name}>
+            <button onClick={() => assistant.openChat(c.name)}>{c.title ?? "Untitled"}</button>
+            <button onClick={() => assistant.deleteChat(c.name)}>Delete</button>
+          </li>
+        ))}
+      </ul>
+
+      {chat.chat.messages.map((m) => (
+        <Message key={m.id} message={m} />
+      ))}
+
+      <Composer
+        onSend={(text) => chat.chat.sendMessage({ role: "user", parts: [{ type: "text", text }] })}
+      />
+    </div>
+  );
+}
+```
 
-### `useAIChatAgent(options)`
+### Returns
 
-Returns `{ agent, chat }` where:
+| 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.                              |
+| `currentChatName` | `string \| undefined`   | Id of the active chat, if any.                                              |
+| `assistant`       | `AssistantActions`      | `getChats`, `createChat`, `openChat`, `deleteChat`.                         |
+| `chat`            | `useChat` result        | The active chat — `chat.chat` is the message interface (see below).         |
 
-- `agent` - The agent connection from `useAgent`
-- `chat` - The chat interface from `useAgentChat`
+`assistant` actions:
 
-#### Options
+| 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.  |
 
-| Option                     | Type                                      | Description                              |
-| -------------------------- | ----------------------------------------- | ---------------------------------------- |
-| `agent`                    | `string`                                  | Agent name                               |
-| `host`                     | `string`                                  | Agent host URL                           |
-| `chatId`                   | `string`                                  | Unique chat session ID                   |
-| `basePath`                 | `string?`                                 | Optional base path                       |
-| `toolContext`              | `Record<string, unknown>?`                | Optional context passed to tools         |
-| `connectionParams`         | `Record<string, string>?`                 | Optional query parameters for connection |
-| `onConnectionStatusChange` | `(status: AgentConnectionStatus) => void` | Callback for connection status changes   |
-| `onOpen`                   | `(event: Event) => void`                  | WebSocket open handler                   |
-| `onClose`                  | `(event: CloseEvent) => void`             | WebSocket close handler                  |
-| `onError`                  | `(event: ErrorEvent) => void`             | WebSocket error handler                  |
+> 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.
 
-### `AgentConnectionStatus`
+---
+
+## Options
+
+All hooks share these connection options (`useAssistant` omits `actorId`):
+
+| Option                           | Type                       | Description                                                                   |
+| -------------------------------- | -------------------------- | ----------------------------------------------------------------------------- |
+| `host`                           | `string`                   | Worker host, e.g. `localhost:8787` or `my-agent.workers.dev`.                 |
+| `agentName`                      | `string`                   | The agent's DO binding/class name.                                            |
+| `name`                           | `string`                   | DO name. For `useAssistant` this is the user id; for `useChat`, the chat key. |
+| `actorId`                        | `string?`                  | If set, the DO name becomes `${actorId}:${name}` (`useAgent` / `useChat`).    |
+| `authToken`                      | `string?`                  | Bearer token; sent as an `Authorization` header and WebSocket subprotocol.    |
+| `enabled`                        | `boolean?`                 | Gate the connection (defaults to enabled when a `name` is present).           |
+| `sub`                            | `{ agent; name }[]?`       | Sub-agent routing (used internally by `useAssistant`).                        |
+| `toolContext`                    | `Record<string, unknown>?` | Forwarded to server tools as the request body (`useChat` / `useAssistant`).   |
+| `welcomeMessage`                 | `string?`                  | Seeds an initial assistant message when the chat is empty.                    |
+| `onOpen` / `onClose` / `onError` | event handlers             | WebSocket lifecycle callbacks.                                                |
+
+---
+
+## Types
 
 ```ts
 type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized";
+type AgentConnectionType = "agent" | "chat" | "assistant";
+
+type AgentConnectionState = {
+  status: AgentConnectionStatus;
+  type: AgentConnectionType;
+  subAgentName?: string;
+};
+
+type ChatSummary = {
+  name: string;
+  title?: string;
+  summary?: string;
+  created_at: number;
+  updated_at: number;
+};
+
+type MessageFeedback = {
+  message_id: string;
+  rating: number; // 1 = up, -1 = down
+  comment?: string;
+  created_at: number;
+  updated_at: number;
+};
 ```
 
-Initial publish.
+The package also exports the handler types `AssistantActions`, `GetChatsHandler`, `CreateChatHandler`, `OpenChatHandler`, `DeleteChatHandler`, `MessageFeedbackHandler`, and `GetMessageFeedbackHandler`.
+
+---
+
+## Authentication
 
+Pass a JWT as `authToken`. It is sent both as an `Authorization: Bearer …` header and as a WebSocket subprotocol (`["bearer", token]`), matching the server-side [`getJwtAuthConfig`](../agents/README.md#authentication). When verification fails, the connection status becomes `"unauthorized"`.
 .

package/dist/index.d.mts

@@ -317,6 +317,7 @@ declare function useChat<ToolContext extends Record<string, unknown>>(options: U
 interface UseAssistantOptions<ToolContext extends Record<string, unknown> = Record<string, unknown>> extends Omit<UseChatOptions<ToolContext>, "actorId" | "getInitialMessages"> {}
 declare function useAssistant<ToolContext extends Record<string, unknown>>(options: UseAssistantOptions<ToolContext>): {
   currentChatName: string | undefined;
+  chats: ChatSummary[];
   status: AgentConnectionStatus;
   assistant: {
     getChats: () => Promise<ChatSummary[]>;

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { useAgent as useAgent$1 } from "agents/react";
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useAgentChat } from "@cloudflare/ai-chat/react";
 //#region src/util.ts
 function getTokenArgs(authToken) {
@@ -80,22 +80,31 @@ function useChat(options) {
 function useAssistant(options) {
 	const { toolContext, welcomeMessage, ...agentOptions } = options;
 	const [chatId, setChatId] = useState();
+	const [chats, setChats] = useState([]);
 	const assistant = useAgent(agentOptions);
-	const getChats = async () => {
-		return (await assistant.call("getChats")).map((chat) => {
+	const refreshChats = useCallback(async () => {
+		setChats((await assistant.call("getChats")).map((chat) => {
 			const c = {
 				...chat,
 				name: chat.durable_object_name
 			};
 			delete c.durable_object_name;
 			return c;
-		});
+		}));
+	}, [assistant]);
+	const assistantStatus = assistant.state?.status;
+	useEffect(() => {
+		if (assistantStatus === "connected") refreshChats().catch(console.error);
+	}, [assistantStatus, refreshChats]);
+	const getChats = async () => {
+		await refreshChats();
+		return chats;
 	};
 	const createChat = async () => {
-		const chatId = await assistant.call("createChat");
-		setChatId(chatId);
-		await getChats();
-		return chatId;
+		const newChatId = await assistant.call("createChat");
+		setChatId(newChatId);
+		await refreshChats();
+		return newChatId;
 	};
 	const openChat = (chatId) => {
 		setChatId(chatId);
@@ -103,7 +112,7 @@ function useAssistant(options) {
 	const deleteChat = async (chatId) => {
 		await assistant.call("deleteChat", [chatId]);
 		setChatId(void 0);
-		await getChats();
+		await refreshChats();
 	};
 	const isChatReady = !!chatId && assistant.state?.status === "connected";
 	const chat = useChat({
@@ -119,6 +128,7 @@ function useAssistant(options) {
 	});
 	return {
 		currentChatName: chatId,
+		chats,
 		status: (chatId ? chat.agent.state?.status : assistant.state?.status) ?? "connecting",
 		assistant: {
 			getChats,

package/dist/v1.d.mts

@@ -0,0 +1,30 @@
+import { useAgent } from "agents/react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+
+//#region src/v1/index.d.ts
+type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized";
+interface UseAIChatAgentOptions {
+  agent: string;
+  host: string;
+  basePath?: string;
+  chatId: string;
+  /** When set with `subAgentName`, used as the coordinator agent instance name instead of `chatId`. */
+  userId?: string;
+  subAgentName?: string;
+  authToken?: string;
+  toolContext?: Record<string, unknown>;
+  connectionParams?: Record<string, string>;
+  welcomeMessage?: string;
+  onConnectionStatusChange?: (status: AgentConnectionStatus) => void;
+  onOpen?: () => void;
+  onClose?: (event: CloseEvent) => void;
+  onError?: (event: ErrorEvent) => void;
+}
+type UseAIChatAgentResult = {
+  agent: ReturnType<typeof useAgent>;
+  chat: ReturnType<typeof useAgentChat>;
+  connectionStatus: AgentConnectionStatus;
+};
+declare function useAIChatAgent(options: UseAIChatAgentOptions): UseAIChatAgentResult;
+//#endregion
+export { AgentConnectionStatus, UseAIChatAgentOptions, useAIChatAgent };

package/dist/v1.mjs

@@ -0,0 +1,121 @@
+import { useAgent } from "agents/react";
+import React from "react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+//#region src/v1/index.ts
+function agentNameToKebab(name) {
+	if (name === name.toUpperCase() && name !== name.toLowerCase()) return name.toLowerCase().replace(/_/g, "-");
+	let result = name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+	result = result.startsWith("-") ? result.slice(1) : result;
+	return result.replace(/_/g, "-").replace(/-$/, "");
+}
+function buildAgentHttpBaseUrl(options) {
+	const hostPart = options.host.replace(/^https?:\/\//, "").replace(/\/$/, "");
+	const protocol = hostPart.startsWith("localhost:") || hostPart.startsWith("127.0.0.1:") || hostPart.startsWith("192.168.") || hostPart.startsWith("10.") ? "http" : "https";
+	let pathname = `/agents/${agentNameToKebab(options.agent)}/${encodeURIComponent(options.name)}`;
+	for (const step of options.sub ?? []) pathname += `/sub/${agentNameToKebab(step.agent)}/${encodeURIComponent(step.name)}`;
+	return `${protocol}://${hostPart}${pathname}`;
+}
+function useAIChatAgent(options) {
+	const { agent: agentName, host, basePath, chatId, userId, subAgentName, authToken, toolContext, connectionParams, welcomeMessage, onConnectionStatusChange, onOpen: onOpenProp, onClose: onCloseProp, onError: onErrorProp } = options;
+	const [connectionStatus, setConnectionStatus] = React.useState("connecting");
+	const updateConnectionStatus = React.useCallback((status) => {
+		setConnectionStatus(status);
+		onConnectionStatusChange?.(status);
+	}, [onConnectionStatusChange]);
+	let headers = {};
+	let protocols = [];
+	if (authToken) {
+		headers["Authorization"] = `Bearer ${authToken}`;
+		protocols.push("bearer", authToken);
+	}
+	const instanceName = userId ?? chatId;
+	const subChain = React.useMemo(() => subAgentName ? [{
+		agent: subAgentName,
+		name: chatId
+	}] : [], [subAgentName, chatId]);
+	const messagesHttpBaseUrl = React.useMemo(() => buildAgentHttpBaseUrl({
+		host,
+		agent: agentName,
+		name: instanceName,
+		sub: subChain.length > 0 ? subChain : void 0
+	}), [
+		host,
+		agentName,
+		instanceName,
+		subChain
+	]);
+	const agent = useAgent({
+		agent: agentName,
+		host,
+		basePath,
+		name: instanceName,
+		sub: subChain.length > 0 ? subChain : void 0,
+		query: connectionParams ?? {},
+		queryDeps: Object.keys(connectionParams ?? {}),
+		onStateUpdate(state) {
+			if (state.status === "connected") {
+				updateConnectionStatus("connected");
+				onOpenProp?.();
+			}
+		},
+		onClose: (event) => {
+			if (event.code >= 3e3) {
+				updateConnectionStatus("unauthorized");
+				agent.close();
+				onCloseProp?.(event);
+				return;
+			}
+			updateConnectionStatus("disconnected");
+			onCloseProp?.(event);
+		},
+		onError: onErrorProp,
+		protocols
+	});
+	const fetchInitialMessages = React.useCallback(async (_options) => {
+		const url = `${messagesHttpBaseUrl}/get-messages`;
+		const response = await fetch(url, { headers });
+		if (!response.ok) {
+			console.warn(`[useAIChatAgent] Failed to fetch initial messages: ${response.status} ${response.statusText}`);
+			return [];
+		}
+		const text = await response.text();
+		if (!text.trim()) return [];
+		try {
+			return JSON.parse(text);
+		} catch (error) {
+			console.warn("[useAIChatAgent] Failed to parse initial messages JSON:", error);
+			return [];
+		}
+	}, [headers, messagesHttpBaseUrl]);
+	const chat = useAgentChat({
+		agent,
+		body: toolContext ?? {},
+		headers,
+		getInitialMessages: fetchInitialMessages
+	});
+	const hasSentWelcome = React.useRef(false);
+	React.useEffect(() => {
+		if (welcomeMessage && connectionStatus === "connected" && chat.messages.length === 0 && !hasSentWelcome.current) {
+			hasSentWelcome.current = true;
+			chat.setMessages([{
+				id: "welcome-message",
+				role: "assistant",
+				parts: [{
+					type: "text",
+					text: welcomeMessage
+				}]
+			}]);
+		}
+	}, [
+		connectionStatus,
+		chat.messages.length,
+		welcomeMessage
+	]);
+	return {
+		agent,
+		chat,
+		connectionStatus
+	};
+}
+//#endregion
+export { useAIChatAgent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents-react",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "license": "MIT",
   "files": [
     "dist"
@@ -9,6 +9,7 @@
   "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs",
+    "./v1": "./dist/v1.mjs",
     "./package.json": "./package.json"
   },
   "scripts": {