Open History to see the last commit
1import { ChatClient } from '@tanstack/ai-client'
2import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'
3import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
4import type {
5 AnyClientTool,
6 InferSchemaType,
7 ModelMessage,
8 RunAgentResumeItem,
9 SchemaInput,
10 StreamChunk,
11} from '@tanstack/ai/client'
12import type {
13 ChatClientState,
14 ChatInterrupt,
15 ChatInterruptState,
16 ChatResumeState,
17 ConnectionStatus,
18 InferredClientContext,
19 QueuedMessage,
20 SendMessageOptions,
21 StructuredOutputPart,
22} from '@tanstack/ai-client'
23
24import type {
25 DeepPartial,
26 MultimodalContent,
27 UIMessage,
28 UseChatOptions,
29 UseChatReturn,
30} from './types'
31
32const EMPTY_INTERRUPTS = Object.freeze([])
33const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
34
35export function useChat<
36 const TTools extends ReadonlyArray<AnyClientTool> = any,
37 TSchema extends SchemaInput | undefined = undefined,
38 TContext = InferredClientContext<TTools>,
39>(
40 options: UseChatOptions<TTools, TSchema, TContext>,
41): UseChatReturn<TTools, TSchema> {
42 // The hook's identity is its `threadId` — also the persistence key, so a
43 // reload with the same `threadId` restores the same conversation. `hookId` is
44 // only a stable fallback for React's client-recreation keying when no
45 // `threadId` is given (an ephemeral chat), never a persistence key.
46 const hookId = useId()
47 const clientId = options.threadId ?? hookId
48
49 const [messages, setMessages] = useState<Array<UIMessage<TTools>>>(
50 options.initialMessages || [],
51 )
52 const [isLoading, setIsLoading] = useState(false)
53 const [error, setError] = useState<Error | undefined>(undefined)
54 const [status, setStatus] = useState<ChatClientState>('ready')
55 const [isSubscribed, setIsSubscribed] = useState(false)
56 const [connectionStatus, setConnectionStatus] =
57 useState<ConnectionStatus>('disconnected')
58 const [sessionGenerating, setSessionGenerating] = useState(false)
59 const [queue, setQueue] = useState<Array<QueuedMessage>>([])
60 const [runId, setRunId] = useState<string | null>(null)
61 const [interruptState, setInterruptState] = useState<
62 ChatInterruptState<TTools>
63 >(() => ({
64 interrupts: EMPTY_INTERRUPTS,
65 pendingInterrupts: EMPTY_INTERRUPTS,
66 interruptErrors: EMPTY_INTERRUPT_ERRORS,
67 resuming: false,
68 }))
69
70 type Partial = DeepPartial<InferSchemaType<NonNullable<TSchema>>>
71 type Final = InferSchemaType<NonNullable<TSchema>>
72
73 // Track current messages in a ref to preserve them when client is recreated
74 const messagesRef = useRef<Array<UIMessage<TTools>>>(
75 options.initialMessages || [],
76 )
77 const isFirstMountRef = useRef(true)
78 const subscribedRef = useRef(false)
79 const activeClientRef = useRef<ChatClient | null>(null)
80 const cleanupInvalidationRef = useRef<ReturnType<typeof setTimeout> | null>(
81 null,
82 )
83 const cleanupDisposalRef = useRef<{
84 client: ChatClient
85 timeout: ReturnType<typeof setTimeout>
86 } | null>(null)
87
88 // Update ref synchronously during render so it's always current when useMemo runs.
89 messagesRef.current = messages
90
91 // Track current options in a ref to avoid recreating client when options change
92 const optionsRef = useRef<UseChatOptions<TTools, TSchema, TContext>>(options)
93 optionsRef.current = options
94
95 const syncResumeState = useCallback((target: ChatClient | null) => {
96 if (!target) return
97 setRunId(target.getCurrentRunId())
98 setInterruptState(target.getInterruptState())
99 }, [])
100
101 // Create ChatClient instance with callbacks to sync state
102 const client = useMemo(() => {
103 const messagesToUse = options.initialMessages || []
104 isFirstMountRef.current = false
105
106 // Build options with conditional spreads for fields whose source
107 // type is `T | undefined` but the ChatClient target uses a strict
108 // optional (`field?: T`) — `exactOptionalPropertyTypes` rejects
109 // assigning `undefined` to those, so we omit the key when absent.
110 const initialOptions = optionsRef.current
111 const transport = initialOptions.connection
112 ? { connection: initialOptions.connection }
113 : { fetcher: initialOptions.fetcher }
114
115 const instanceHolder: {
116 current: ChatClient<TTools, TContext> | undefined
117 } = { current: undefined }
118 const getActiveInstance = () => {
119 const currentInstance = instanceHolder.current
120 if (!currentInstance || activeClientRef.current !== currentInstance) {
121 return undefined
122 }
123 return currentInstance
124 }
125 const pendingInitializationErrors: Array<Error> = []
126 const instance = new ChatClient<TTools, TContext>({
127 devtoolsBridgeFactory: createChatDevtoolsBridge,
128 ...transport,
129 initialMessages: messagesToUse,
130 ...(initialOptions.body !== undefined && { body: initialOptions.body }),
131 ...(initialOptions.threadId !== undefined && {
132 threadId: initialOptions.threadId,
133 }),
134 ...(initialOptions.forwardedProps !== undefined && {
135 forwardedProps: initialOptions.forwardedProps,
136 }),
137 ...(initialOptions.persistence !== undefined && {
138 persistence: initialOptions.persistence,
139 }),
140 ...(initialOptions.initialResumeSnapshot !== undefined && {
141 initialResumeSnapshot: initialOptions.initialResumeSnapshot,
142 }),
143 ...(initialOptions.context !== undefined && {
144 context: initialOptions.context,
145 }),
146 devtools: {
147 ...initialOptions.devtools,
148 framework: 'react',
149 hookName: 'useChat',
150 outputKind: initialOptions.outputSchema ? 'structured' : 'chat',
151 },
152 onResponse: (response) => {
153 if (!getActiveInstance()) return
154 void optionsRef.current.onResponse?.(response)
155 },
156 onChunk: (chunk: StreamChunk) => {
157 if (!getActiveInstance()) return
158 optionsRef.current.onChunk?.(chunk)
159 },
160 onFinish: (message: UIMessage<TTools>) => {
161 if (!getActiveInstance()) return
162 optionsRef.current.onFinish?.(message)
163 },
164 onError: (error: Error) => {
165 const currentInstance = instanceHolder.current
166 if (!currentInstance) {
167 pendingInitializationErrors.push(error)
168 return
169 }
170 if (activeClientRef.current !== currentInstance) return
171 optionsRef.current.onError?.(error)
172 },
173 ...(initialOptions.tools !== undefined && {
174 tools: initialOptions.tools,
175 }),
176 onCustomEvent: (eventType, data, context) => {
177 if (!getActiveInstance()) return
178 optionsRef.current.onCustomEvent?.(eventType, data, context)
179 },
180 ...(options.streamProcessor !== undefined && {
181 streamProcessor: options.streamProcessor,
182 }),
183 onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {
184 if (!getActiveInstance()) return
185 setMessages(newMessages)
186 },
187 onLoadingChange: (newIsLoading: boolean) => {
188 const currentInstance = getActiveInstance()
189 if (!currentInstance) return
190 setIsLoading(newIsLoading)
191 syncResumeState(currentInstance)
192 },
193 onErrorChange: (newError: Error | undefined) => {
194 if (!getActiveInstance()) return
195 setError(newError)
196 },
197 onStatusChange: (status: ChatClientState) => {
198 if (!getActiveInstance()) return
199 setStatus(status)
200 },
201 onSubscriptionChange: (nextIsSubscribed: boolean) => {
202 if (!getActiveInstance()) return
203 setIsSubscribed(nextIsSubscribed)
204 },
205 onConnectionStatusChange: (nextStatus: ConnectionStatus) => {
206 if (!getActiveInstance()) return
207 setConnectionStatus(nextStatus)
208 },
209 onSessionGeneratingChange: (isGenerating: boolean) => {
210 if (!getActiveInstance()) return
211 setSessionGenerating(isGenerating)
212 },
213 ...(optionsRef.current.queue !== undefined && {
214 queue: optionsRef.current.queue,
215 }),
216 onQueueChange: (nextQueue: Array<QueuedMessage>) => {
217 if (activeClientRef.current !== instance) return
218 setQueue(nextQueue)
219 },
220 onRunIdChange: (nextRunId) => {
221 if (!getActiveInstance()) return
222 setRunId(nextRunId)
223 },
224 onResumeStateChange: (_nextResumeState, nextPendingInterrupts) => {
225 if (!getActiveInstance()) return
226 setInterruptState((current) => ({
227 ...current,
228 interrupts: nextPendingInterrupts,
229 pendingInterrupts: nextPendingInterrupts,
230 }))
231 },
232 onInterruptStateChange: (nextInterruptState) => {
233 if (!getActiveInstance()) return
234 setInterruptState(nextInterruptState)
235 optionsRef.current.onInterruptStateChange?.(nextInterruptState)
236 },
237 })
238 instanceHolder.current = instance
239 activeClientRef.current = instance
240 for (const error of pendingInitializationErrors) {
241 if (activeClientRef.current !== instance) break
242 optionsRef.current.onError?.(error)
243 }
244 return instance
245 }, [clientId, syncResumeState])
246
247 useEffect(() => {
248 const clientMessages = client.getMessages()
249 if (clientMessages !== messagesRef.current) {
250 setMessages(clientMessages)
251 }
252 }, [client])
253
254 // Sync each wire-payload slot in its own effect so an unrelated option
255 // changing doesn't re-run the others. `updateOptions` declares strict-optional
256 // fields and rejects explicit `undefined` under EOPT, so guard the optional
257 // slots before passing them.
258 useEffect(() => {
259 client.updateOptions({ body: options.body })
260 }, [client, options.body])
261
262 useEffect(() => {
263 if (options.forwardedProps !== undefined) {
264 client.updateOptions({ forwardedProps: options.forwardedProps })
265 }
266 }, [client, options.forwardedProps])
267
268 useEffect(() => {
269 if (options.tools !== undefined) {
270 client.updateOptions({ tools: options.tools })
271 }
272 }, [client, options.tools])
273
274 useEffect(() => {
275 client.updateOptions({ context: options.context })
276 }, [client, options.context])
277
278 useEffect(() => {
279 if (options.queue !== undefined) {
280 client.updateOptions({ queue: options.queue })
281 }
282 }, [client, options.queue])
283
284 useEffect(() => {
285 if (options.live) {
286 client.subscribe()
287 subscribedRef.current = true
288 } else if (subscribedRef.current) {
289 // Only tear down a subscription we actually started. Calling
290 // `unsubscribe()` on initial mount (when `live` was never enabled) would
291 // abort an in-flight delivery resume — `resumeInFlightRun` is kicked off
292 // in the client constructor, and `unsubscribe()` cancels the shared
293 // in-flight stream — so a mid-stream reload would drop its rejoin before
294 // it delivers a single chunk. This is exactly why a reload froze instead
295 // of continuing.
296 client.unsubscribe()
297 subscribedRef.current = false
298 }
299 }, [client, options.live])
300
301 // ONLY THE VIEW ON SCREEN HOLDS A STREAM.
302 //
303 // A page can own many chats — 40 sandboxes, 40 conversations — and a browser
304 // allows only ~6 connections per origin. One long-lived stream per chat reaches
305 // that ceiling after a handful of views, and every request after it QUEUES:
306 // measured, an in-page fetch took over two minutes while the same request from
307 // outside the browser took 17ms. So the connection follows the view.
308 //
309 // Immediate, not deferred: the deferred teardown below can be skipped when the
310 // same client remounts, which is right for disposal but useless for a
311 // connection. `attach` is idempotent and `detach` keeps the transcript and the
312 // resume pointer, so a Strict Mode remount is just detach-then-attach and the
313 // run is picked straight back up from the durable log.
314 useEffect(() => {
315 client.attach()
316 return () => {
317 client.detach()
318 }
319 }, [client])
320
321 useEffect(() => {
322 if (cleanupDisposalRef.current?.client === client) {
323 clearTimeout(cleanupDisposalRef.current.timeout)
324 cleanupDisposalRef.current = null
325 }
326 if (cleanupInvalidationRef.current) {
327 clearTimeout(cleanupInvalidationRef.current)
328 cleanupInvalidationRef.current = null
329 }
330 activeClientRef.current = client
331 client.mountDevtools()
332 // Delivery-durability resume is transparent: the resumable SSE connection
333 // adapter re-attaches via the browser's native Last-Event-ID on reconnect.
334 // We only seed interrupt (state) resume from the client here.
335 syncResumeState(client)
336
337 return () => {
338 cleanupInvalidationRef.current = setTimeout(() => {
339 if (activeClientRef.current === client) {
340 activeClientRef.current = null
341 }
342 cleanupInvalidationRef.current = null
343 }, 0)
344 // Soft cleanup only: do NOT stop/unsubscribe here. React Strict Mode
345 // remounts fire this cleanup then re-attach the same client one tick
346 // later; calling `stop()` would abort a constructor rejoin
347 // (`resumeInFlightRun`) and can wipe the durable resume pointer before
348 // the first chunk. Real teardown lives in the deferred dispose path
349 // below, which only runs when the client is not remounted.
350 // Subscribe/unsubscribe on `options.live` is still owned by the
351 // dedicated effect above for live toggles.
352 const disposal = {
353 client,
354 timeout: setTimeout(() => {
355 if (optionsRef.current.live) {
356 client.unsubscribe()
357 } else {
358 client.stop()
359 }
360 client.dispose()
361 if (cleanupDisposalRef.current === disposal) {
362 cleanupDisposalRef.current = null
363 }
364 }, 0),
365 }
366 cleanupDisposalRef.current = disposal
367 }
368 }, [client, syncResumeState])
369
370 const sendMessage = useCallback(
371 async (
372 content: string | MultimodalContent,
373 sendOptions?: SendMessageOptions,
374 ) => {
375 try {
376 await client.sendMessage(content, undefined, sendOptions)
377 } finally {
378 syncResumeState(client)
379 }
380 },
381 [client, syncResumeState],
382 )
383
384 const cancelQueued = useCallback(
385 (id: string) => {
386 client.cancelQueued(id)
387 },
388 [client, syncResumeState],
389 )
390
391 const append = useCallback(
392 async (message: ModelMessage | UIMessage) => {
393 try {
394 await client.append(message)
395 } finally {
396 syncResumeState(client)
397 }
398 },
399 [client, syncResumeState],
400 )
401
402 const reload = useCallback(async () => {
403 try {
404 await client.reload()
405 } finally {
406 syncResumeState(client)
407 }
408 }, [client, syncResumeState])
409
410 const stop = useCallback(() => {
411 client.stop()
412 }, [client])
413
414 const clear = useCallback(() => {
415 client.clear()
416 syncResumeState(client)
417 }, [client, syncResumeState])
418
419 const setMessagesManually = useCallback(
420 (newMessages: Array<UIMessage<TTools>>) => {
421 client.setMessagesManually(newMessages)
422 },
423 [client],
424 )
425
426 const addToolResult = useCallback(
427 async (result: {
428 toolCallId: string
429 tool: string
430 output: any
431 state?: 'output-available' | 'output-error'
432 errorText?: string
433 }) => {
434 await client.addToolResult(result)
435 },
436 [client],
437 )
438
439 const addToolApprovalResponse = useCallback(
440 async (response: { id: string; approved: boolean }) => {
441 await client.addToolApprovalResponse(response)
442 syncResumeState(client)
443 },
444 [client, syncResumeState],
445 )
446
447 const resumeInterrupts = useCallback(
448 async (resumeItems: Array<RunAgentResumeItem>, state?: ChatResumeState) => {
449 const result = await client.resumeInterrupts(
450 resumeItems,
451 state ?? undefined,
452 )
453 syncResumeState(client)
454 return result
455 },
456 [client, syncResumeState],
457 )
458
459 const resolveInterrupts = useCallback(
460 (
461 resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
462 ) => {
463 if (typeof resolution === 'boolean') {
464 client.resolveInterrupts(resolution)
465 } else {
466 client.resolveInterrupts(resolution)
467 }
468 },
469 [client],
470 )
471
472 const cancelInterrupts = useCallback(() => {
473 client.cancelInterrupts()
474 }, [client])
475
476 const retryInterrupts = useCallback(() => {
477 client.retryInterrupts()
478 }, [client])
479
480 const resumeInterruptsUnsafe = useCallback(
481 (resumeItems: Array<RunAgentResumeItem>, state?: ChatResumeState) =>
482 client.resumeInterruptsUnsafe(resumeItems, state),
483 [client],
484 )
485
486 // The "active" structured-output part is the one on the assistant message
487 // that follows the latest user message. No such message exists between
488 // sendMessage() and the first chunk, so partial/final naturally read as
489 // cleared. Historical parts on earlier assistant messages remain available
490 // via `messages` directly.
491 //
492 // When there is NO user message yet (e.g. `initialMessages` contains only
493 // a stale assistant turn or a system prompt) we deliberately return null
494 // rather than scanning historical assistants — otherwise a `final` from a
495 // previous session would leak into the hook value on first render.
496 const renderedMessages = client.getMessages()
497
498 const activeStructuredPart = useMemo<StructuredOutputPart | null>(() => {
499 let lastUserIndex = -1
500 for (let i = renderedMessages.length - 1; i >= 0; i--) {
501 if (renderedMessages[i]?.role === 'user') {
502 lastUserIndex = i
503 break
504 }
505 }
506 if (lastUserIndex === -1) return null
507 for (let i = renderedMessages.length - 1; i > lastUserIndex; i--) {
508 const m = renderedMessages[i]
509 if (m?.role !== 'assistant') continue
510 const part = m.parts.find(
511 (p): p is StructuredOutputPart => p.type === 'structured-output',
512 )
513 if (part) return part
514 }
515 return null
516 }, [renderedMessages])
517
518 const partial = useMemo<Partial>(() => {
519 if (!activeStructuredPart) return {} as Partial
520 const v = activeStructuredPart.partial ?? activeStructuredPart.data
521 return (v ?? {}) as Partial
522 }, [activeStructuredPart])
523
524 const final = useMemo<Final | null>(() => {
525 if (!activeStructuredPart || activeStructuredPart.status !== 'complete') {
526 return null
527 }
528 return activeStructuredPart.data as Final
529 }, [activeStructuredPart])
530
531 // The runtime shape unconditionally exposes partial/final; the public
532 // return type hides them when no outputSchema was supplied. TS can't
533 // structurally narrow across that conditional, so the `as` is the seam.
534 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- hook return shape diverges from generic UseChatReturn<TTools, TSchema> due to conditional type on TSchema; TS can't structurally narrow
535 return {
536 messages: renderedMessages,
537 sendMessage,
538 append,
539 reload,
540 stop,
541 isLoading,
542 error,
543 status,
544 isSubscribed,
545 connectionStatus,
546 sessionGenerating,
547 setMessages: setMessagesManually,
548 clear,
549 addToolResult,
550 addToolApprovalResponse,
551 queue,
552 cancelQueued,
553 runId,
554 interrupts: interruptState.interrupts,
555 pendingInterrupts: interruptState.pendingInterrupts,
556 interruptErrors: interruptState.interruptErrors,
557 resuming: interruptState.resuming,
558 resolveInterrupts,
559 cancelInterrupts,
560 retryInterrupts,
561 resumeInterruptsUnsafe,
562 resumeInterrupts,
563 partial,
564 final,
565 } as unknown as UseChatReturn<TTools, TSchema>
566}