@economic/agents 0.0.1-alpha.26 → 0.0.1-alpha.27

package/README.md

@@ -6,6 +6,8 @@ Base class and utilities for building LLM chat agents on Cloudflare's Agents SDK
 npm install @economic/agents ai @cloudflare/ai-chat agents
 ```
 
+For React UIs that import `@economic/agents/react`, also install `react`. It is an **optional** peer of the package so Workers-only installs are not required to add React. The hook still needs `agents`, `ai`, and `@cloudflare/ai-chat` at runtime (same as the Cloudflare SDK imports it wraps).
+
 ---
 
 ## Overview
@@ -15,9 +17,35 @@ npm install @economic/agents ai @cloudflare/ai-chat agents
 - **`AIChatAgent`** — an abstract Cloudflare Durable Object base class. Implement `onChatMessage`, call `this.buildLLMParams()`, and pass the result to `streamText` from the AI SDK.
 - **`guard`** — optional TypeScript 5+ method decorator for `onChatMessage`. Runs your function with `options.body`; return a `Response` to short-circuit (e.g. auth), or nothing to continue.
 - **`buildLLMParams`** — the standalone version of the above, for use outside of `AIChatAgent` or in custom agent implementations.
+- **`useAIChatAgent`** (subpath `@economic/agents/react`) — React hook that wraps `useAgent` (`agents/react`) and `useAgentChat` (`@cloudflare/ai-chat/react`). Connection status is **callback-only** (`onConnectionStatusChange`). On WebSocket close codes **`>= 3000`**, the hook calls `agent.close()` to stop reconnection, then forwards `onClose` (use `event.reason` for the server message). Pass-through **`onOpen`**, **`onClose`**, **`onError`** are supported.
 
 Skills and compaction are AI SDK concerns — they control what goes to the LLM. The CF layer is responsible for WebSockets, Durable Objects, and message persistence. These are kept separate.
 
+### React client
+
+```typescript
+import { useAIChatAgent, type AgentConnectionStatus } from "@economic/agents/react";
+import { useState } from "react";
+
+const [connectionStatus, setConnectionStatus] = useState<AgentConnectionStatus>("connecting");
+
+const { agent, chat } = useAIChatAgent({
+  agent: "MyAgent",
+  host: "localhost:8787",
+  chatId: "session-id",
+  toolContext: {},
+  connectionParams: { userId: "…" },
+  onConnectionStatusChange: setConnectionStatus,
+  onOpen: (event) => {},
+  onClose: (event) => {},
+  onError: (event) => {},
+});
+
+const { messages, sendMessage, status, stop } = chat;
+```
+
+Server-side agent code still imports only from `@economic/agents`; the `/react` entry is a separate build output and does not pull Workers runtime code into the client bundle.
+
 ---
 
 ## Quick start

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { AIChatAgent as AIChatAgent$1, OnChatMessageOptions } from "@cloudflare/
 import { LanguageModel, ToolSet, UIMessage, generateText, streamText } from "ai";
 import { Connection, ConnectionContext } from "agents";
 
-//#region src/features/skills/index.d.ts
+//#region src/server/features/skills/index.d.ts
 /**
  * A named group of related tools that can be loaded together on demand.
  *
@@ -23,7 +23,7 @@ interface Skill {
   tools: ToolSet;
 }
 //#endregion
-//#region src/llm.d.ts
+//#region src/server/llm.d.ts
 type LLMParams = Parameters<typeof streamText>[0] & Parameters<typeof generateText>[0];
 type BuildLLMParamsConfig = Omit<LLMParams, "messages" | "experimental_context" | "abortSignal"> & {
   /** CF options object — extracts `abortSignal` and `experimental_context` (from `body`). */options: OnChatMessageOptions | undefined; /** Conversation history (`this.messages`). Converted to `ModelMessage[]` internally. */
@@ -66,7 +66,7 @@ type BuildLLMParamsConfig = Omit<LLMParams, "messages" | "experimental_context"
  */
 declare function buildLLMParams(config: BuildLLMParamsConfig): Promise<LLMParams>;
 //#endregion
-//#region src/agents/AIChatAgent.d.ts
+//#region src/server/agents/AIChatAgent.d.ts
 /**
  * Base class for Cloudflare Agents SDK chat agents with lazy skill loading
  * and built-in audit logging.
@@ -98,13 +98,13 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
    * to `buildLLMParams` rather than omitting or nulling out `fastModel`.
    */
   protected abstract fastModel: LanguageModel;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
   /**
    * Resolves the D1 database binding and userId required for all D1 writes.
    * Returns null and silently no-ops if AGENT_DB is not bound.
    * Returns null and logs an error if userId is missing.
    */
   private resolveD1Context;
-  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
   /**
    * Returns all conversations for the current user.
    */
@@ -178,7 +178,7 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
   }): Promise<void>;
 }
 //#endregion
-//#region src/types.d.ts
+//#region src/server/types.d.ts
 /**
  * The context object available throughout an agent's lifetime — passed via
  * `experimental_context` to tool `execute` functions. Contains the typed

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { AIChatAgent as AIChatAgent$1 } from "@cloudflare/ai-chat";
 import { Output, convertToModelMessages, generateText, jsonSchema, stepCountIs, tool } from "ai";
 import { callable } from "agents";
-//#region src/features/skills/index.ts
+//#region src/server/features/skills/index.ts
 /** Creates the `skill_state` table in DO SQLite if it does not exist yet. */
 function ensureSkillTable(sql) {
 	sql`CREATE TABLE IF NOT EXISTS skill_state (id INTEGER PRIMARY KEY, active_skills TEXT NOT NULL DEFAULT '[]')`;
@@ -279,7 +279,7 @@ async function compactIfNeeded(messages, model, tailSize) {
 	return compactMessages(messages, model, tailSize);
 }
 //#endregion
-//#region src/llm.ts
+//#region src/server/llm.ts
 /**
 * Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
 *
@@ -328,7 +328,7 @@ async function buildLLMParams(config) {
 	};
 }
 //#endregion
-//#region src/features/audit/index.ts
+//#region src/server/features/audit/index.ts
 /**
 * Inserts a single audit event row into the shared `audit_events` D1 table.
 *
@@ -370,7 +370,7 @@ function extractMessageText(msg) {
 	return msg.parts.filter((p) => p.type === "text").map((p) => p.text).join(" ").trim();
 }
 //#endregion
-//#region src/features/conversations/index.ts
+//#region src/server/features/conversations/index.ts
 /**
 * Records a conversation row in the `conversations` D1 table.
 *
@@ -459,7 +459,7 @@ async function generateConversationSummary(db, durableObjectId, messages, model)
 	await updateConversationSummary(db, durableObjectId, title, summary);
 }
 //#endregion
-//#region src/agents/AIChatAgent.ts
+//#region src/server/agents/AIChatAgent.ts
 /**
 * Base class for Cloudflare Agents SDK chat agents with lazy skill loading
 * and built-in audit logging.
@@ -478,6 +478,16 @@ var AIChatAgent = class extends AIChatAgent$1 {
 	* Undefined if the client did not include `userId`.
 	*/
 	_userId;
+	async onConnect(connection, ctx) {
+		super.onConnect(connection, ctx);
+		const userId = new URL(ctx.request.url).searchParams.get("userId");
+		if (!userId) {
+			console.error("[AIChatAgent] Connection rejected: userId query parameter is required");
+			connection.close(3e3, "userId query parameter is required");
+			return;
+		}
+		this._userId = userId;
+	}
 	/**
 	* Resolves the D1 database binding and userId required for all D1 writes.
 	* Returns null and silently no-ops if AGENT_DB is not bound.
@@ -485,9 +495,12 @@ var AIChatAgent = class extends AIChatAgent$1 {
 	*/
 	resolveD1Context() {
 		const db = this.env.AGENT_DB;
-		if (!db) return null;
+		if (!db) {
+			console.error("[AIChatAgent] Skipping logging: D1 database not found");
+			return null;
+		}
 		if (!this._userId) {
-			console.error("[AIChatAgent] Logging & conversation tracking skipped: userId not provided in connection query params");
+			console.error("[AIChatAgent] Skipping logging: userId not provided in connection query params");
 			return null;
 		}
 		return {
@@ -495,15 +508,6 @@ var AIChatAgent = class extends AIChatAgent$1 {
 			userId: this._userId
 		};
 	}
-	async onConnect(connection, ctx) {
-		super.onConnect(connection, ctx);
-		const userId = new URL(ctx.request.url).searchParams.get("userId");
-		if (!userId) {
-			connection.close(3e3, "userId query parameter is required");
-			return;
-		}
-		this._userId = userId;
-	}
 	/**
 	* Returns all conversations for the current user.
 	*/

package/dist/react.d.mts

@@ -0,0 +1,25 @@
+import { UIMessage } from "ai";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+import { useAgent } from "agents/react";
+
+//#region src/client/index.d.ts
+type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized";
+interface UseAIChatAgentOptions {
+  agent: string;
+  host: string;
+  basePath?: string;
+  chatId: string;
+  toolContext?: Record<string, unknown>;
+  connectionParams?: Record<string, string>;
+  onConnectionStatusChange?: (status: AgentConnectionStatus) => void;
+  onOpen?: (event: Event) => void;
+  onClose?: (event: CloseEvent) => void;
+  onError?: (event: ErrorEvent) => void;
+}
+type UseAIChatAgentResult = {
+  agent: ReturnType<typeof useAgent>;
+  chat: ReturnType<typeof useAgentChat<unknown, UIMessage>>;
+};
+declare function useAIChatAgent(options: UseAIChatAgentOptions): UseAIChatAgentResult;
+//#endregion
+export { AgentConnectionStatus, UseAIChatAgentOptions, useAIChatAgent };

package/dist/react.mjs

@@ -0,0 +1,38 @@
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+import { useAgent } from "agents/react";
+//#region src/client/index.ts
+function useAIChatAgent(options) {
+	const { agent: agentName, host, basePath, chatId, toolContext, connectionParams, onConnectionStatusChange, onOpen: onOpenProp, onClose: onCloseProp, onError: onErrorProp } = options;
+	const agent = useAgent({
+		agent: agentName,
+		host,
+		basePath,
+		name: chatId,
+		query: connectionParams ?? {},
+		onOpen: (event) => {
+			onConnectionStatusChange?.("connected");
+			onOpenProp?.(event);
+		},
+		onClose: (event) => {
+			if (event.code >= 3e3) {
+				onConnectionStatusChange?.("unauthorized");
+				agent.close();
+				onCloseProp?.(event);
+				return;
+			}
+			onConnectionStatusChange?.("disconnected");
+			onCloseProp?.(event);
+		},
+		onError: onErrorProp
+	});
+	return {
+		agent,
+		chat: useAgentChat({
+			agent,
+			body: toolContext ?? {},
+			getInitialMessages: null
+		})
+	};
+}
+//#endregion
+export { useAIChatAgent };

package/package.json

@@ -1,17 +1,8 @@
 {
   "name": "@economic/agents",
-  "version": "0.0.1-alpha.26",
+  "version": "0.0.1-alpha.27",
   "description": "A starter for creating a TypeScript package.",
-  "homepage": "https://github.com/author/library#readme",
-  "bugs": {
-    "url": "https://github.com/author/library/issues"
-  },
   "license": "MIT",
-  "author": "Author Name <author.name@mail.com>",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/author/library.git"
-  },
   "files": [
     "dist",
     "schema"
@@ -19,6 +10,7 @@
   "type": "module",
   "exports": {
     ".": "./dist/index.mjs",
+    "./react": "./dist/react.mjs",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -33,9 +25,11 @@
     "@cloudflare/ai-chat": "^0.1.9",
     "@cloudflare/workers-types": "^4.20260317.1",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
     "@typescript/native-preview": "7.0.0-dev.20260316.1",
     "ai": "^6.0.134",
     "bumpp": "^11.0.1",
+    "react": "^19.0.0",
     "tsdown": "^0.21.4",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
@@ -43,6 +37,12 @@
   "peerDependencies": {
     "@cloudflare/ai-chat": "^0.1.0",
     "agents": "^0.7.6",
-    "ai": "^6.0.0"
+    "ai": "^6.0.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }