@tanstack/ai-react 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+<div align="center">
+  <img src="./media/header_ai.png" >
+</div>
+
+<br />
+
+<div align="center">
+<a href="https://npmjs.com/package/@tanstack/ai" target="\_parent">
+  <img alt="" src="https://img.shields.io/npm/dm/@tanstack/ai.svg" />
+</a>
+<a href="https://github.com/TanStack/ai" target="\_parent">
+	  <img alt="" src="https://img.shields.io/github/stars/TanStack/ai.svg?style=social&label=Star" alt="GitHub stars" />
+</a>
+<a href="https://bundlephobia.com/result?p=@tanstack/ai@latest" target="\_parent">
+  <img alt="" src="https://badgen.net/bundlephobia/minzip/@tanstack/ai@latest" />
+</a>
+</div>
+
+<div align="center">
+<a href="#badge">
+  <img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
+</a>
+	<a href="#badge">
+		<img src="https://img.shields.io/github/v/release/tanstack/ai" alt="Release"/>
+	</a>
+<a href="https://twitter.com/tan_stack">
+  <img src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social" alt="Follow @TanStack"/>
+</a>
+</div>
+
+<div align="center">
+  
+### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
+</div>
+
+# TanStack AI
+
+A powerful, type-safe AI SDK for building AI-powered applications.
+
+- Provider-agnostic adapters (OpenAI, Anthropic, Gemini, Ollama, etc.)
+- **Multimodal content support** - Send images, audio, video, and documents
+- Chat completion, streaming, and agent loop strategies
+- Headless chat state management with adapters (SSE, HTTP stream, custom)
+- Isomorphic type-safe tools with server/client execution
+- **Enhanced integration with TanStack Start** - Share implementations between AI tools and server functions
+
+### <a href="https://tanstack.com/ai">Read the docs →</b></a>
+
+## Bonus: TanStack Start Integration
+
+TanStack AI works with **any** framework (Next.js, Express, Remix, etc.).
+
+**With TanStack Start**, you get a bonus: share implementations between AI tools and server functions with `createServerFnTool`:
+
+```typescript
+import { createServerFnTool } from '@tanstack/ai-react'
+
+// Define once, get AI tool AND server function (TanStack Start only)
+const getProducts = createServerFnTool({
+  name: 'getProducts',
+  inputSchema: z.object({ query: z.string() }),
+  execute: async ({ query }) => db.products.search(query),
+})
+
+// Use in AI chat
+chat({ tools: [getProducts.server] })
+
+// Call directly from components (no API endpoint needed!)
+const products = await getProducts.serverFn({ query: 'laptop' })
+```
+
+No duplicate logic, full type safety, automatic validation. The `serverFn` feature requires TanStack Start. See [docs](https://tanstack.com/ai) for details.
+
+## Get Involved
+
+- We welcome issues and pull requests!
+- Participate in [GitHub discussions](https://github.com/TanStack/ai/discussions)
+- Chat with the community on [Discord](https://discord.com/invite/WrRKjPJ)
+- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions
+
+## Partners
+
+<table align="center">
+  <tr>
+    <td>
+      <a href="https://www.coderabbit.ai/?via=tanstack&dub_id=aCcEEdAOqqutX6OS" >
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/coderabbit-dark-CMcuvjEy.svg" height="40" />
+          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" />
+          <img src="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" alt="CodeRabbit" />
+        </picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.cloudflare.com?utm_source=tanstack">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/cloudflare-white-DQDB7UaL.svg" height="60" />
+          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" />
+          <img src="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" alt="Cloudflare" />
+        </picture>
+      </a>
+    </td>
+  </tr>
+</table>
+
+<div align="center">
+<img src="./media/partner_logo.svg" alt="AI & you?" height="65">
+<p>
+We're looking for TanStack AI Partners to join our mission! Partner with us to push the boundaries of TanStack AI and build amazing things together.
+</p>
+<a href="mailto:partners@tanstack.com?subject=TanStack AI Partnership"><b>LET'S CHAT</b></a>
+</div>
+
+## Explore the TanStack Ecosystem
+
+- <a href="https://github.com/tanstack/config"><b>TanStack Config</b></a> – Tooling for JS/TS packages
+- <a href="https://github.com/tanstack/db"><b>TanStack DB</b></a> – Reactive sync client store
+- <a href="https://github.com/tanstack/devtools">TanStack Devtools</a> – Unified devtools panel
+- <a href="https://github.com/tanstack/form"><b>TanStack Form</b></a> – Type‑safe form state
+- <a href="https://github.com/tanstack/pacer"><b>TanStack Pacer</b></a> – Debouncing, throttling, batching
+- <a href="https://github.com/tanstack/query"><b>TanStack Query</b></a> – Async state & caching
+- <a href="https://github.com/tanstack/ranger"><b>TanStack Ranger</b></a> – Range & slider primitives
+- <a href="https://github.com/tanstack/router"><b>TanStack Router</b></a> – Type‑safe routing, caching & URL state
+- <a href="https://github.com/tanstack/router"><b>TanStack Start</b></a> – Full‑stack SSR & streaming
+- <a href="https://github.com/tanstack/store"><b>TanStack Store</b></a> – Reactive data store
+- <a href="https://github.com/tanstack/table"><b>TanStack Table</b></a> – Headless datagrids
+- <a href="https://github.com/tanstack/virtual"><b>TanStack Virtual</b></a> – Virtualized rendering
+
+… and more at <a href="https://tanstack.com"><b>TanStack.com »</b></a>
+
+<!-- USE THE FORCE LUKE -->

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { useChat } from './use-chat.js';
+export type { UseChatOptions, UseChatReturn, UIMessage, ChatRequestBody, } from './types.js';
+export { fetchServerSentEvents, fetchHttpStream, stream, createChatClientOptions, type ConnectionAdapter, type FetchConnectionOptions, type InferChatMessages, } from '@tanstack/ai-client';

package/dist/esm/index.js

@@ -0,0 +1,10 @@
+import { useChat } from "./use-chat.js";
+import { createChatClientOptions, fetchHttpStream, fetchServerSentEvents, stream } from "@tanstack/ai-client";
+export {
+  createChatClientOptions,
+  fetchHttpStream,
+  fetchServerSentEvents,
+  stream,
+  useChat
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/esm/types.d.ts

@@ -0,0 +1,74 @@
+import { AnyClientTool, ModelMessage } from '@tanstack/ai';
+import { ChatClientOptions, ChatRequestBody, UIMessage } from '@tanstack/ai-client';
+export type { UIMessage, ChatRequestBody };
+/**
+ * Options for the useChat hook.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by React state:
+ * - `onMessagesChange` - Managed by React state (exposed as `messages`)
+ * - `onLoadingChange` - Managed by React state (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by React state (exposed as `error`)
+ *
+ * All other callbacks (onResponse, onChunk, onFinish, onError) are
+ * passed through to the underlying ChatClient and can be used for side effects.
+ *
+ * Note: Connection and body changes will recreate the ChatClient instance.
+ * To update these options, remount the component or use a key prop.
+ */
+export type UseChatOptions<TTools extends ReadonlyArray<AnyClientTool> = any> = Omit<ChatClientOptions<TTools>, 'onMessagesChange' | 'onLoadingChange' | 'onErrorChange'>;
+export interface UseChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any> {
+    /**
+     * Current messages in the conversation
+     */
+    messages: Array<UIMessage<TTools>>;
+    /**
+     * Send a message and get a response
+     */
+    sendMessage: (content: string) => Promise<void>;
+    /**
+     * Append a message to the conversation
+     */
+    append: (message: ModelMessage | UIMessage<TTools>) => Promise<void>;
+    /**
+     * Add the result of a client-side tool execution
+     */
+    addToolResult: (result: {
+        toolCallId: string;
+        tool: string;
+        output: any;
+        state?: 'output-available' | 'output-error';
+        errorText?: string;
+    }) => Promise<void>;
+    /**
+     * Respond to a tool approval request
+     */
+    addToolApprovalResponse: (response: {
+        id: string;
+        approved: boolean;
+    }) => Promise<void>;
+    /**
+     * Reload the last assistant message
+     */
+    reload: () => Promise<void>;
+    /**
+     * Stop the current response generation
+     */
+    stop: () => void;
+    /**
+     * Whether a response is currently being generated
+     */
+    isLoading: boolean;
+    /**
+     * Current error, if any
+     */
+    error: Error | undefined;
+    /**
+     * Set messages manually
+     */
+    setMessages: (messages: Array<UIMessage<TTools>>) => void;
+    /**
+     * Clear all messages
+     */
+    clear: () => void;
+}

package/dist/esm/use-chat.d.ts

@@ -0,0 +1,3 @@
+import { AnyClientTool } from '@tanstack/ai';
+import { UseChatOptions, UseChatReturn } from './types.js';
+export declare function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(options: UseChatOptions<TTools>): UseChatReturn<TTools>;

package/dist/esm/use-chat.js

@@ -0,0 +1,115 @@
+import { useId, useState, useRef, useEffect, useMemo, useCallback } from "react";
+import { ChatClient } from "@tanstack/ai-client";
+function useChat(options) {
+  const hookId = useId();
+  const clientId = options.id || hookId;
+  const [messages, setMessages] = useState(
+    options.initialMessages || []
+  );
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(void 0);
+  const messagesRef = useRef(
+    options.initialMessages || []
+  );
+  const isFirstMountRef = useRef(true);
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    messagesRef.current = messages;
+  }, [messages]);
+  optionsRef.current = options;
+  const client = useMemo(() => {
+    const messagesToUse = isFirstMountRef.current ? options.initialMessages || [] : messagesRef.current;
+    isFirstMountRef.current = false;
+    return new ChatClient({
+      connection: optionsRef.current.connection,
+      id: clientId,
+      initialMessages: messagesToUse,
+      body: optionsRef.current.body,
+      onResponse: optionsRef.current.onResponse,
+      onChunk: optionsRef.current.onChunk,
+      onFinish: optionsRef.current.onFinish,
+      onError: optionsRef.current.onError,
+      tools: optionsRef.current.tools,
+      streamProcessor: options.streamProcessor,
+      onMessagesChange: (newMessages) => {
+        setMessages(newMessages);
+      },
+      onLoadingChange: (newIsLoading) => {
+        setIsLoading(newIsLoading);
+      },
+      onErrorChange: (newError) => {
+        setError(newError);
+      }
+    });
+  }, [clientId]);
+  useEffect(() => {
+    if (options.initialMessages && options.initialMessages.length > 0) {
+      if (messages.length === 0) {
+        client.setMessagesManually(options.initialMessages);
+      }
+    }
+  }, []);
+  useEffect(() => {
+    return () => {
+      if (isLoading) {
+        client.stop();
+      }
+    };
+  }, [client, isLoading]);
+  const sendMessage = useCallback(
+    async (content) => {
+      await client.sendMessage(content);
+    },
+    [client]
+  );
+  const append = useCallback(
+    async (message) => {
+      await client.append(message);
+    },
+    [client]
+  );
+  const reload = useCallback(async () => {
+    await client.reload();
+  }, [client]);
+  const stop = useCallback(() => {
+    client.stop();
+  }, [client]);
+  const clear = useCallback(() => {
+    client.clear();
+  }, [client]);
+  const setMessagesManually = useCallback(
+    (newMessages) => {
+      client.setMessagesManually(newMessages);
+    },
+    [client]
+  );
+  const addToolResult = useCallback(
+    async (result) => {
+      await client.addToolResult(result);
+    },
+    [client]
+  );
+  const addToolApprovalResponse = useCallback(
+    async (response) => {
+      await client.addToolApprovalResponse(response);
+    },
+    [client]
+  );
+  return {
+    messages,
+    sendMessage,
+    append,
+    reload,
+    stop,
+    isLoading,
+    error,
+    setMessages: setMessagesManually,
+    clear,
+    addToolResult,
+    addToolApprovalResponse
+  };
+}
+export {
+  useChat
+};
+//# sourceMappingURL=use-chat.js.map

package/dist/esm/use-chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-chat.js","sources":["../../src/use-chat.ts"],"sourcesContent":["import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport { ChatClient } from '@tanstack/ai-client'\nimport type { AnyClientTool, ModelMessage } from '@tanstack/ai'\n\nimport type { UIMessage, UseChatOptions, UseChatReturn } from './types'\n\nexport function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(\n  options: UseChatOptions<TTools>,\n): UseChatReturn<TTools> {\n  const hookId = useId()\n  const clientId = options.id || hookId\n\n  const [messages, setMessages] = useState<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n\n  // Track current messages in a ref to preserve them when client is recreated\n  const messagesRef = useRef<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const isFirstMountRef = useRef(true)\n\n  // Track current options in a ref to avoid recreating client when options change\n  const optionsRef = useRef<UseChatOptions<TTools>>(options)\n\n  // Update ref whenever messages change\n  useEffect(() => {\n    messagesRef.current = messages\n  }, [messages])\n\n  optionsRef.current = options\n\n  // Create ChatClient instance with callbacks to sync state\n  // Note: Options are captured at client creation time.\n  // The connection adapter can use functions for dynamic values (url, headers, etc.)\n  // which are evaluated lazily on each request.\n  const client = useMemo(() => {\n    // On first mount, use initialMessages. On subsequent recreations, preserve existing messages.\n    const messagesToUse = isFirstMountRef.current\n      ? options.initialMessages || []\n      : messagesRef.current\n\n    isFirstMountRef.current = false\n\n    return new ChatClient({\n      connection: optionsRef.current.connection,\n      id: clientId,\n      initialMessages: messagesToUse,\n      body: optionsRef.current.body,\n      onResponse: optionsRef.current.onResponse,\n      onChunk: optionsRef.current.onChunk,\n      onFinish: optionsRef.current.onFinish,\n      onError: optionsRef.current.onError,\n      tools: optionsRef.current.tools,\n      streamProcessor: options.streamProcessor,\n      onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {\n        setMessages(newMessages)\n      },\n      onLoadingChange: (newIsLoading: boolean) => {\n        setIsLoading(newIsLoading)\n      },\n      onErrorChange: (newError: Error | undefined) => {\n        setError(newError)\n      },\n    })\n  }, [clientId])\n\n  // Sync initial messages on mount only\n  // Note: initialMessages are passed to ChatClient constructor, but we also\n  // set them here to ensure React state is in sync\n  useEffect(() => {\n    if (options.initialMessages && options.initialMessages.length > 0) {\n      // Only set if current messages are empty (initial state)\n      if (messages.length === 0) {\n        client.setMessagesManually(options.initialMessages)\n      }\n    }\n  }, []) // Only run on mount - initialMessages are handled by ChatClient constructor\n\n  // Cleanup on unmount: stop any in-flight requests\n  useEffect(() => {\n    return () => {\n      // Stop any active generation when component unmounts\n      if (isLoading) {\n        client.stop()\n      }\n    }\n  }, [client, isLoading])\n\n  // Note: Callback options (onResponse, onChunk, onFinish, onError, onToolCall)\n  // are captured at client creation time. Changes to these callbacks require\n  // remounting the component or changing the connection to recreate the client.\n\n  const sendMessage = useCallback(\n    async (content: string) => {\n      await client.sendMessage(content)\n    },\n    [client],\n  )\n\n  const append = useCallback(\n    async (message: ModelMessage | UIMessage) => {\n      await client.append(message)\n    },\n    [client],\n  )\n\n  const reload = useCallback(async () => {\n    await client.reload()\n  }, [client])\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const clear = useCallback(() => {\n    client.clear()\n  }, [client])\n\n  const setMessagesManually = useCallback(\n    (newMessages: Array<UIMessage<TTools>>) => {\n      client.setMessagesManually(newMessages)\n    },\n    [client],\n  )\n\n  const addToolResult = useCallback(\n    async (result: {\n      toolCallId: string\n      tool: string\n      output: any\n      state?: 'output-available' | 'output-error'\n      errorText?: string\n    }) => {\n      await client.addToolResult(result)\n    },\n    [client],\n  )\n\n  const addToolApprovalResponse = useCallback(\n    async (response: { id: string; approved: boolean }) => {\n      await client.addToolApprovalResponse(response)\n    },\n    [client],\n  )\n\n  return {\n    messages,\n    sendMessage,\n    append,\n    reload,\n    stop,\n    isLoading,\n    error,\n    setMessages: setMessagesManually,\n    clear,\n    addToolResult,\n    addToolApprovalResponse,\n  }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tanstack/ai-react",
+  "version": "0.0.1",
+  "description": "React hooks for TanStack AI",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-react"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "react",
+    "hooks",
+    "tanstack",
+    "chat",
+    "streaming"
+  ],
+  "dependencies": {
+    "@tanstack/ai": "0.0.1",
+    "@tanstack/ai-client": "0.0.1"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.7",
+    "@vitest/coverage-v8": "4.0.14",
+    "jsdom": "^27.2.0",
+    "vite": "^7.2.4",
+    "zod": "^4.1.13"
+  },
+  "peerDependencies": {
+    "@types/react": ">=18.0.0",
+    "react": ">=18.0.0",
+    "@tanstack/ai": "0.0.1",
+    "@tanstack/ai-client": "0.0.1"
+  },
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "test:build": "publint --strict",
+    "build": "vite build"
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { useChat } from './use-chat'
+export type {
+  UseChatOptions,
+  UseChatReturn,
+  UIMessage,
+  ChatRequestBody,
+} from './types'
+
+// Re-export from ai-client for convenience
+export {
+  fetchServerSentEvents,
+  fetchHttpStream,
+  stream,
+  createChatClientOptions,
+  type ConnectionAdapter,
+  type FetchConnectionOptions,
+  type InferChatMessages,
+} from '@tanstack/ai-client'

package/src/types.ts

@@ -0,0 +1,101 @@
+import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+import type {
+  ChatClientOptions,
+  ChatRequestBody,
+  UIMessage,
+} from '@tanstack/ai-client'
+
+// Re-export types from ai-client
+export type { UIMessage, ChatRequestBody }
+
+/**
+ * Options for the useChat hook.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by React state:
+ * - `onMessagesChange` - Managed by React state (exposed as `messages`)
+ * - `onLoadingChange` - Managed by React state (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by React state (exposed as `error`)
+ *
+ * All other callbacks (onResponse, onChunk, onFinish, onError) are
+ * passed through to the underlying ChatClient and can be used for side effects.
+ *
+ * Note: Connection and body changes will recreate the ChatClient instance.
+ * To update these options, remount the component or use a key prop.
+ */
+export type UseChatOptions<TTools extends ReadonlyArray<AnyClientTool> = any> =
+  Omit<
+    ChatClientOptions<TTools>,
+    'onMessagesChange' | 'onLoadingChange' | 'onErrorChange'
+  >
+
+export interface UseChatReturn<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> {
+  /**
+   * Current messages in the conversation
+   */
+  messages: Array<UIMessage<TTools>>
+
+  /**
+   * Send a message and get a response
+   */
+  sendMessage: (content: string) => Promise<void>
+
+  /**
+   * Append a message to the conversation
+   */
+  append: (message: ModelMessage | UIMessage<TTools>) => Promise<void>
+
+  /**
+   * Add the result of a client-side tool execution
+   */
+  addToolResult: (result: {
+    toolCallId: string
+    tool: string
+    output: any
+    state?: 'output-available' | 'output-error'
+    errorText?: string
+  }) => Promise<void>
+
+  /**
+   * Respond to a tool approval request
+   */
+  addToolApprovalResponse: (response: {
+    id: string // approval.id, not toolCallId
+    approved: boolean
+  }) => Promise<void>
+
+  /**
+   * Reload the last assistant message
+   */
+  reload: () => Promise<void>
+
+  /**
+   * Stop the current response generation
+   */
+  stop: () => void
+
+  /**
+   * Whether a response is currently being generated
+   */
+  isLoading: boolean
+
+  /**
+   * Current error, if any
+   */
+  error: Error | undefined
+
+  /**
+   * Set messages manually
+   */
+  setMessages: (messages: Array<UIMessage<TTools>>) => void
+
+  /**
+   * Clear all messages
+   */
+  clear: () => void
+}
+
+// Note: createChatClientOptions and InferChatMessages are now in @tanstack/ai-client
+// and re-exported from there for convenience

package/src/use-chat.ts

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
+import { ChatClient } from '@tanstack/ai-client'
+import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+
+import type { UIMessage, UseChatOptions, UseChatReturn } from './types'
+
+export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
+  options: UseChatOptions<TTools>,
+): UseChatReturn<TTools> {
+  const hookId = useId()
+  const clientId = options.id || hookId
+
+  const [messages, setMessages] = useState<Array<UIMessage<TTools>>>(
+    options.initialMessages || [],
+  )
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<Error | undefined>(undefined)
+
+  // Track current messages in a ref to preserve them when client is recreated
+  const messagesRef = useRef<Array<UIMessage<TTools>>>(
+    options.initialMessages || [],
+  )
+  const isFirstMountRef = useRef(true)
+
+  // Track current options in a ref to avoid recreating client when options change
+  const optionsRef = useRef<UseChatOptions<TTools>>(options)
+
+  // Update ref whenever messages change
+  useEffect(() => {
+    messagesRef.current = messages
+  }, [messages])
+
+  optionsRef.current = options
+
+  // Create ChatClient instance with callbacks to sync state
+  // Note: Options are captured at client creation time.
+  // The connection adapter can use functions for dynamic values (url, headers, etc.)
+  // which are evaluated lazily on each request.
+  const client = useMemo(() => {
+    // On first mount, use initialMessages. On subsequent recreations, preserve existing messages.
+    const messagesToUse = isFirstMountRef.current
+      ? options.initialMessages || []
+      : messagesRef.current
+
+    isFirstMountRef.current = false
+
+    return new ChatClient({
+      connection: optionsRef.current.connection,
+      id: clientId,
+      initialMessages: messagesToUse,
+      body: optionsRef.current.body,
+      onResponse: optionsRef.current.onResponse,
+      onChunk: optionsRef.current.onChunk,
+      onFinish: optionsRef.current.onFinish,
+      onError: optionsRef.current.onError,
+      tools: optionsRef.current.tools,
+      streamProcessor: options.streamProcessor,
+      onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {
+        setMessages(newMessages)
+      },
+      onLoadingChange: (newIsLoading: boolean) => {
+        setIsLoading(newIsLoading)
+      },
+      onErrorChange: (newError: Error | undefined) => {
+        setError(newError)
+      },
+    })
+  }, [clientId])
+
+  // Sync initial messages on mount only
+  // Note: initialMessages are passed to ChatClient constructor, but we also
+  // set them here to ensure React state is in sync
+  useEffect(() => {
+    if (options.initialMessages && options.initialMessages.length > 0) {
+      // Only set if current messages are empty (initial state)
+      if (messages.length === 0) {
+        client.setMessagesManually(options.initialMessages)
+      }
+    }
+  }, []) // Only run on mount - initialMessages are handled by ChatClient constructor
+
+  // Cleanup on unmount: stop any in-flight requests
+  useEffect(() => {
+    return () => {
+      // Stop any active generation when component unmounts
+      if (isLoading) {
+        client.stop()
+      }
+    }
+  }, [client, isLoading])
+
+  // Note: Callback options (onResponse, onChunk, onFinish, onError, onToolCall)
+  // are captured at client creation time. Changes to these callbacks require
+  // remounting the component or changing the connection to recreate the client.
+
+  const sendMessage = useCallback(
+    async (content: string) => {
+      await client.sendMessage(content)
+    },
+    [client],
+  )
+
+  const append = useCallback(
+    async (message: ModelMessage | UIMessage) => {
+      await client.append(message)
+    },
+    [client],
+  )
+
+  const reload = useCallback(async () => {
+    await client.reload()
+  }, [client])
+
+  const stop = useCallback(() => {
+    client.stop()
+  }, [client])
+
+  const clear = useCallback(() => {
+    client.clear()
+  }, [client])
+
+  const setMessagesManually = useCallback(
+    (newMessages: Array<UIMessage<TTools>>) => {
+      client.setMessagesManually(newMessages)
+    },
+    [client],
+  )
+
+  const addToolResult = useCallback(
+    async (result: {
+      toolCallId: string
+      tool: string
+      output: any
+      state?: 'output-available' | 'output-error'
+      errorText?: string
+    }) => {
+      await client.addToolResult(result)
+    },
+    [client],
+  )
+
+  const addToolApprovalResponse = useCallback(
+    async (response: { id: string; approved: boolean }) => {
+      await client.addToolApprovalResponse(response)
+    },
+    [client],
+  )
+
+  return {
+    messages,
+    sendMessage,
+    append,
+    reload,
+    stop,
+    isLoading,
+    error,
+    setMessages: setMessagesManually,
+    clear,
+    addToolResult,
+    addToolApprovalResponse,
+  }
+}