@tanstack/ai-octane 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tanstack/ai-octane",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "Octane bindings for TanStack AI streaming chat, structured outputs, and media generation.",
5
5
  "author": "Dominic Gannaway",
6
6
  "license": "MIT",
@@ -48,11 +48,11 @@
48
48
  ],
49
49
  "//lint": "The .tsrx.d.ts companions are generated declaration emits of the .tsrx implementations, so they are not hand-formatted and are excluded from lint rather than edited in place (a regeneration would undo any fix).",
50
50
  "dependencies": {
51
- "@tanstack/ai-client": "0.39.3"
51
+ "@tanstack/ai-client": "0.40.0"
52
52
  },
53
53
  "peerDependencies": {
54
54
  "octane": ">=0.12.0",
55
- "@tanstack/ai": "^0.69.0"
55
+ "@tanstack/ai": "^0.70.0"
56
56
  },
57
57
  "devDependencies": {
58
58
  "@octanejs/testing-library": "0.1.62",
@@ -64,7 +64,7 @@
64
64
  "octane": "0.12.1",
65
65
  "vite": "^8.2.1",
66
66
  "zod": "^4.2.0",
67
- "@tanstack/ai": "0.69.0"
67
+ "@tanstack/ai": "0.70.0"
68
68
  },
69
69
  "scripts": {
70
70
  "lint:fix": "oxlint src --type-aware --fix",
@@ -104,7 +104,7 @@ export interface UseRealtimeChatReturn {
104
104
  /** Current mode (idle, listening, thinking, speaking) */
105
105
  mode: RealtimeMode
106
106
  /** Conversation messages */
107
- messages: Array<RealtimeMessage>
107
+ messages: ReadonlyArray<RealtimeMessage>
108
108
  /** User transcript while speaking (before finalized) */
109
109
  pendingUserTranscript: string | null
110
110
  /** Assistant transcript while speaking (before finalized) */
package/src/types.ts CHANGED
@@ -162,7 +162,7 @@ interface BaseUseChatReturn<
162
162
  * `messages[i].parts.find(p => p.type === 'structured-output')` is typed
163
163
  * with the schema's inferred shape — `data: T`, `partial: DeepPartial<T>`.
164
164
  */
165
- messages: Array<UIMessage<TTools, TData>>
165
+ messages: ReadonlyArray<UIMessage<TTools, TData>>
166
166
 
167
167
  /**
168
168
  * Send a message and get a response.
@@ -181,7 +181,7 @@ interface BaseUseChatReturn<
181
181
  * Pending messages queued while the client is busy (streaming, claiming a
182
182
  * send, or draining). Separate from `messages` until they drain.
183
183
  */
184
- queue: Array<QueuedMessage>
184
+ queue: ReadonlyArray<QueuedMessage>
185
185
 
186
186
  /**
187
187
  * Cancel a queued message before it drains. No-op if already sent.
@@ -313,7 +313,7 @@ interface BaseUseChatReturn<
313
313
  /**
314
314
  * Set messages manually
315
315
  */
316
- setMessages: (messages: Array<UIMessage<TTools, TData>>) => void
316
+ setMessages: (messages: ReadonlyArray<UIMessage<TTools, TData>>) => void
317
317
 
318
318
  /**
319
319
  * Clear all messages
package/src/use-chat.tsrx CHANGED
@@ -11,13 +11,9 @@ import type {
11
11
  StreamChunk,
12
12
  } from '@tanstack/ai/client'
13
13
  import type {
14
- ChatClientState,
15
14
  ResolvableChatInterrupt,
16
- ChatInterruptState,
17
15
  ChatResumeState,
18
- ConnectionStatus,
19
16
  InferredClientContext,
20
- QueuedMessage,
21
17
  SendMessageOptions,
22
18
  StructuredOutputPart,
23
19
  } from '@tanstack/ai-client'
@@ -30,9 +26,6 @@ import type {
30
26
  UseChatReturn,
31
27
  } from './types'
32
28
 
33
- const EMPTY_INTERRUPTS = Object.freeze([])
34
- const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
35
-
36
29
  export function useChat<
37
30
  const TTools extends ReadonlyArray<AnyClientTool> = any,
38
31
  TSchema extends SchemaInput | undefined = undefined,
@@ -49,54 +42,13 @@ export function useChat<
49
42
  const hookId = useId()
50
43
  const clientId = options.threadId ?? hookId
51
44
 
52
- const [messages, setMessages] = useState<Array<UIMessage<TTools>>>(
53
- options.initialMessages || [],
54
- )
55
- const [isLoading, setIsLoading] = useState(false)
56
- const [hasOlderMessages, setHasOlderMessages] = useState(false)
57
- const [error, setError] = useState<Error | undefined>(undefined)
58
- const [status, setStatus] = useState<ChatClientState>('ready')
59
- const [isSubscribed, setIsSubscribed] = useState(false)
60
- const [connectionStatus, setConnectionStatus] =
61
- useState<ConnectionStatus>('disconnected')
62
- const [sessionGenerating, setSessionGenerating] = useState(false)
63
- const [queue, setQueue] = useState<Array<QueuedMessage>>([])
64
- const [runId, setRunId] = useState<string | null>(null)
65
- const [interruptState, setInterruptState] = useState<
66
- ChatInterruptState<TTools, TInterrupts>
67
- >(() => ({
68
- interrupts: EMPTY_INTERRUPTS,
69
- pendingInterrupts: EMPTY_INTERRUPTS,
70
- interruptErrors: EMPTY_INTERRUPT_ERRORS,
71
- resuming: false,
72
- }))
73
-
74
- type Partial = DeepPartial<InferSchemaType<NonNullable<TSchema>>>
75
- type Final = InferSchemaType<NonNullable<TSchema>>
76
-
77
- // Track the rendered snapshot so a replacement client only synchronizes
78
- // state when its messages actually differ.
79
- const messagesRef = useRef<Array<UIMessage<TTools>>>(
80
- options.initialMessages || [],
81
- )
82
45
  const subscribedRef = useRef(false)
83
46
  const activeClientRef = useRef<ChatClient | null>(null)
84
47
  const seenClientRef = useRef<ChatClient | null>(null)
85
-
86
- // Update ref synchronously during render so it's always current when useMemo runs.
87
- messagesRef.current = messages
88
-
89
- // Track current options in a ref to avoid recreating client when options change
90
48
  const optionsRef =
91
49
  useRef<UseChatOptions<TTools, TSchema, TContext, TInterrupts>>(options)
92
50
  optionsRef.current = options
93
51
 
94
- const syncResumeState = useCallback((target: ChatClient | null) => {
95
- if (!target) return
96
- setRunId(target.getCurrentRunId())
97
- setInterruptState(target.getInterruptState())
98
- }, [])
99
-
100
52
  // Create ChatClient instance with callbacks to sync state
101
53
  const { client, initialization } = useMemo(() => {
102
54
  const messagesToUse = options.initialMessages || []
@@ -213,77 +165,11 @@ export function useChat<
213
165
  ...(options.streamProcessor !== undefined && {
214
166
  streamProcessor: options.streamProcessor,
215
167
  }),
216
- onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {
217
- runOrQueueForActiveInstance(() => {
218
- setMessages(newMessages)
219
- const currentInstance = getActiveInstance()
220
- if (!currentInstance) return
221
- setHasOlderMessages(currentInstance.getHasOlderMessages())
222
- })
223
- },
224
- onLoadingChange: (newIsLoading: boolean) => {
225
- runOrQueueForActiveInstance(() => {
226
- const currentInstance = getActiveInstance()
227
- if (!currentInstance) return
228
- setIsLoading(newIsLoading)
229
- syncResumeState(currentInstance)
230
- })
231
- },
232
- onErrorChange: (newError: Error | undefined) => {
233
- runOrQueueForActiveInstance(() => {
234
- setError(newError)
235
- })
236
- },
237
- onStatusChange: (status: ChatClientState) => {
238
- runOrQueueForActiveInstance(() => {
239
- setStatus(status)
240
- })
241
- },
242
- onSubscriptionChange: (nextIsSubscribed: boolean) => {
243
- runOrQueueForActiveInstance(() => {
244
- setIsSubscribed(nextIsSubscribed)
245
- })
246
- },
247
- onConnectionStatusChange: (nextStatus: ConnectionStatus) => {
248
- runOrQueueForActiveInstance(() => {
249
- setConnectionStatus(nextStatus)
250
- })
251
- },
252
- onSessionGeneratingChange: (isGenerating: boolean) => {
253
- runOrQueueForActiveInstance(() => {
254
- setSessionGenerating(isGenerating)
255
- })
256
- },
257
- onHydratingChange: (nextIsHydrating: boolean) => {
258
- runOrQueueForActiveInstance(() => {
259
- setHydration({ client: instance, value: nextIsHydrating })
260
- })
261
- },
262
168
  ...(optionsRef.current.queue !== undefined && {
263
169
  queue: optionsRef.current.queue,
264
170
  }),
265
- onQueueChange: (nextQueue: Array<QueuedMessage>) => {
266
- runOrQueueForActiveInstance(() => {
267
- setQueue(nextQueue)
268
- })
269
- },
270
- onRunIdChange: (nextRunId) => {
271
- runOrQueueForActiveInstance(() => {
272
- setRunId(nextRunId)
273
- })
274
- },
275
- onResumeStateChange: (_nextResumeState, nextPendingInterrupts) => {
276
- runOrQueueForActiveInstance(() => {
277
- setInterruptState((current) => ({
278
- ...current,
279
- interrupts: nextPendingInterrupts,
280
- pendingInterrupts: nextPendingInterrupts,
281
- }))
282
- })
283
- },
284
171
  onInterruptStateChange: (nextInterruptState, context) => {
285
172
  runOrQueueForActiveInstance(() => {
286
- setInterruptState(nextInterruptState)
287
173
  optionsRef.current.onInterruptStateChange?.(
288
174
  nextInterruptState,
289
175
  context,
@@ -293,18 +179,21 @@ export function useChat<
293
179
  })
294
180
  instanceHolder.current = instance
295
181
  return { client: instance, initialization: initializationState }
296
- }, [clientId, syncResumeState])
182
+ }, [clientId])
183
+
184
+ type Partial = DeepPartial<InferSchemaType<NonNullable<TSchema>>>
185
+ type Final = InferSchemaType<NonNullable<TSchema>>
297
186
 
298
- // Seeded from the client so the first render already shows hydrating, not an
299
- // empty chat. The constructor sets it without firing a callback. Tagged with
300
- // its client: after a thread switch, the new client's value shows on the
301
- // first render, before the effects sync it.
302
- const [hydration, setHydration] = useState(() => ({
187
+ // Constructor hydration (sync store / resume snapshot) must be on the first
188
+ // paint. `useEffect` runs after paint, so seed from the snapshot here.
189
+ // Tagged with its client: after a thread switch, the new client's snapshot
190
+ // shows on the first render, before the effect below subscribes.
191
+ const [held, setHeld] = useState(() => ({
303
192
  client,
304
- value: client.getIsHydrating(),
193
+ snapshot: client.getSnapshot(),
305
194
  }))
306
- const isHydrating =
307
- hydration.client === client ? hydration.value : client.getIsHydrating()
195
+ const snapshot =
196
+ held.client === client ? held.snapshot : client.getSnapshot()
308
197
 
309
198
  useEffect(() => {
310
199
  activeClientRef.current = client
@@ -325,12 +214,16 @@ export function useChat<
325
214
  }, [client, initialization])
326
215
 
327
216
  useEffect(() => {
328
- const clientMessages = client.getMessages()
329
- if (clientMessages !== messagesRef.current) {
330
- setMessages(clientMessages)
217
+ const applySnapshot = () => {
218
+ const next = client.getSnapshot()
219
+ setHeld((prev) =>
220
+ prev.client === client && prev.snapshot === next
221
+ ? prev
222
+ : { client, snapshot: next },
223
+ )
331
224
  }
332
- setHasOlderMessages(client.getHasOlderMessages())
333
- setHydration({ client, value: client.getIsHydrating() })
225
+ applySnapshot()
226
+ return client.subscribeSnapshot(applySnapshot)
334
227
  }, [client])
335
228
 
336
229
  // OCTANE DIVERGENCE: upstream captures the initial transport. ChatClient
@@ -400,7 +293,6 @@ export function useChat<
400
293
  useEffect(() => {
401
294
  client.attach()
402
295
  client.mountDevtools()
403
- syncResumeState(client)
404
296
  return () => {
405
297
  client.detach()
406
298
  if (optionsRef.current.live) {
@@ -413,20 +305,16 @@ export function useChat<
413
305
  activeClientRef.current = null
414
306
  }
415
307
  }
416
- }, [client, syncResumeState])
308
+ }, [client])
417
309
 
418
310
  const sendMessage = useCallback(
419
311
  async (
420
312
  content: string | MultimodalContent,
421
313
  sendOptions?: SendMessageOptions,
422
314
  ) => {
423
- try {
424
- await client.sendMessage(content, undefined, sendOptions)
425
- } finally {
426
- syncResumeState(client)
427
- }
315
+ await client.sendMessage(content, undefined, sendOptions)
428
316
  },
429
- [client, syncResumeState],
317
+ [client],
430
318
  )
431
319
 
432
320
  const cancelQueued = useCallback(
@@ -438,26 +326,17 @@ export function useChat<
438
326
 
439
327
  const append = useCallback(
440
328
  async (message: ModelMessage | UIMessage) => {
441
- try {
442
- await client.append(message)
443
- } finally {
444
- syncResumeState(client)
445
- }
329
+ await client.append(message)
446
330
  },
447
- [client, syncResumeState],
331
+ [client],
448
332
  )
449
333
 
450
334
  const reload = useCallback(async () => {
451
- try {
452
- await client.reload()
453
- } finally {
454
- syncResumeState(client)
455
- }
456
- }, [client, syncResumeState])
335
+ await client.reload()
336
+ }, [client])
457
337
 
458
338
  const loadOlderMessages = useCallback(async () => {
459
339
  await client.loadOlderMessages()
460
- setHasOlderMessages(client.getHasOlderMessages())
461
340
  }, [client])
462
341
 
463
342
  const stop = useCallback(() => {
@@ -466,11 +345,10 @@ export function useChat<
466
345
 
467
346
  const clear = useCallback(() => {
468
347
  client.clear()
469
- syncResumeState(client)
470
- }, [client, syncResumeState])
348
+ }, [client])
471
349
 
472
350
  const setMessagesManually = useCallback(
473
- (newMessages: Array<UIMessage<TTools>>) => {
351
+ (newMessages: ReadonlyArray<UIMessage<TTools>>) => {
474
352
  client.setMessagesManually(newMessages)
475
353
  },
476
354
  [client],
@@ -492,21 +370,15 @@ export function useChat<
492
370
  const addToolApprovalResponse = useCallback(
493
371
  async (response: { id: string; approved: boolean }) => {
494
372
  await client.addToolApprovalResponse(response)
495
- syncResumeState(client)
496
373
  },
497
- [client, syncResumeState],
374
+ [client],
498
375
  )
499
376
 
500
377
  const resumeInterrupts = useCallback(
501
378
  async (resumeItems: Array<RunAgentResumeItem>, state?: ChatResumeState) => {
502
- const result = await client.resumeInterrupts(
503
- resumeItems,
504
- state ?? undefined,
505
- )
506
- syncResumeState(client)
507
- return result
379
+ return await client.resumeInterrupts(resumeItems, state ?? undefined)
508
380
  },
509
- [client, syncResumeState],
381
+ [client],
510
382
  )
511
383
 
512
384
  const resolveInterrupts = useCallback(
@@ -550,7 +422,7 @@ export function useChat<
550
422
  // a stale assistant turn or a system prompt) we deliberately return null
551
423
  // rather than scanning historical assistants — otherwise a `final` from a
552
424
  // previous session would leak into the hook value on first render.
553
- const renderedMessages = client.getMessages()
425
+ const renderedMessages = snapshot.messages
554
426
 
555
427
  const activeStructuredPart = useMemo<StructuredOutputPart | null>(() => {
556
428
  let lastUserIndex = -1
@@ -595,26 +467,26 @@ export function useChat<
595
467
  append,
596
468
  reload,
597
469
  stop,
598
- isLoading,
599
- hasOlderMessages,
470
+ isLoading: snapshot.isLoading,
471
+ hasOlderMessages: snapshot.hasOlderMessages,
600
472
  loadOlderMessages,
601
- error,
602
- status,
603
- isSubscribed,
604
- connectionStatus,
605
- sessionGenerating,
606
- isHydrating,
473
+ error: snapshot.error,
474
+ status: snapshot.status,
475
+ isSubscribed: snapshot.isSubscribed,
476
+ connectionStatus: snapshot.connectionStatus,
477
+ sessionGenerating: snapshot.sessionGenerating,
478
+ isHydrating: snapshot.isHydrating,
607
479
  setMessages: setMessagesManually,
608
480
  clear,
609
481
  addToolResult,
610
482
  addToolApprovalResponse,
611
- queue,
483
+ queue: snapshot.queue,
612
484
  cancelQueued,
613
- runId,
614
- interrupts: interruptState.interrupts,
615
- pendingInterrupts: interruptState.pendingInterrupts,
616
- interruptErrors: interruptState.interruptErrors,
617
- resuming: interruptState.resuming,
485
+ runId: snapshot.runId,
486
+ interrupts: snapshot.interruptState.interrupts,
487
+ pendingInterrupts: snapshot.interruptState.pendingInterrupts,
488
+ interruptErrors: snapshot.interruptState.interruptErrors,
489
+ resuming: snapshot.interruptState.resuming,
618
490
  resolveInterrupts,
619
491
  cancelInterrupts,
620
492
  retryInterrupts,
@@ -172,12 +172,6 @@ export function useGenerateVideo<TTransformed = void>(
172
172
  onStatusUpdate: (s: VideoStatusInfo) => {
173
173
  optionsRef.current.onStatusUpdate?.(s)
174
174
  },
175
- onResultChange: setResult,
176
- onLoadingChange: setIsLoading,
177
- onErrorChange: setError,
178
- onStatusChange: setStatus,
179
- onJobIdChange: setJobId,
180
- onVideoStatusChange: setVideoStatus,
181
175
  }
182
176
 
183
177
  if (opts.connection) {
@@ -199,6 +193,20 @@ export function useGenerateVideo<TTransformed = void>(
199
193
  )
200
194
  }, [clientId])
201
195
 
196
+ useEffect(() => {
197
+ const applySnapshot = () => {
198
+ const next = client.getSnapshot()
199
+ setResult(next.result)
200
+ setIsLoading(next.isLoading)
201
+ setError(next.error)
202
+ setStatus(next.status)
203
+ setJobId(next.jobId)
204
+ setVideoStatus(next.videoStatus)
205
+ }
206
+ applySnapshot()
207
+ return client.subscribe(applySnapshot)
208
+ }, [client])
209
+
202
210
  // Sync body changes without recreating client
203
211
  useEffect(() => {
204
212
  // Conditional spread: target uses strict-optional `body?: T`.
@@ -160,10 +160,6 @@ export function useGeneration<
160
160
  onChunk: (c: StreamChunk) => {
161
161
  optionsRef.current.onChunk?.(c)
162
162
  },
163
- onResultChange: setResult,
164
- onLoadingChange: setIsLoading,
165
- onErrorChange: setError,
166
- onStatusChange: setStatus,
167
163
  }
168
164
 
169
165
  if (opts.connection) {
@@ -185,6 +181,18 @@ export function useGeneration<
185
181
  )
186
182
  }, [clientId])
187
183
 
184
+ useEffect(() => {
185
+ const applySnapshot = () => {
186
+ const next = client.getSnapshot()
187
+ setResult(next.result)
188
+ setIsLoading(next.isLoading)
189
+ setError(next.error)
190
+ setStatus(next.status)
191
+ }
192
+ applySnapshot()
193
+ return client.subscribe(applySnapshot)
194
+ }, [client])
195
+
188
196
  // Sync body changes without recreating client
189
197
  useEffect(() => {
190
198
  // Conditional spread: target uses strict-optional `body?: T`.
@@ -61,7 +61,7 @@ export function useRealtimeChat(
61
61
  // State
62
62
  const [status, setStatus] = useState<RealtimeStatus>('idle')
63
63
  const [mode, setMode] = useState<RealtimeMode>('idle')
64
- const [messages, setMessages] = useState<Array<RealtimeMessage>>([])
64
+ const [messages, setMessages] = useState<ReadonlyArray<RealtimeMessage>>([])
65
65
  const [pendingUserTranscript, setPendingUserTranscript] = useState<
66
66
  string | null
67
67
  >(null)
@@ -124,17 +124,14 @@ export function useRealtimeChat(
124
124
  semanticEagerness: initial.semanticEagerness,
125
125
  }),
126
126
  onStatusChange: (newStatus) => {
127
- setStatus(newStatus)
128
127
  // OCTANE DIVERGENCE: upstream declares this callback but does not
129
128
  // forward status changes beyond its own hook state.
130
129
  optionsRef.current.onStatusChange?.(newStatus)
131
130
  },
132
131
  onModeChange: (newMode) => {
133
- setMode(newMode)
134
132
  optionsRef.current.onModeChange?.(newMode)
135
133
  },
136
134
  onMessage: (message) => {
137
- setMessages((prev) => [...prev, message])
138
135
  optionsRef.current.onMessage?.(message)
139
136
  },
140
137
  onUsage: (usage) => {
@@ -144,31 +141,36 @@ export function useRealtimeChat(
144
141
  optionsRef.current.onGoAway?.(timeLeft)
145
142
  },
146
143
  onError: (err) => {
147
- setError(err)
148
144
  optionsRef.current.onError?.(err)
149
145
  },
150
146
  onConnect: () => {
151
- setError(null)
152
147
  optionsRef.current.onConnect?.()
153
148
  },
154
149
  onDisconnect: () => {
155
150
  optionsRef.current.onDisconnect?.()
156
151
  },
157
152
  onInterrupted: () => {
158
- setPendingAssistantTranscript(null)
159
153
  optionsRef.current.onInterrupted?.()
160
154
  },
161
155
  })
162
-
163
- // Subscribe to state changes for transcripts
164
- clientRef.current.onStateChange((state) => {
165
- setPendingUserTranscript(state.pendingUserTranscript)
166
- setPendingAssistantTranscript(state.pendingAssistantTranscript)
167
- })
168
156
  }
169
157
 
170
158
  const client = clientRef.current
171
159
 
160
+ useEffect(() => {
161
+ const applySnapshot = () => {
162
+ const next = client.getSnapshot()
163
+ setStatus(next.status)
164
+ setMode(next.mode)
165
+ setMessages(next.messages)
166
+ setPendingUserTranscript(next.pendingUserTranscript)
167
+ setPendingAssistantTranscript(next.pendingAssistantTranscript)
168
+ setError(next.error)
169
+ }
170
+ applySnapshot()
171
+ return client.subscribe(applySnapshot)
172
+ }, [client])
173
+
172
174
  // Audio level animation loop
173
175
  useEffect(() => {
174
176
  function updateLevels() {
@@ -200,10 +202,6 @@ export function useRealtimeChat(
200
202
 
201
203
  // Connection methods
202
204
  const connect = useCallback(async () => {
203
- setError(null)
204
- setMessages([])
205
- setPendingUserTranscript(null)
206
- setPendingAssistantTranscript(null)
207
205
  await client.connect()
208
206
  }, [client])
209
207