@tanstack/ai-octane 0.9.1 → 1.1.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/src/index.ts CHANGED
@@ -6,12 +6,10 @@ export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge.tsrx'
6
6
  export {
7
7
  usePageWebMCPTools,
8
8
  useRegisterWebMCPTools,
9
- useWebMCPTools,
10
9
  } from './use-web-mcp-tools.tsrx'
11
10
  export type {
12
11
  UsePageWebMCPToolsOptions,
13
12
  UseRegisterWebMCPToolsOptions,
14
- UseWebMCPToolsOptions,
15
13
  } from './use-web-mcp-tools.tsrx'
16
14
  export type {
17
15
  DeepPartial,
@@ -41,6 +39,11 @@ export type {
41
39
  UseGenerateImageOptions,
42
40
  UseGenerateImageReturn,
43
41
  } from './use-generate-image.tsrx'
42
+ export { useGenerate3DModel } from './use-generate-3d-model.tsrx'
43
+ export type {
44
+ UseGenerate3DModelOptions,
45
+ UseGenerate3DModelReturn,
46
+ } from './use-generate-3d-model.tsrx'
44
47
  export { useGenerateAudio } from './use-generate-audio.tsrx'
45
48
  export type {
46
49
  UseGenerateAudioOptions,
@@ -138,6 +141,7 @@ export {
138
141
  type InferChatMessages,
139
142
  type GenerationClientState,
140
143
  type ImageGenerateInput,
144
+ type Model3DGenerateInput,
141
145
  type AudioGenerateInput,
142
146
  type SpeechGenerateInput,
143
147
  type TranscriptionGenerateInput,
@@ -1,5 +1,6 @@
1
1
  import type {
2
2
  AnyClientTool,
3
+ RealtimeAdapter,
3
4
  RealtimeMessage,
4
5
  RealtimeMode,
5
6
  RealtimeSessionConfig,
@@ -7,7 +8,6 @@ import type {
7
8
  RealtimeToken,
8
9
  UsageInfo,
9
10
  } from '@tanstack/ai'
10
- import type { RealtimeAdapter } from '@tanstack/ai-client'
11
11
 
12
12
  /**
13
13
  * Options for the useRealtimeChat hook.
package/src/types.ts CHANGED
@@ -204,14 +204,6 @@ interface BaseUseChatReturn<
204
204
  errorText?: string
205
205
  }) => Promise<void>
206
206
 
207
- /**
208
- * Respond to a tool approval request
209
- */
210
- addToolApprovalResponse: (response: {
211
- id: string // approval.id, not toolCallId
212
- approved: boolean
213
- }) => Promise<void>
214
-
215
207
  /**
216
208
  * The id of the run this client has in flight — one it started or rejoined —
217
209
  * or `null` when there is none (including while a run sits paused on an
@@ -225,8 +217,6 @@ interface BaseUseChatReturn<
225
217
  */
226
218
  runId: string | null
227
219
  interrupts: BoundInterrupts<TTools, TInterrupts>
228
- /** @deprecated Use `interrupts`. */
229
- pendingInterrupts: BoundInterrupts<TTools, TInterrupts>
230
220
  interruptErrors: ChatInterruptState<TTools, TInterrupts>['interruptErrors']
231
221
  resuming: boolean
232
222
  resolveInterrupts: {
@@ -243,11 +233,6 @@ interface BaseUseChatReturn<
243
233
  resume: Array<RunAgentResumeItem>,
244
234
  state?: ChatResumeState,
245
235
  ) => Promise<boolean>
246
- /** @deprecated Use bound interrupt methods or `resumeInterruptsUnsafe`. */
247
- resumeInterrupts: (
248
- resume: Array<RunAgentResumeItem>,
249
- state?: ChatResumeState,
250
- ) => Promise<boolean>
251
236
 
252
237
  /**
253
238
  * Reload the last assistant message
@@ -42,7 +42,7 @@ export interface UseAudioRecorderReturn<TOutput> {
42
42
  * @example
43
43
  * ```tsx
44
44
  * const { isRecording, start, stop, recording } = useAudioRecorder()
45
- * const { sendMessage } = useChat({ connection })
45
+ * const { sendMessage } = useChat({ threadId: 'support-1', connection })
46
46
  * // ...
47
47
  * const rec = await stop()
48
48
  * sendMessage({ content: [rec.part] })
@@ -39,7 +39,7 @@ export interface UseAudioRecorderReturn<TOutput> {
39
39
  * @example
40
40
  * ```tsx
41
41
  * const { isRecording, start, stop, recording } = useAudioRecorder()
42
- * const { sendMessage } = useChat({ connection })
42
+ * const { sendMessage } = useChat({ threadId: 'support-1', connection })
43
43
  * // ...
44
44
  * const rec = await stop()
45
45
  * sendMessage({ content: [rec.part] })
package/src/use-chat.tsrx CHANGED
@@ -1,6 +1,6 @@
1
1
  import { ChatClient } from '@tanstack/ai-client'
2
2
  import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'
3
- import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'octane'
3
+ import { useCallback, useEffect, useMemo, useRef, useState } from 'octane'
4
4
  import type {
5
5
  AnyClientTool,
6
6
  InferSchemaType,
@@ -37,10 +37,8 @@ export function useChat<
37
37
  options: UseChatOptions<TTools, TSchema, TContext, TInterrupts>,
38
38
  ): UseChatReturn<TTools, TSchema, TInterrupts> {
39
39
  // The hook's identity is its `threadId`. Reload with the same `threadId`
40
- // restores the same conversation. `hookId` is only a recreation key when no
41
- // `threadId` is given. It is never sent on the wire.
42
- const hookId = useId()
43
- const clientId = options.threadId ?? hookId
40
+ // restores the same conversation.
41
+ const clientId = options.threadId
44
42
 
45
43
  const subscribedRef = useRef(false)
46
44
  const activeClientRef = useRef<ChatClient | null>(null)
@@ -93,27 +91,15 @@ export function useChat<
93
91
  devtoolsBridgeFactory: createChatDevtoolsBridge,
94
92
  ...transport,
95
93
  initialMessages: messagesToUse,
96
- ...(typeof initialOptions.threadId === 'string' &&
97
- initialOptions.persistence === true
94
+ threadId: initialOptions.threadId,
95
+ ...(initialOptions.persistence === true
98
96
  ? {
99
97
  persistence: true,
100
- threadId: initialOptions.threadId,
101
98
  ...(initialOptions.history !== undefined && {
102
99
  history: initialOptions.history,
103
100
  }),
104
101
  }
105
- : typeof initialOptions.threadId === 'string' &&
106
- initialOptions.persistence
107
- ? {
108
- persistence: initialOptions.persistence,
109
- threadId: initialOptions.threadId,
110
- }
111
- : {
112
- ...(initialOptions.threadId !== undefined && {
113
- threadId: initialOptions.threadId,
114
- }),
115
- }),
116
- ...(initialOptions.body !== undefined && { body: initialOptions.body }),
102
+ : { persistence: initialOptions.persistence }),
117
103
  ...(initialOptions.forwardedProps !== undefined && {
118
104
  forwardedProps: initialOptions.forwardedProps,
119
105
  }),
@@ -123,6 +109,8 @@ export function useChat<
123
109
  ...(initialOptions.context !== undefined && {
124
110
  context: initialOptions.context,
125
111
  }),
112
+ ...(initialOptions.byok !== undefined && { byok: initialOptions.byok }),
113
+ byokProvider: () => optionsRef.current.byokProvider?.(),
126
114
  devtools: {
127
115
  ...initialOptions.devtools,
128
116
  // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
@@ -247,10 +235,6 @@ export function useChat<
247
235
  // changing doesn't re-run the others. `updateOptions` declares strict-optional
248
236
  // fields and rejects explicit `undefined` under EOPT, so guard the optional
249
237
  // slots before passing them.
250
- useEffect(() => {
251
- client.updateOptions({ body: options.body })
252
- }, [client, options.body])
253
-
254
238
  useEffect(() => {
255
239
  if (options.forwardedProps !== undefined) {
256
240
  client.updateOptions({ forwardedProps: options.forwardedProps })
@@ -367,20 +351,6 @@ export function useChat<
367
351
  [client],
368
352
  )
369
353
 
370
- const addToolApprovalResponse = useCallback(
371
- async (response: { id: string; approved: boolean }) => {
372
- await client.addToolApprovalResponse(response)
373
- },
374
- [client],
375
- )
376
-
377
- const resumeInterrupts = useCallback(
378
- async (resumeItems: Array<RunAgentResumeItem>, state?: ChatResumeState) => {
379
- return await client.resumeInterrupts(resumeItems, state ?? undefined)
380
- },
381
- [client],
382
- )
383
-
384
354
  const resolveInterrupts = useCallback(
385
355
  (
386
356
  resolution:
@@ -479,19 +449,16 @@ export function useChat<
479
449
  setMessages: setMessagesManually,
480
450
  clear,
481
451
  addToolResult,
482
- addToolApprovalResponse,
483
452
  queue: snapshot.queue,
484
453
  cancelQueued,
485
454
  runId: snapshot.runId,
486
455
  interrupts: snapshot.interruptState.interrupts,
487
- pendingInterrupts: snapshot.interruptState.pendingInterrupts,
488
456
  interruptErrors: snapshot.interruptState.interruptErrors,
489
457
  resuming: snapshot.interruptState.resuming,
490
458
  resolveInterrupts,
491
459
  cancelInterrupts,
492
460
  retryInterrupts,
493
461
  resumeInterruptsUnsafe,
494
- resumeInterrupts,
495
462
  partial,
496
463
  final,
497
464
  } as unknown as UseChatReturn<TTools, TSchema, TInterrupts>
@@ -0,0 +1,143 @@
1
+ import { useGeneration } from './use-generation.tsrx'
2
+ import type { Model3DResult, StreamChunk } from '@tanstack/ai'
3
+ import type {
4
+ AIDevtoolsDisplayOptions,
5
+ ConnectConnectionAdapter,
6
+ GenerationClientState,
7
+ GenerationFetcher,
8
+ InferGenerationOutputFromReturn,
9
+ Model3DGenerateInput,
10
+ } from '@tanstack/ai-client'
11
+
12
+ /**
13
+ * Options for the useGenerate3DModel hook.
14
+ *
15
+ * @experimental 3D model generation is experimental. The shape can change in
16
+ * a minor release.
17
+ *
18
+ * @template TOutput - The output type after optional transform (defaults to Model3DResult)
19
+ */
20
+ export interface UseGenerate3DModelOptions<TOutput = Model3DResult> {
21
+ /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
22
+ connection?: ConnectConnectionAdapter
23
+ /** Direct async function for 3D model generation */
24
+ fetcher?: GenerationFetcher<Model3DGenerateInput, Model3DResult>
25
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
26
+ threadId: string
27
+ /** Additional body parameters to send with connect-based adapter requests */
28
+ body?: Record<string, any>
29
+ /** Display options for TanStack AI Devtools. */
30
+ devtools?: AIDevtoolsDisplayOptions
31
+ /**
32
+ * Callback when the 3D model is ready. Can optionally return a transformed value.
33
+ *
34
+ * - Return a non-null value to transform and store it as the result
35
+ * - Return `null` to keep the previous result unchanged
36
+ * - Return nothing (`void`) to store the raw result as-is
37
+ */
38
+ onResult?: (result: Model3DResult) => TOutput | null | void
39
+ /** Callback when an error occurs */
40
+ onError?: (error: Error) => void
41
+ /**
42
+ * Callback for each provider poll. `progress` is 0-100. `message` is the
43
+ * job state (`'pending'`, `'processing'` or `'completed'`).
44
+ */
45
+ onProgress?: (progress: number, message?: string) => void
46
+ /** Callback for each stream chunk (connect-based adapter mode only) */
47
+ onChunk?: (chunk: StreamChunk) => void
48
+ }
49
+
50
+ /**
51
+ * Return type for the useGenerate3DModel hook.
52
+ *
53
+ * @experimental 3D model generation is experimental. The shape can change in
54
+ * a minor release.
55
+ *
56
+ * @template TOutput - The output type (after optional transform)
57
+ */
58
+ export interface UseGenerate3DModelReturn<TOutput = Model3DResult> {
59
+ /** Start 3D model generation */
60
+ generate: (input: Model3DGenerateInput) => Promise<void>
61
+ /** The finished 3D model (url, format, files), or null */
62
+ result: TOutput | null
63
+ /** Whether generation is in progress */
64
+ isLoading: boolean
65
+ /** Current error, if any */
66
+ error: Error | undefined
67
+ /** Current state of the generation */
68
+ status: GenerationClientState
69
+ /** Abort the current generation */
70
+ stop: () => void
71
+ /** Clear result, error, and return to idle */
72
+ reset: () => void
73
+ }
74
+
75
+ /**
76
+ * Octane hook for generating 3D models (text-to-3D, image-to-3D, 3D-to-3D).
77
+ *
78
+ * Supports two transport modes:
79
+ * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)
80
+ * - **Fetcher** — Direct async function call
81
+ *
82
+ * The server streams a `generation:progress` event for each provider poll and
83
+ * one `generation:result` event with the finished model.
84
+ *
85
+ * @experimental 3D model generation is experimental. The shape can change in
86
+ * a minor release.
87
+ *
88
+ * @example
89
+ * ```tsx
90
+ * import { useGenerate3DModel } from '@tanstack/ai-octane'
91
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
92
+ *
93
+ * function ModelGenerator() {
94
+ * const { generate, result, isLoading, error } = useGenerate3DModel({
95
+ * threadId: 'hero-model',
96
+ * connection: fetchServerSentEvents('/api/3d-model'),
97
+ * onProgress: (progress, message) => console.log(progress, message),
98
+ * })
99
+ *
100
+ * return (
101
+ * <div>
102
+ * <button onClick={() => generate({ prompt: 'A low-poly fox' })}>
103
+ * Generate
104
+ * </button>
105
+ * {isLoading && <p>Generating...</p>}
106
+ * {error && <p>Error: {error.message}</p>}
107
+ * {result && <a href={result.url}>Download .{result.format}</a>}
108
+ * </div>
109
+ * )
110
+ * }
111
+ * ```
112
+ */
113
+ export function useGenerate3DModel<TTransformed = void>(
114
+ options: Omit<UseGenerate3DModelOptions, 'onResult'> & {
115
+ onResult?: (result: Model3DResult) => TTransformed
116
+ },
117
+ ): UseGenerate3DModelReturn<
118
+ InferGenerationOutputFromReturn<Model3DResult, TTransformed>
119
+ > {
120
+ const devtools = {
121
+ ...options.devtools,
122
+ // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
123
+ framework: 'octane',
124
+ hookName: 'useGenerate3DModel',
125
+ }
126
+ const { generate, result, isLoading, error, status, stop, reset } =
127
+ useGeneration<Model3DGenerateInput, Model3DResult, TTransformed>({
128
+ ...options,
129
+ devtools,
130
+ // 3D results are never persisted, even if an untyped caller sets it.
131
+ persistence: false,
132
+ })
133
+
134
+ return {
135
+ generate,
136
+ result,
137
+ isLoading,
138
+ error,
139
+ status,
140
+ stop,
141
+ reset,
142
+ }
143
+ }
@@ -0,0 +1,116 @@
1
+ // Declaration companion generated from use-generate-3d-model.tsrx.
2
+ import type { Model3DResult, StreamChunk } from '@tanstack/ai'
3
+ import type {
4
+ AIDevtoolsDisplayOptions,
5
+ ConnectConnectionAdapter,
6
+ GenerationClientState,
7
+ GenerationFetcher,
8
+ InferGenerationOutputFromReturn,
9
+ Model3DGenerateInput,
10
+ } from '@tanstack/ai-client'
11
+ /**
12
+ * Options for the useGenerate3DModel hook.
13
+ *
14
+ * @experimental 3D model generation is experimental. The shape can change in
15
+ * a minor release.
16
+ *
17
+ * @template TOutput - The output type after optional transform (defaults to Model3DResult)
18
+ */
19
+ export interface UseGenerate3DModelOptions<TOutput = Model3DResult> {
20
+ /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
21
+ connection?: ConnectConnectionAdapter
22
+ /** Direct async function for 3D model generation */
23
+ fetcher?: GenerationFetcher<Model3DGenerateInput, Model3DResult>
24
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
25
+ threadId: string
26
+ /** Additional body parameters to send with connect-based adapter requests */
27
+ body?: Record<string, any>
28
+ /** Display options for TanStack AI Devtools. */
29
+ devtools?: AIDevtoolsDisplayOptions
30
+ /**
31
+ * Callback when the 3D model is ready. Can optionally return a transformed value.
32
+ *
33
+ * - Return a non-null value to transform and store it as the result
34
+ * - Return `null` to keep the previous result unchanged
35
+ * - Return nothing (`void`) to store the raw result as-is
36
+ */
37
+ onResult?: (result: Model3DResult) => TOutput | null | void
38
+ /** Callback when an error occurs */
39
+ onError?: (error: Error) => void
40
+ /**
41
+ * Callback for each provider poll. `progress` is 0-100. `message` is the
42
+ * job state (`'pending'`, `'processing'` or `'completed'`).
43
+ */
44
+ onProgress?: (progress: number, message?: string) => void
45
+ /** Callback for each stream chunk (connect-based adapter mode only) */
46
+ onChunk?: (chunk: StreamChunk) => void
47
+ }
48
+ /**
49
+ * Return type for the useGenerate3DModel hook.
50
+ *
51
+ * @experimental 3D model generation is experimental. The shape can change in
52
+ * a minor release.
53
+ *
54
+ * @template TOutput - The output type (after optional transform)
55
+ */
56
+ export interface UseGenerate3DModelReturn<TOutput = Model3DResult> {
57
+ /** Start 3D model generation */
58
+ generate: (input: Model3DGenerateInput) => Promise<void>
59
+ /** The finished 3D model (url, format, files), or null */
60
+ result: TOutput | null
61
+ /** Whether generation is in progress */
62
+ isLoading: boolean
63
+ /** Current error, if any */
64
+ error: Error | undefined
65
+ /** Current state of the generation */
66
+ status: GenerationClientState
67
+ /** Abort the current generation */
68
+ stop: () => void
69
+ /** Clear result, error, and return to idle */
70
+ reset: () => void
71
+ }
72
+ /**
73
+ * Octane hook for generating 3D models (text-to-3D, image-to-3D, 3D-to-3D).
74
+ *
75
+ * Supports two transport modes:
76
+ * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)
77
+ * - **Fetcher** — Direct async function call
78
+ *
79
+ * The server streams a `generation:progress` event for each provider poll and
80
+ * one `generation:result` event with the finished model.
81
+ *
82
+ * @experimental 3D model generation is experimental. The shape can change in
83
+ * a minor release.
84
+ *
85
+ * @example
86
+ * ```tsx
87
+ * import { useGenerate3DModel } from '@tanstack/ai-octane'
88
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
89
+ *
90
+ * function ModelGenerator() {
91
+ * const { generate, result, isLoading, error } = useGenerate3DModel({
92
+ * threadId: 'hero-model',
93
+ * connection: fetchServerSentEvents('/api/3d-model'),
94
+ * onProgress: (progress, message) => console.log(progress, message),
95
+ * })
96
+ *
97
+ * return (
98
+ * <div>
99
+ * <button onClick={() => generate({ prompt: 'A low-poly fox' })}>
100
+ * Generate
101
+ * </button>
102
+ * {isLoading && <p>Generating...</p>}
103
+ * {error && <p>Error: {error.message}</p>}
104
+ * {result && <a href={result.url}>Download .{result.format}</a>}
105
+ * </div>
106
+ * )
107
+ * }
108
+ * ```
109
+ */
110
+ export declare function useGenerate3DModel<TTransformed = void>(
111
+ options: Omit<UseGenerate3DModelOptions, 'onResult'> & {
112
+ onResult?: (result: Model3DResult) => TTransformed
113
+ },
114
+ ): UseGenerate3DModelReturn<
115
+ InferGenerationOutputFromReturn<Model3DResult, TTransformed>
116
+ >
@@ -19,8 +19,8 @@ export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
19
19
  connection?: ConnectConnectionAdapter
20
20
  /** Direct async function for audio generation */
21
21
  fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>
22
- /** Unique identifier for this generation instance */
23
- id?: string
22
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
23
+ threadId: string
24
24
  /** Additional body parameters to send with connect-based adapter requests */
25
25
  body?: Record<string, any>
26
26
  /** Display options for TanStack AI Devtools. */
@@ -77,6 +77,7 @@ export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
77
77
  *
78
78
  * function AudioGenerator() {
79
79
  * const { generate, result, isLoading, error, reset } = useGenerateAudio({
80
+ * threadId: 'theme-audio',
80
81
  * connection: fetchServerSentEvents('/api/generate/audio'),
81
82
  * })
82
83
  *
@@ -18,8 +18,8 @@ export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
18
18
  connection?: ConnectConnectionAdapter
19
19
  /** Direct async function for audio generation */
20
20
  fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>
21
- /** Unique identifier for this generation instance */
22
- id?: string
21
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
22
+ threadId: string
23
23
  /** Additional body parameters to send with connect-based adapter requests */
24
24
  body?: Record<string, any>
25
25
  /** Display options for TanStack AI Devtools. */
@@ -74,6 +74,7 @@ export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
74
74
  *
75
75
  * function AudioGenerator() {
76
76
  * const { generate, result, isLoading, error, reset } = useGenerateAudio({
77
+ * threadId: 'theme-audio',
77
78
  * connection: fetchServerSentEvents('/api/generate/audio'),
78
79
  * })
79
80
  *
@@ -19,8 +19,8 @@ export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
19
19
  connection?: ConnectConnectionAdapter
20
20
  /** Direct async function for image generation */
21
21
  fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>
22
- /** Unique identifier for this generation instance */
23
- id?: string
22
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
23
+ threadId: string
24
24
  /** Additional body parameters to send with connect-based adapter requests */
25
25
  body?: Record<string, any>
26
26
  /** Display options for TanStack AI Devtools. */
@@ -77,6 +77,7 @@ export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
77
77
  *
78
78
  * function ImageGenerator() {
79
79
  * const { generate, result, isLoading, error, reset } = useGenerateImage({
80
+ * threadId: 'hero-image',
80
81
  * connection: fetchServerSentEvents('/api/generate/image'),
81
82
  * })
82
83
  *
@@ -18,8 +18,8 @@ export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
18
18
  connection?: ConnectConnectionAdapter
19
19
  /** Direct async function for image generation */
20
20
  fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>
21
- /** Unique identifier for this generation instance */
22
- id?: string
21
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
22
+ threadId: string
23
23
  /** Additional body parameters to send with connect-based adapter requests */
24
24
  body?: Record<string, any>
25
25
  /** Display options for TanStack AI Devtools. */
@@ -74,6 +74,7 @@ export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
74
74
  *
75
75
  * function ImageGenerator() {
76
76
  * const { generate, result, isLoading, error, reset } = useGenerateImage({
77
+ * threadId: 'hero-image',
77
78
  * connection: fetchServerSentEvents('/api/generate/image'),
78
79
  * })
79
80
  *
@@ -19,8 +19,8 @@ export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
19
19
  connection?: ConnectConnectionAdapter
20
20
  /** Direct async function for speech generation */
21
21
  fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>
22
- /** Unique identifier for this generation instance */
23
- id?: string
22
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
23
+ threadId: string
24
24
  /** Additional body parameters to send with connect-based adapter requests */
25
25
  body?: Record<string, any>
26
26
  /** Display options for TanStack AI Devtools. */
@@ -73,6 +73,7 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
73
73
  *
74
74
  * function SpeechGenerator() {
75
75
  * const { generate, result, isLoading } = useGenerateSpeech({
76
+ * threadId: 'welcome-speech',
76
77
  * connection: fetchServerSentEvents('/api/generate/speech'),
77
78
  * })
78
79
  *
@@ -18,8 +18,8 @@ export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
18
18
  connection?: ConnectConnectionAdapter
19
19
  /** Direct async function for speech generation */
20
20
  fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>
21
- /** Unique identifier for this generation instance */
22
- id?: string
21
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
22
+ threadId: string
23
23
  /** Additional body parameters to send with connect-based adapter requests */
24
24
  body?: Record<string, any>
25
25
  /** Display options for TanStack AI Devtools. */
@@ -70,6 +70,7 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
70
70
  *
71
71
  * function SpeechGenerator() {
72
72
  * const { generate, result, isLoading } = useGenerateSpeech({
73
+ * threadId: 'welcome-speech',
73
74
  * connection: fetchServerSentEvents('/api/generate/speech'),
74
75
  * })
75
76
  *
@@ -1,6 +1,6 @@
1
1
  import { VideoGenerationClient } from '@tanstack/ai-client'
2
2
  import { createVideoDevtoolsBridge } from '@tanstack/ai-client/devtools'
3
- import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'octane'
3
+ import { useCallback, useEffect, useMemo, useRef, useState } from 'octane'
4
4
  import type { StreamChunk } from '@tanstack/ai'
5
5
  import type {
6
6
  AIDevtoolsDisplayOptions,
@@ -21,8 +21,8 @@ export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
21
21
  connection?: ConnectConnectionAdapter
22
22
  /** Direct async function that returns a completed video result */
23
23
  fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>
24
- /** Unique identifier for this generation instance */
25
- id?: string
24
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
25
+ threadId: string
26
26
  /** Additional body parameters to send with connect-based adapter requests */
27
27
  body?: Record<string, any>
28
28
  /** Display options for TanStack AI Devtools. */
@@ -86,6 +86,7 @@ export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
86
86
  *
87
87
  * function VideoGenerator() {
88
88
  * const { generate, result, videoStatus, isLoading } = useGenerateVideo({
89
+ * threadId: 'intro-video',
89
90
  * connection: fetchServerSentEvents('/api/generate/video'),
90
91
  * onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),
91
92
  * })
@@ -118,8 +119,7 @@ export function useGenerateVideo<TTransformed = void>(
118
119
  VideoGenerateResult,
119
120
  TTransformed
120
121
  >
121
- const hookId = useId()
122
- const clientId = options.id || hookId
122
+ const clientId = options.threadId
123
123
 
124
124
  const [result, setResult] = useState<TOutput | null>(null)
125
125
  const [jobId, setJobId] = useState<string | null>(null)
@@ -140,7 +140,7 @@ export function useGenerateVideo<TTransformed = void>(
140
140
  // return type (which `exactOptionalPropertyTypes` rejects
141
141
  // against the strict-optional target).
142
142
  const baseOptions = {
143
- id: clientId,
143
+ threadId: clientId,
144
144
  body: opts.body,
145
145
  devtoolsBridgeFactory: createVideoDevtoolsBridge,
146
146
  devtools: {
@@ -18,8 +18,8 @@ export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
18
18
  connection?: ConnectConnectionAdapter
19
19
  /** Direct async function that returns a completed video result */
20
20
  fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>
21
- /** Unique identifier for this generation instance */
22
- id?: string
21
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
22
+ threadId: string
23
23
  /** Additional body parameters to send with connect-based adapter requests */
24
24
  body?: Record<string, any>
25
25
  /** Display options for TanStack AI Devtools. */
@@ -81,6 +81,7 @@ export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
81
81
  *
82
82
  * function VideoGenerator() {
83
83
  * const { generate, result, videoStatus, isLoading } = useGenerateVideo({
84
+ * threadId: 'intro-video',
84
85
  * connection: fetchServerSentEvents('/api/generate/video'),
85
86
  * onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),
86
87
  * })