Open History to see the last commit
1import {
2 GENERATION_EVENTS,
3 GENERATION_STREAM_TRUNCATED_MESSAGE,
4 GENERATION_UNRESTORABLE_RESULT_MESSAGE,
5 clientStateFromResumeStatus,
6 createGenerationHydrationError,
7 createGenerationResultSnapshot,
8 parseGenerationResumeSnapshot,
9 updateGenerationResumeSnapshot,
10} from './generation-types'
11import { createNoOpGenerationDevtoolsBridge } from './devtools-noop'
12import { parseSSEResponse } from './sse-parser'
13import type { StreamChunk } from '@tanstack/ai/client'
14import type {
15 ConnectConnectionAdapter,
16 GenerationHydrationResult,
17 RunAgentInputContext,
18} from './connection-adapters'
19import type {
20 AIDevtoolsClientMetadata,
21 AIDevtoolsGenerationProgress,
22 GenerationDevtoolsBridge,
23 GenerationDevtoolsBridgeOptions,
24} from './devtools'
25import type {
26 GenerationClientOptions,
27 GenerationClientState,
28 GenerationFetcher,
29 GenerationRestoredResult,
30 GenerationResumeSnapshot,
31 GenerationResumeState,
32} from './generation-types'
33
34/**
35 * Callbacks stored in a ref so hooks can update them without recreating the client.
36 */
37// All optional fields explicitly allow `| undefined` so callers can spread
38// option bags (where each callback may be `undefined`) into the callbacks
39// ref under `exactOptionalPropertyTypes`.
40interface GenerationCallbacks<TResult, TOutput> {
41 onResult?: ((result: TResult) => TOutput | null | void) | undefined
42 onError?: ((error: Error) => void) | undefined
43 onProgress?: ((progress: number, message?: string) => void) | undefined
44 onChunk?: ((chunk: StreamChunk) => void) | undefined
45 onResultChange?: ((result: TOutput | null) => void) | undefined
46 onLoadingChange?: ((isLoading: boolean) => void) | undefined
47 onErrorChange?: ((error: Error | undefined) => void) | undefined
48 onStatusChange?: ((status: GenerationClientState) => void) | undefined
49 onResumeSnapshotChange?:
50 | ((snapshot: GenerationResumeSnapshot | undefined) => void)
51 | undefined
52 onResumeStateChange?:
53 | ((resumeState: GenerationResumeState | null) => void)
54 | undefined
55 reconstructResult?:
56 | ((restored: GenerationRestoredResult) => TResult | null)
57 | undefined
58}
59
60/**
61 * A lightweight, generic client for one-shot generation tasks
62 * (image, speech, transcription, summarize).
63 *
64 * Supports two transport modes:
65 * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom).
66 * Server wraps results in StreamChunk events with CUSTOM event names.
67 * - **Fetcher** — Direct async function call. No streaming protocol needed.
68 *
69 * @template TInput - The input type for the generation request
70 * @template TResult - The result type returned by the generation
71 *
72 * @example
73 * ```typescript
74 * // With streaming connection adapter
75 * const client = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({
76 * connection: fetchServerSentEvents('/api/generate/image'),
77 * onResultChange: setResult,
78 * onLoadingChange: setIsLoading,
79 * })
80 *
81 * // With fetcher (direct)
82 * const client = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({
83 * fetcher: async (input) => {
84 * const res = await fetch('/api/generate/image', {
85 * method: 'POST',
86 * body: JSON.stringify(input),
87 * })
88 * return res.json()
89 * },
90 * })
91 *
92 * await client.generate({ prompt: 'A sunset over mountains' })
93 * ```
94 */
95export class GenerationClient<
96 TInput extends Record<string, any>,
97 TResult,
98 TOutput = TResult,
99> {
100 private readonly connection: ConnectConnectionAdapter | undefined
101 private readonly fetcher: GenerationFetcher<TInput, TResult> | undefined
102 // Persistence handlers supplied as options (e.g. alongside a `fetcher`), used
103 // when the connection doesn't carry its own — the connection's handlers take
104 // precedence when both exist.
105 private readonly hydrateGenerationHandler:
106 | ConnectConnectionAdapter['hydrateGeneration']
107 | undefined
108 private readonly joinRunHandler:
109 | ConnectConnectionAdapter['joinRun']
110 | undefined
111 private readonly uniqueId: string
112 private readonly devtoolsMetadata: AIDevtoolsClientMetadata
113 private readonly devtoolsBridge: GenerationDevtoolsBridge<TOutput>
114 private readonly threadId: string
115 private readonly persistenceScope: string | undefined
116 // Server-driven mode (`persistence: true`): no local snapshot store; on mount
117 // the client hydrates the last generation for `threadId` from the server.
118 private readonly serverDriven: boolean = false
119 private body: Record<string, any>
120 private result: TOutput | null = null
121 private input: TInput | null = null
122 private progress: AIDevtoolsGenerationProgress | null = null
123 private isLoading = false
124 private error: Error | undefined = undefined
125 private status: GenerationClientState = 'idle'
126 private resumeSnapshot: GenerationResumeSnapshot | undefined
127 private lastEmittedResumeState: string | undefined
128 private abortController: AbortController | null = null
129 private rejoinedRunId: string | undefined
130 private readonly callbacksRef: GenerationCallbacks<TResult, TOutput>
131 private devtoolsMounted = false
132 private disposed = false
133 private serverHydrationStarted = false
134
135 constructor(
136 options: GenerationClientOptions<TInput, TResult, TOutput> &
137 (
138 | { connection: ConnectConnectionAdapter; fetcher?: never }
139 | {
140 fetcher: GenerationFetcher<TInput, TResult>
141 connection?: never
142 }
143 ),
144 ) {
145 // `threadId` is the single identity. Deprecated `id` is only a fallback
146 // when no threadId is given (ephemeral runs / legacy call sites).
147 this.uniqueId =
148 options.threadId ?? options.id ?? this.generateUniqueId('generation')
149 // AG-UI requires a thread id on every run, so fall back to uniqueId. The
150 // generated fallback is for the WIRE ONLY: it is not stable across reloads,
151 // so persistence must never key on it — see `persistenceScope` below.
152 this.threadId = options.threadId ?? this.uniqueId
153 // The persistence scope: the explicit `threadId` and nothing else. The
154 // types require it whenever `persistence` is set; this field keeps the
155 // fallback from silently becoming a storage key for JS callers.
156 this.persistenceScope = options.threadId
157 this.connection = options.connection
158 this.fetcher = options.fetcher
159 this.hydrateGenerationHandler = options.hydrateGeneration
160 this.joinRunHandler = options.joinRun
161 this.body = options.body ?? {}
162 // `persistence` is `false`/omitted (ephemeral) or `true` (server-driven:
163 // hydrate the last generation for `threadId` from the server on mount).
164 this.serverDriven = options.persistence === true
165 // The types require `threadId` alongside `persistence`, so this only fires
166 // for JS callers. Warn rather than fall back silently: keying on the
167 // generated wire id would write a different slot every reload, restoring
168 // nothing while accumulating orphaned records.
169 if (options.persistence && !this.persistenceScope) {
170 console.warn(
171 '[TanStack AI] `persistence` needs a stable `threadId` to key on. Without one nothing will be restored after a reload. Pass a `threadId` derived from your own domain (e.g. `product-123-hero`).',
172 )
173 }
174 this.callbacksRef = {
175 onResult: options.onResult,
176 onError: options.onError,
177 onProgress: options.onProgress,
178 onChunk: options.onChunk,
179 onResultChange: options.onResultChange,
180 onLoadingChange: options.onLoadingChange,
181 onErrorChange: options.onErrorChange,
182 onStatusChange: options.onStatusChange,
183 onResumeSnapshotChange: options.onResumeSnapshotChange,
184 onResumeStateChange: options.onResumeStateChange,
185 reconstructResult: options.reconstructResult,
186 }
187
188 this.devtoolsMetadata = this.createDevtoolsMetadata(options.devtools)
189 this.devtoolsBridge = (
190 options.devtoolsBridgeFactory ?? createNoOpGenerationDevtoolsBridge
191 )<TOutput>(this.buildDevtoolsBridgeOptions())
192
193 // Mount hydration (`maybeHydrateFromServer`) is deliberately NOT run here. The framework
194 // hooks build this client inside `useMemo`, so the constructor executes in
195 // React's render phase; hydrating here would re-fire the hydrate GET on
196 // every discarded/speculative render, flooding the connection pool when
197 // several clients mount together. It is kicked off once from
198 // `mountDevtools`, which the hooks call from a commit-phase mount effect.
199 }
200
201 private buildDevtoolsBridgeOptions(): GenerationDevtoolsBridgeOptions<TOutput> {
202 return {
203 hookId: this.uniqueId,
204 clientId: this.uniqueId,
205 threadId: this.threadId,
206 metadata: this.devtoolsMetadata,
207 getCoreState: () => ({
208 input: this.input,
209 result: this.result,
210 progress: this.progress,
211 status: this.status,
212 isLoading: this.isLoading,
213 ...(this.error ? { error: this.error.message } : {}),
214 }),
215 }
216 }
217
218 mountDevtools(): void {
219 // Mounting revives a disposed client. Framework hooks call this from
220 // their mount effect, so a dispose → remount cycle (e.g. React
221 // StrictMode's mount → cleanup → mount replay against the same memoized
222 // client) leaves the client usable again.
223 this.disposed = false
224 this.maybeHydrateFromServer()
225 // Re-attach to an in-flight run whose snapshot is already loaded — the
226 // remount case. On the FIRST mount the snapshot loads asynchronously and
227 // `repaintRestoredSnapshot` starts the rejoin; on a StrictMode remount the
228 // snapshot is already present but the prior rejoin was aborted by
229 // `dispose()`, so retrigger it here. Guarded by `rejoinInFlight`'s own
230 // dedupe/in-flight checks, so this never double-joins.
231 this.maybeResumeInFlight()
232 if (this.devtoolsMounted) {
233 return
234 }
235
236 this.devtoolsMounted = true
237 this.devtoolsBridge.emitRegistered()
238 this.devtoolsBridge.emitSnapshot()
239 }
240
241 /**
242 * Trigger a generation request.
243 * Only one generation can be in-flight at a time; calling generate()
244 * while already generating will be a no-op.
245 */
246 async generate(input: TInput): Promise<void> {
247 if (this.disposed) return
248 if (this.isLoading) return
249 this.mountDevtools()
250
251 this.input = input
252 this.progress = null
253 const runId = this.devtoolsBridge.beginRun(input)
254 this.setIsLoading(true)
255 this.setStatus('generating')
256 this.setError(undefined)
257
258 const abortController = new AbortController()
259 this.abortController = abortController
260 const { signal } = abortController
261
262 try {
263 if (this.fetcher) {
264 // Direct fetch path
265 const result = await this.fetcher(input, { signal })
266 if (signal.aborted) return
267 if (result instanceof Response) {
268 // Server function returned SSE Response — parse stream
269 await this.processStream(
270 parseSSEResponse(result, signal),
271 runId,
272 signal,
273 )
274 } else {
275 this.devtoolsBridge.ensureRunStarted(runId)
276 this.setResult(result)
277 this.setStatus('success')
278 this.completePlainFetcherResumeSnapshot(result)
279 }
280 } else if (this.connection) {
281 // Streaming adapter path
282 const mergedData = { ...this.body, ...input }
283 const stream = this.connection.connect(
284 [],
285 mergedData,
286 signal,
287 this.createRunContext(runId),
288 )
289 await this.processStream(stream, runId, signal)
290 } else {
291 throw new Error(
292 'GenerationClient requires either a connection or fetcher option',
293 )
294 }
295 if (!signal.aborted && this.status === 'success') {
296 // Bump progress to 100 on successful completion so devtools
297 // snapshots reflect the final state. The bridge mirrors this in
298 // the run's recorded progress, but the snapshot reads `progress`
299 // from the client's core state.
300 this.progress = completeProgressValue(this.progress)
301 this.devtoolsBridge.finishRun(
302 this.devtoolsBridge.getActiveRunId() ?? runId,
303 'run:completed',
304 'completed',
305 )
306 }
307 } catch (err: unknown) {
308 if (signal.aborted) return
309 const error = err instanceof Error ? err : new Error(String(err))
310 this.setError(error)
311 this.setStatus('error')
312 this.recordResumeSnapshotError(error)
313 this.devtoolsBridge.finishRun(
314 this.devtoolsBridge.getActiveRunId() ?? runId,
315 'run:errored',
316 'errored',
317 error.message,
318 )
319 this.callbacksRef.onError?.(error)
320 } finally {
321 if (this.abortController === abortController) {
322 this.abortController = null
323 this.setIsLoading(false)
324 }
325 }
326 }
327
328 /**
329 * Process a stream of AG-UI events from the streaming connection adapter.
330 *
331 * Throws {@link GENERATION_STREAM_TRUNCATED_MESSAGE} when the iteration ends
332 * without a terminal chunk. A `for await` over a stream that simply stops —
333 * proxy idle timeout, server restart, a durable log missing its terminal
334 * append — returns normally and would otherwise leave the caller's `status`
335 * on `generating` forever, with the persisted snapshot still `running` so
336 * every reload rejoins the same dead run. Throwing routes it through the
337 * caller's error path instead, which settles the status and rewrites the
338 * snapshot so nothing chases it again.
339 */
340 private async processStream(
341 source: AsyncIterable<StreamChunk>,
342 fallbackRunId: string,
343 signal: AbortSignal,
344 ): Promise<void> {
345 let streamRunId: string | undefined
346 let sawTerminalChunk = false
347
348 for await (const chunk of source) {
349 if (signal.aborted) break
350
351 this.callbacksRef.onChunk?.(chunk)
352 this.observeResumeSnapshot(chunk)
353 const chunkRunId =
354 'runId' in chunk && typeof chunk.runId === 'string'
355 ? chunk.runId
356 : undefined
357
358 // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType has ~22 variants; this consumer only handles the subset relevant to generation lifecycle.
359 switch (chunk.type) {
360 case 'RUN_STARTED': {
361 streamRunId = chunk.runId
362 this.devtoolsBridge.ensureRunStarted(chunk.runId)
363 break
364 }
365 case 'CUSTOM': {
366 this.devtoolsBridge.ensureRunStarted(streamRunId ?? fallbackRunId)
367 if (chunk.name === GENERATION_EVENTS.RESULT) {
368 this.setResult(chunk.value as TResult)
369 } else if (chunk.name === GENERATION_EVENTS.PROGRESS) {
370 const { progress, message } = chunk.value as {
371 progress: number
372 message?: string
373 }
374 this.setProgress(progress, message)
375 }
376 break
377 }
378 case 'RUN_FINISHED': {
379 streamRunId = chunk.runId
380 sawTerminalChunk = true
381 this.devtoolsBridge.ensureRunStarted(chunk.runId)
382 this.setStatus('success')
383 break
384 }
385 case 'RUN_ERROR': {
386 this.devtoolsBridge.ensureRunStarted(
387 chunkRunId ?? streamRunId ?? fallbackRunId,
388 )
389 // Prefer spec `message`; fall back to deprecated `error.message`
390 const msg =
391 (chunk.message as string | undefined) ||
392 chunk.error?.message ||
393 'An error occurred'
394 throw new Error(msg)
395 }
396 default:
397 break
398 }
399 }
400
401 // An aborted read is a deliberate stop/dispose, not a truncation.
402 if (!sawTerminalChunk && !signal.aborted) {
403 throw new Error(GENERATION_STREAM_TRUNCATED_MESSAGE)
404 }
405 }
406
407 /**
408 * Abort any in-flight generation request.
409 */
410 stop(): void {
411 const runId = this.devtoolsBridge.getActiveRunId()
412 if (this.abortController) {
413 this.abortController.abort()
414 this.abortController = null
415 }
416 this.setIsLoading(false)
417 if (this.status === 'generating') {
418 this.setStatus('idle')
419 if (runId) {
420 this.devtoolsBridge.finishRun(runId, 'run:cancelled', 'cancelled')
421 }
422 }
423 // A stopped run is no longer resumable. Without this the in-memory
424 // snapshot stays `running`, and a remount's `maybeResumeInFlight` would
425 // rejoin a run the user just cancelled.
426 if (this.resumeSnapshot && this.resumeSnapshot.status === 'running') {
427 this.resumeSnapshot = {
428 ...this.resumeSnapshot,
429 resumeState: null,
430 status: 'idle',
431 }
432 this.notifyResumeSnapshotChanged()
433 }
434 }
435
436 /**
437 * Clear the result, error, and return to idle state. Also drops the client's
438 * in-memory resume snapshot, so a remount restores nothing. The server-side
439 * record is untouched — this client no longer writes one — so a full page
440 * reload under `persistence: true` re-hydrates the last generation again.
441 */
442 reset(): void {
443 this.stop()
444 this.setResult(null)
445 this.input = null
446 this.progress = null
447 this.devtoolsBridge.resetRuns()
448 this.setError(undefined)
449 this.setStatus('idle')
450 this.clearResumeSnapshot()
451 this.devtoolsBridge.emitState()
452 }
453
454 /**
455 * Update options without recreating the client.
456 */
457 updateOptions(
458 options: Partial<
459 Pick<
460 GenerationClientOptions<TInput, TResult, TOutput>,
461 'body' | 'onResult' | 'onError' | 'onProgress' | 'onChunk'
462 >
463 >,
464 ): void {
465 if (options.body !== undefined) {
466 this.body = options.body ?? {}
467 }
468 if (options.onResult !== undefined) {
469 this.callbacksRef.onResult = options.onResult
470 }
471 if (options.onError !== undefined) {
472 this.callbacksRef.onError = options.onError
473 }
474 if (options.onProgress !== undefined) {
475 this.callbacksRef.onProgress = options.onProgress
476 }
477 if (options.onChunk !== undefined) {
478 this.callbacksRef.onChunk = options.onChunk
479 }
480 }
481
482 dispose(): void {
483 this.disposed = true
484 // Teardown, NOT a user cancel: abort in-flight DELIVERY (this reader) but
485 // do NOT call `stop()` — `stop()` marks the run non-resumable and wipes the
486 // `running` snapshot, which is correct for a Stop button but wrong for an
487 // unmount / React StrictMode dispose. Clearing it here would destroy the
488 // in-memory resume state, so a remount of this same client instance could
489 // never rejoin. (A real page revisit re-hydrates from the server instead.)
490 // The run itself survives server-side (durable delivery), so the snapshot
491 // must stay `running` for the remount to resume it.
492 if (this.abortController) {
493 this.abortController.abort()
494 this.abortController = null
495 }
496 this.setIsLoading(false)
497 this.devtoolsBridge.dispose()
498 this.devtoolsMounted = false
499 // Re-arm mount hydration + rejoin so a remount resumes from the (preserved)
500 // snapshot. `mountDevtools` re-runs the hydration entry point and
501 // `maybeResumeInFlight`, both individually guarded.
502 this.serverHydrationStarted = false
503 this.rejoinedRunId = undefined
504 }
505
506 // ===========================
507 // Getters
508 // ===========================
509
510 getResult(): TOutput | null {
511 return this.result
512 }
513
514 getIsLoading(): boolean {
515 return this.isLoading
516 }
517
518 getError(): Error | undefined {
519 return this.error
520 }
521
522 getStatus(): GenerationClientState {
523 return this.status
524 }
525
526 getResumeSnapshot(): GenerationResumeSnapshot | undefined {
527 return this.resumeSnapshot
528 ? {
529 ...this.resumeSnapshot,
530 ...(this.resumeSnapshot.pendingArtifacts
531 ? { pendingArtifacts: [...this.resumeSnapshot.pendingArtifacts] }
532 : {}),
533 ...(this.resumeSnapshot.result
534 ? {
535 result: {
536 ...this.resumeSnapshot.result,
537 ...(this.resumeSnapshot.result.artifacts
538 ? { artifacts: [...this.resumeSnapshot.result.artifacts] }
539 : {}),
540 },
541 }
542 : {}),
543 ...(this.resumeSnapshot.error
544 ? { error: { ...this.resumeSnapshot.error } }
545 : {}),
546 ...(this.resumeSnapshot.lastEvent
547 ? { lastEvent: { ...this.resumeSnapshot.lastEvent } }
548 : {}),
549 }
550 : undefined
551 }
552
553 // ===========================
554 // Private state setters
555 // ===========================
556
557 private setResult(rawResult: TResult | null): void {
558 if (rawResult === null) {
559 this.result = null
560 this.callbacksRef.onResultChange?.(null)
561 this.devtoolsBridge.recordResultChange()
562 return
563 }
564
565 if (this.callbacksRef.onResult) {
566 const transformed = this.callbacksRef.onResult(rawResult)
567 if (transformed === null) {
568 // null return → keep previous result unchanged, just re-emit
569 this.devtoolsBridge.emitState()
570 return
571 }
572 if (transformed !== undefined) {
573 // Non-null, non-undefined → use transformed value
574 this.result = transformed
575 this.callbacksRef.onResultChange?.(this.result)
576 this.devtoolsBridge.recordResultChange()
577 return
578 }
579 }
580
581 // No onResult callback, or callback returned void → use raw value as
582 // TOutput. When the caller did not supply an onResult transform,
583 // `TOutput` defaults to `TResult`, so the runtime cast is sound.
584 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- TOutput defaults to TResult when no onResult transform is supplied
585 this.result = rawResult as unknown as TOutput
586 this.callbacksRef.onResultChange?.(this.result)
587 this.devtoolsBridge.recordResultChange()
588 }
589
590 private setIsLoading(isLoading: boolean): void {
591 this.isLoading = isLoading
592 this.callbacksRef.onLoadingChange?.(isLoading)
593 this.devtoolsBridge.recordLoadingChange()
594 }
595
596 private setError(error: Error | undefined): void {
597 this.error = error
598 this.callbacksRef.onErrorChange?.(error)
599 this.devtoolsBridge.recordErrorChange(error)
600 }
601
602 private setStatus(status: GenerationClientState): void {
603 this.status = status
604 this.callbacksRef.onStatusChange?.(status)
605 this.devtoolsBridge.recordStatusChange(status)
606 }
607
608 private setProgress(value: number, message?: string): void {
609 this.progress = {
610 value,
611 ...(message ? { message } : {}),
612 }
613 if (message === undefined) {
614 this.callbacksRef.onProgress?.(value)
615 } else {
616 this.callbacksRef.onProgress?.(value, message)
617 }
618 this.devtoolsBridge.recordProgressChange()
619 }
620
621 private createDevtoolsMetadata(
622 metadata?: Partial<AIDevtoolsClientMetadata>,
623 ): AIDevtoolsClientMetadata {
624 return {
625 hookName: metadata?.hookName ?? 'useGeneration',
626 ...(metadata?.framework ? { framework: metadata.framework } : {}),
627 ...(metadata?.outputKind ? { outputKind: metadata.outputKind } : {}),
628 ...(metadata?.name ? { name: metadata.name } : {}),
629 }
630 }
631
632 private generateUniqueId(prefix: string): string {
633 return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
634 }
635
636 private createRunContext(runId: string): RunAgentInputContext {
637 return {
638 threadId: this.threadId,
639 runId,
640 }
641 }
642
643 private observeResumeSnapshot(chunk: StreamChunk): void {
644 this.resumeSnapshot = updateGenerationResumeSnapshot(
645 this.resumeSnapshot,
646 chunk,
647 )
648 this.notifyResumeSnapshotChanged()
649 }
650
651 /**
652 * Notify the (internal) snapshot listener AND emit the public resume state.
653 * The snapshot stays internal (persistence + devtools); the hook consumes
654 * `resumeState`, mirroring the chat client.
655 */
656 private notifyResumeSnapshotChanged(): void {
657 this.callbacksRef.onResumeSnapshotChange?.(this.resumeSnapshot)
658 this.emitResumeState()
659 }
660
661 /**
662 * Derive the public `resumeState` from the internal snapshot: the in-flight
663 * run identity, with any in-flight artifact refs folded under it. `null` once
664 * no run is in flight.
665 *
666 * The snapshot is rebuilt for every chunk, so emitting unconditionally would
667 * hand each framework hook a fresh object per chunk and re-render the
668 * component on every stream event. `resumeState` only changes at run
669 * boundaries and when artifacts land, so skip the notification unless it
670 * materially changed — same gate the persistence writes use.
671 */
672 private emitResumeState(): void {
673 const snapshot = this.resumeSnapshot
674 const state = snapshot?.resumeState
675 const resumeState: GenerationResumeState | null = state
676 ? {
677 ...state,
678 ...(snapshot?.pendingArtifacts && snapshot.pendingArtifacts.length > 0
679 ? { pendingArtifacts: [...snapshot.pendingArtifacts] }
680 : {}),
681 }
682 : null
683 const signature = JSON.stringify(resumeState)
684 if (signature === this.lastEmittedResumeState) {
685 return
686 }
687 this.lastEmittedResumeState = signature
688 this.callbacksRef.onResumeStateChange?.(resumeState)
689 }
690
691 /**
692 * Repaint the normal fields from a restored snapshot (client store or server
693 * hydrate), so a reload presents the run in `result` / `status` / `error`
694 * exactly as a just-finished run would, never a bolt-on snapshot object.
695 * `isLoading` stays false: the client never auto-tails a restored run. The
696 * snapshot is not re-persisted here (it came from storage / the server).
697 *
698 * When the activity's mapper DECLINES a `complete` snapshot the repaint
699 * settles as an error instead: `success` with a `null` result is a state no
700 * consumer can render, and it hides the real cause (an output artifact
701 * persisted without a serve URL). A decline on any other status is expected —
702 * a `running` snapshot has no result yet, the rejoin will deliver it.
703 */
704 private repaintFromSnapshot(snapshot: GenerationResumeSnapshot): void {
705 this.resumeSnapshot = snapshot
706 this.notifyResumeSnapshotChanged()
707 this.setStatus(clientStateFromResumeStatus(snapshot.status))
708 this.setError(
709 snapshot.error
710 ? Object.assign(
711 new Error(snapshot.error.message),
712 snapshot.error.code ? { code: snapshot.error.code } : {},
713 )
714 : undefined,
715 )
716 const restored = this.reconstructRestoredResult(snapshot)
717 if (restored !== null) {
718 this.setResult(restored)
719 } else if (
720 this.callbacksRef.reconstructResult &&
721 snapshot.status === 'complete'
722 ) {
723 this.reportUnrestorableResult()
724 }
725 }
726
727 /**
728 * Report a `complete` snapshot the activity's mapper could not rebuild.
729 * Runs after the status/error repaint above, so it wins over the snapshot's
730 * own `complete` status.
731 */
732 private reportUnrestorableResult(): void {
733 const error = new Error(GENERATION_UNRESTORABLE_RESULT_MESSAGE)
734 this.setStatus('error')
735 this.setError(error)
736 this.callbacksRef.onError?.(error)
737 }
738
739 /**
740 * Repaint a restored snapshot (client store or server hydrate) and, when it
741 * reports a run still in flight, tail that run to completion via `joinRun`
742 * (from the connection, or the `joinRun` option when the transport can't
743 * carry one).
744 *
745 * A `running` snapshot that no `joinRun` handler can tail is repainted as an
746 * interrupted error instead of a `generating` status that would never
747 * settle: an interrupted generation cannot be resumed, only re-run.
748 */
749 private repaintRestoredSnapshot(
750 snapshot: GenerationResumeSnapshot,
751 activeRunId?: string,
752 ): void {
753 if (snapshot.status !== 'running') {
754 this.repaintFromSnapshot(snapshot)
755 return
756 }
757 const joinRun = this.connection?.joinRun ?? this.joinRunHandler
758 const runId = activeRunId ?? snapshot.resumeState?.runId
759 if (runId && joinRun) {
760 this.repaintFromSnapshot(snapshot)
761 this.rejoinInFlight(runId)
762 return
763 }
764 this.repaintFromSnapshot({
765 ...snapshot,
766 resumeState: null,
767 status: 'error',
768 error: {
769 message:
770 'The previous generation was interrupted before it finished and cannot be resumed — generate again to retry.',
771 },
772 })
773 }
774
775 /**
776 * Build the restorable result shape from the snapshot and hand it to the
777 * per-activity `reconstructResult` mapper (injected by the specialized
778 * client/hook, which knows the concrete result type).
779 *
780 * Returns `null` both when no mapper is set (nothing to rebuild — `result`
781 * simply stays null) and when the mapper declines. The caller distinguishes
782 * the two: see {@link repaintFromSnapshot}.
783 */
784 private reconstructRestoredResult(
785 snapshot: GenerationResumeSnapshot,
786 ): TResult | null {
787 const build = this.callbacksRef.reconstructResult
788 if (!build) return null
789 const result = snapshot.result
790 const restored: GenerationRestoredResult = {
791 ...(result?.id !== undefined ? { id: result.id } : {}),
792 ...(result?.model !== undefined ? { model: result.model } : {}),
793 ...(result?.status !== undefined ? { status: result.status } : {}),
794 ...(result?.providerJobId !== undefined
795 ? { providerJobId: result.providerJobId }
796 : {}),
797 ...(result?.expiresAt !== undefined
798 ? { expiresAt: result.expiresAt }
799 : {}),
800 ...(result?.text !== undefined ? { text: result.text } : {}),
801 ...(result?.usage !== undefined ? { usage: result.usage } : {}),
802 ...(snapshot.activity !== undefined
803 ? { activity: snapshot.activity }
804 : {}),
805 artifacts: result?.artifacts ?? [],
806 }
807 return build(restored)
808 }
809
810 /**
811 * The plain (non-Response) fetcher path never observes stream chunks, so
812 * the terminal snapshot is built here from the fetcher's own result. A
813 * stale `error` from a previous run is intentionally dropped — this run
814 * succeeded.
815 */
816 private completePlainFetcherResumeSnapshot(rawResult: unknown): void {
817 const previous = this.resumeSnapshot
818 const result = createGenerationResultSnapshot(rawResult)
819 this.resumeSnapshot = {
820 schemaVersion: 1,
821 resumeState: null,
822 status: 'complete',
823 ...(previous?.activity ? { activity: previous.activity } : {}),
824 ...(previous?.pendingArtifacts && previous.pendingArtifacts.length > 0
825 ? { pendingArtifacts: [...previous.pendingArtifacts] }
826 : {}),
827 ...(result
828 ? { result }
829 : previous?.result
830 ? { result: { ...previous.result } }
831 : {}),
832 }
833 this.notifyResumeSnapshotChanged()
834 }
835
836 /**
837 * Records a transport-level failure (network drop, throwing callback) in
838 * the snapshot. Without this, only a server-emitted RUN_ERROR chunk would
839 * mark the snapshot `error`, leaving a persisted record that claims the
840 * run is still in flight.
841 */
842 private recordResumeSnapshotError(error: Error): void {
843 // Surface the failure on the OBSERVABLE fields FIRST: a rejoin (or live
844 // stream) that emits RUN_ERROR has already flipped the snapshot to `error`
845 // via `observeResumeSnapshot`, so the early-return below would otherwise
846 // skip this and leave `status` stuck on `generating` — the run would look
847 // like it is still going forever. The guard avoids a duplicate `error`
848 // emission on the live `generate()` path, which sets the status itself.
849 if (this.status !== 'error') this.setStatus('error')
850 this.setError(error)
851 if (this.resumeSnapshot?.status === 'error') return
852 if (!this.resumeSnapshot && !this.serverDriven) return
853 const previous = this.resumeSnapshot
854 this.resumeSnapshot = {
855 schemaVersion: 1,
856 resumeState: null,
857 status: 'error',
858 ...(previous?.activity ? { activity: previous.activity } : {}),
859 ...(previous?.pendingArtifacts && previous.pendingArtifacts.length > 0
860 ? { pendingArtifacts: [...previous.pendingArtifacts] }
861 : {}),
862 ...(previous?.result ? { result: { ...previous.result } } : {}),
863 error: { message: error.message },
864 }
865 this.notifyResumeSnapshotChanged()
866 }
867
868 /**
869 * Drop the client's in-memory snapshot and re-emit. Purely local — this
870 * client writes no storage, so nothing persisted is removed.
871 */
872 private clearResumeSnapshot(): void {
873 this.resumeSnapshot = undefined
874 this.lastEmittedResumeState = undefined
875 this.notifyResumeSnapshotChanged()
876 }
877
878 /**
879 * Server-driven mount hydration entry point (`persistence: true`). Runs at
880 * most once, from the commit-phase mount path (`mountDevtools`) — never the
881 * constructor / render phase — so remounts and speculative renders can't
882 * re-fire the hydrate GET.
883 */
884 private maybeHydrateFromServer(): void {
885 if (!this.serverDriven || this.serverHydrationStarted) return
886 this.serverHydrationStarted = true
887 if (this.connection?.hydrateGeneration ?? this.hydrateGenerationHandler) {
888 this.hydrateFromServer()
889 } else {
890 // `persistence: true` without any hydrate source can never restore
891 // anything — warn rather than silently no-op.
892 console.warn(
893 '[TanStack AI] `persistence: true` (server-driven) needs a `hydrateGeneration` handler — either a connection that implements one (e.g. `fetchServerSentEvents` / `fetchHttpStream`, or `stream()` / `rpcStream()` with persistence handlers) or the `hydrateGeneration` option. Without one, nothing is persisted or restored.',
894 )
895 }
896 }
897
898 /**
899 * Server-driven mount hydration (`persistence: true`). The client holds no
900 * local snapshot; on mount it asks the server — keyed by the stable threadId —
901 * for the last generation's resume snapshot, validates it, and repaints it. It
902 * never auto-starts a run, and never blocks: a `generate()` that starts first
903 * owns the client and hydration backs off, mirroring the chat client.
904 *
905 * A genuine **miss** (the server reports no record for the thread) is silent —
906 * a fresh thread is not an error. A genuine **failure** (transport error, a
907 * 403 from the authorize gate, a malformed body, a record the client's own
908 * validator rejects) is surfaced through `status` / `error` / `onError`, so a
909 * broken server is distinguishable from an empty one and the app can retry.
910 */
911 private hydrateFromServer(): void {
912 const hydrate =
913 this.connection?.hydrateGeneration ?? this.hydrateGenerationHandler
914 if (!hydrate) return
915 // A send that already started owns the client; don't stomp it.
916 if (this.resumeSnapshot || this.isLoading || this.status !== 'idle') return
917 void (async () => {
918 let res: GenerationHydrationResult
919 try {
920 res = await hydrate(this.threadId)
921 } catch (cause) {
922 this.failHydration(
923 createGenerationHydrationError(
924 'the request to the server did not succeed',
925 cause,
926 ),
927 )
928 return
929 }
930 // No record for this thread — a fresh thread, not a failure.
931 if (!res.resumeSnapshot) return
932 const snapshot = parseGenerationResumeSnapshot(res.resumeSnapshot)
933 if (!snapshot) {
934 this.failHydration(
935 createGenerationHydrationError(
936 'the server returned a record this client cannot read (unknown schema version, or a missing/invalid `status` or `resumeState`)',
937 ),
938 )
939 return
940 }
941 // Re-check: a send may have started while the fetch was in flight.
942 if (this.resumeSnapshot || this.isLoading || this.status !== 'idle')
943 return
944 // A run still generating on the server: re-attach and finish it in place.
945 this.repaintRestoredSnapshot(snapshot, res.activeRun?.runId)
946 })()
947 }
948
949 /**
950 * Surface a hydration failure on the observable fields. Skipped when a
951 * `generate()` took ownership while the hydrate GET was in flight — the live
952 * run's state must win over a stale mount-time failure.
953 */
954 private failHydration(error: Error): void {
955 if (this.resumeSnapshot || this.isLoading || this.status !== 'idle') return
956 this.setStatus('error')
957 this.setError(error)
958 this.callbacksRef.onError?.(error)
959 }
960
961 /**
962 * Re-attach to an already-loaded `running` snapshot (the remount case). Safe
963 * to call repeatedly: `rejoinInFlight` dedupes on `rejoinedRunId` and bails
964 * when a run is already in flight, so on the first mount (where the rejoin was
965 * already started from `repaintRestoredSnapshot`) this is a no-op.
966 */
967 private maybeResumeInFlight(): void {
968 if (this.resumeSnapshot?.status !== 'running') return
969 const runId = this.resumeSnapshot.resumeState?.runId
970 if (runId) this.rejoinInFlight(runId)
971 }
972
973 /**
974 * Re-attach to a run that is still generating and stream it to completion,
975 * mirroring the chat client's mount-time rejoin. Reuses `processStream`, so
976 * `result` / `progress` / `status` repaint from the replayed chunks exactly as
977 * a live run does. Best-effort: a live `generate()` owns the client and is
978 * never stomped, and the same run is only rejoined once.
979 */
980 private rejoinInFlight(runId: string): void {
981 const joinRun = this.connection?.joinRun ?? this.joinRunHandler
982 if (!joinRun) return
983 if (this.rejoinedRunId === runId) return
984 // A fresh send (or an in-progress rejoin) owns the client.
985 if (this.isLoading || this.abortController) return
986 this.rejoinedRunId = runId
987 const controller = new AbortController()
988 this.abortController = controller
989 this.setIsLoading(true)
990 this.setStatus('generating')
991 void (async () => {
992 try {
993 await this.processStream(
994 joinRun(runId, controller.signal),
995 runId,
996 controller.signal,
997 )
998 } catch (error) {
999 if (!controller.signal.aborted) {
1000 const failure =
1001 error instanceof Error ? error : new Error(String(error))
1002 // Settles `status`/`error` AND rewrites the snapshot to a terminal
1003 // `error` with a null `resumeState`, so the next mount does not
1004 // rejoin this run again.
1005 this.recordResumeSnapshotError(failure)
1006 this.callbacksRef.onError?.(failure)
1007 }
1008 } finally {
1009 // Only reset if this rejoin still owns the client: a `stop()` +
1010 // fresh `generate()` may have replaced the controller while the tail
1011 // was settling, and that live run owns `isLoading` now.
1012 if (this.abortController === controller) {
1013 this.abortController = null
1014 this.setIsLoading(false)
1015 }
1016 }
1017 })()
1018 }
1019}
1020
1021function completeProgressValue(
1022 progress: AIDevtoolsGenerationProgress | null,
1023): AIDevtoolsGenerationProgress | null {
1024 if (!progress) return null
1025 const message = progress.message
1026 return {
1027 value: 100,
1028 ...(message ? { message } : {}),
1029 }
1030}