@tanstack/ai-svelte 0.15.1 → 0.16.1

package/src/create-chat.svelte.ts

@@ -1,7 +1,11 @@
 import { ChatClient } from '@tanstack/ai-client'
 import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'
+import { onMount } from 'svelte'
 import type {
   ChatClientState,
+  ChatInterrupt,
+  ChatInterruptState,
+  ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
   QueuedMessage,
@@ -12,6 +16,7 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
   StreamChunk,
 } from '@tanstack/ai'
@@ -23,6 +28,9 @@ import type {
   UIMessage,
 } from './types'
 
+const EMPTY_INTERRUPTS = Object.freeze([])
+const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
+
 /**
  * Creates a reactive chat instance for Svelte 5.
  *
@@ -60,11 +68,6 @@ export function createChat<
 >(
   options: CreateChatOptions<TTools, TSchema, TContext>,
 ): CreateChatReturn<TTools, TSchema, TContext> {
-  // Generate a unique ID for this chat instance
-  const clientId =
-    options.id ||
-    `chat-${Date.now()}-${Math.random().toString(36).substring(7)}`
-
   // Create reactive state using Svelte 5 runes
   let messages = $state<Array<UIMessage<TTools>>>(options.initialMessages || [])
   let isLoading = $state(false)
@@ -74,6 +77,13 @@ export function createChat<
   let connectionStatus = $state<ConnectionStatus>('disconnected')
   let sessionGenerating = $state(false)
   let queue = $state<Array<QueuedMessage>>([])
+  let runId = $state<string | null>(null)
+  let interruptState = $state.raw<ChatInterruptState<TTools>>({
+    interrupts: EMPTY_INTERRUPTS,
+    pendingInterrupts: EMPTY_INTERRUPTS,
+    interruptErrors: EMPTY_INTERRUPT_ERRORS,
+    resuming: false,
+  })
 
   // Structured-output `partial` / `final` are derived from `messages` —
   // specifically from the structured-output part on the latest assistant
@@ -96,16 +106,21 @@ export function createChat<
     ? { connection: options.connection }
     : { fetcher: options.fetcher }
 
+  // The hook's identity is its `threadId`, which ChatClient also uses as the
+  // persistence key — no separate `id`. When no `threadId` is given the client
+  // generates one, so an ephemeral chat still works but is not restored on reload.
   const client = new ChatClient<TTools, TContext>({
     devtoolsBridgeFactory: createChatDevtoolsBridge,
     ...transport,
-    id: clientId,
     ...(options.initialMessages !== undefined && {
       initialMessages: options.initialMessages,
     }),
     ...(options.persistence !== undefined && {
       persistence: options.persistence,
     }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     ...(options.body !== undefined && { body: options.body }),
     ...(options.threadId !== undefined && { threadId: options.threadId }),
     ...(options.forwardedProps !== undefined && {
@@ -140,6 +155,7 @@ export function createChat<
     },
     onLoadingChange: (newIsLoading: boolean) => {
       isLoading = newIsLoading
+      syncResumeState()
     },
     onStatusChange: (newStatus: ChatClientState) => {
       status = newStatus
@@ -160,9 +176,22 @@ export function createChat<
     onQueueChange: (nextQueue: Array<QueuedMessage>) => {
       queue = nextQueue
     },
+    onRunIdChange: (nextRunId) => {
+      runId = nextRunId
+    },
+    onInterruptStateChange: (nextInterruptState) => {
+      interruptState = nextInterruptState
+      options.onInterruptStateChange?.(nextInterruptState)
+    },
   })
 
+  function syncResumeState() {
+    runId = client.getCurrentRunId()
+    interruptState = client.getInterruptState()
+  }
+
   messages = client.getMessages()
+  interruptState = client.getInterruptState()
 
   if (options.live) {
     client.subscribe()
@@ -170,27 +199,64 @@ export function createChat<
 
   client.mountDevtools()
 
-  // Note: Cleanup is handled by calling stop() directly when needed.
-  // Unlike React/Vue/Solid, Svelte 5 runes like $effect can only be used
-  // during component initialization, so we don't add automatic cleanup here.
-  // Users should call chat.stop() in their component's cleanup if needed.
+  if (typeof window !== 'undefined') {
+    try {
+      onMount(() => {
+        // Delivery-durability resume is transparent: the resumable SSE
+        // connection adapter reattaches via the browser's native
+        // Last-Event-ID on reconnect. We only seed interrupt (state) resume.
+        syncResumeState()
+        client.attach()
+        // ONLY THE VIEW ON SCREEN HOLDS A STREAM. `onMount`'s returned function
+        // runs when the component is destroyed, which is the one automatic
+        // teardown Svelte gives us here — and it is enough, because a connection
+        // is all that must go. A page can own many chats and a browser allows
+        // only ~6 connections per origin, so one long-lived stream per chat
+        // starves every other request once a few views have been open.
+        //
+        // `detach` keeps the transcript and the resume pointer, so re-entering
+        // the view picks the run back up from the durable log.
+        return () => {
+          client.detach()
+        }
+      })
+    } catch {
+      // Svelte lifecycle hooks are only valid during component initialization.
+    }
+  }
+
+  // Note: `dispose()` remains manual — it releases devtools and marks the client
+  // dead, which only the owner can decide. The CONNECTION is released
+  // automatically by the `onMount` teardown above.
 
   // Define methods
   const sendMessage = async (
     content: string | MultimodalContent,
     sendOptions?: SendMessageOptions,
   ) => {
-    await client.sendMessage(content, undefined, sendOptions)
+    try {
+      await client.sendMessage(content, undefined, sendOptions)
+    } finally {
+      syncResumeState()
+    }
   }
 
   const cancelQueued = (id: string) => client.cancelQueued(id)
 
   const append = async (message: ModelMessage | UIMessage<TTools>) => {
-    await client.append(message)
+    try {
+      await client.append(message)
+    } finally {
+      syncResumeState()
+    }
   }
 
   const reload = async () => {
-    await client.reload()
+    try {
+      await client.reload()
+    } finally {
+      syncResumeState()
+    }
   }
 
   const stop = () => {
@@ -203,6 +269,7 @@ export function createChat<
 
   const clear = () => {
     client.clear()
+    syncResumeState()
   }
 
   const setMessages = (newMessages: Array<UIMessage<TTools>>) => {
@@ -224,8 +291,41 @@ export function createChat<
     approved: boolean
   }) => {
     await client.addToolApprovalResponse(response)
+    syncResumeState()
   }
 
+  const resumeInterrupts = async (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => {
+    const result = await client.resumeInterrupts(resumeItems, state)
+    syncResumeState()
+    return result
+  }
+
+  const resolveInterrupts = (
+    resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+  ) => {
+    if (typeof resolution === 'boolean') {
+      client.resolveInterrupts(resolution)
+    } else {
+      client.resolveInterrupts(resolution)
+    }
+  }
+
+  const cancelInterrupts = () => {
+    client.cancelInterrupts()
+  }
+
+  const retryInterrupts = () => {
+    client.retryInterrupts()
+  }
+
+  const resumeInterruptsUnsafe = (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => client.resumeInterruptsUnsafe(resumeItems, state)
+
   /**
    * @deprecated Use `updateForwardedProps` instead.
    * Both populate the same wire payload.
@@ -282,7 +382,7 @@ export function createChat<
 
   // Return the chat interface with reactive getters
   // Using getters allows Svelte to track reactivity without needing $ prefix
-  // eslint-disable-next-line no-restricted-syntax -- rune return shape diverges from generic CreateChatReturn<TTools, TSchema, TContext> due to TSchema conditional partial/final fields; TS can't structurally narrow.
+  // oxlint-disable-next-line eslint-js/no-restricted-syntax -- rune return shape diverges from generic CreateChatReturn<TTools, TSchema, TContext> due to TSchema conditional partial/final fields; TS can't structurally narrow.
   return {
     get messages() {
       return messages
@@ -308,6 +408,21 @@ export function createChat<
     get queue() {
       return queue
     },
+    get runId() {
+      return runId
+    },
+    get interrupts() {
+      return interruptState.interrupts
+    },
+    get pendingInterrupts() {
+      return interruptState.interrupts
+    },
+    get interruptErrors() {
+      return interruptState.interruptErrors
+    },
+    get resuming() {
+      return interruptState.resuming
+    },
     get partial() {
       return partial
     },
@@ -324,6 +439,11 @@ export function createChat<
     clear,
     addToolResult,
     addToolApprovalResponse,
+    resolveInterrupts,
+    cancelInterrupts,
+    retryInterrupts,
+    resumeInterruptsUnsafe,
+    resumeInterrupts,
     updateBody,
     updateForwardedProps,
     updateContext,

package/src/create-generate-audio.svelte.ts

@@ -1,4 +1,9 @@
 import { createGeneration } from './create-generation.svelte'
+import { reconstructAudioResult } from '@tanstack/ai-client'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.svelte'
 import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -6,6 +11,7 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
 
@@ -14,12 +20,19 @@ import type {
  *
  * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)
  */
-export interface CreateGenerateAudioOptions<TOutput = AudioGenerationResult> {
+export interface CreateGenerateAudioOptions<
+  TOutput = AudioGenerationResult,
+> extends Pick<
+  CreateGenerationOptions<AudioGenerateInput, AudioGenerationResult, TOutput>,
+  'persistence' | 'threadId' | 'hydrateGeneration' | 'joinRun'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for audio generation */
   fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>
-  /** Unique identifier for this generation instance */
+  /**
+   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+   */
   id?: string
   /** Additional body parameters to send with connect-based adapter requests */
   body?: Record<string, any>
@@ -46,7 +59,9 @@ export interface CreateGenerateAudioOptions<TOutput = AudioGenerationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface CreateGenerateAudioReturn<TOutput = AudioGenerationResult> {
+export interface CreateGenerateAudioReturn<
+  TOutput = AudioGenerationResult,
+> extends Omit<CreateGenerationReturn<TOutput>, 'generate'> {
   /** The generation result containing audio, or null */
   readonly result: TOutput | null
   /** Whether generation is in progress */
@@ -57,12 +72,6 @@ export interface CreateGenerateAudioReturn<TOutput = AudioGenerationResult> {
   readonly status: GenerationClientState
   /** Trigger audio generation */
   generate: (input: AudioGenerateInput) => Promise<void>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
-  /** Update additional body parameters */
-  updateBody: (body: Record<string, any>) => void
 }
 
 /**
@@ -92,9 +101,12 @@ export interface CreateGenerateAudioReturn<TOutput = AudioGenerationResult> {
  * ```
  */
 export function createGenerateAudio<TTransformed = void>(
-  options: Omit<CreateGenerateAudioOptions, 'onResult'> & {
+  options: Omit<
+    CreateGenerateAudioOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: AudioGenerationResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): CreateGenerateAudioReturn<
   InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>
 > {
@@ -111,6 +123,7 @@ export function createGenerateAudio<TTransformed = void>(
   >({
     ...options,
     devtools,
+    reconstructResult: reconstructAudioResult,
   })
 
   return {
@@ -126,9 +139,13 @@ export function createGenerateAudio<TTransformed = void>(
     get status() {
       return gen.status
     },
-    generate: gen.generate as (input: AudioGenerateInput) => Promise<void>,
+    generate: gen.generate,
     stop: gen.stop,
     reset: gen.reset,
     updateBody: gen.updateBody,
+    dispose: gen.dispose,
+    get runId() {
+      return gen.runId
+    },
   }
 }

package/src/create-generate-image.svelte.ts

@@ -1,10 +1,16 @@
 import { createGeneration } from './create-generation.svelte'
+import { reconstructImageResult } from '@tanstack/ai-client'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.svelte'
 import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   ImageGenerateInput,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
@@ -14,12 +20,19 @@ import type {
  *
  * @template TOutput - The output type after optional transform (defaults to ImageGenerationResult)
  */
-export interface CreateGenerateImageOptions<TOutput = ImageGenerationResult> {
+export interface CreateGenerateImageOptions<
+  TOutput = ImageGenerationResult,
+> extends Pick<
+  CreateGenerationOptions<ImageGenerateInput, ImageGenerationResult, TOutput>,
+  'persistence' | 'threadId' | 'hydrateGeneration' | 'joinRun'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for image generation */
   fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>
-  /** Unique identifier for this generation instance */
+  /**
+   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+   */
   id?: string
   /** Additional body parameters to send with connect-based adapter requests */
   body?: Record<string, any>
@@ -46,7 +59,9 @@ export interface CreateGenerateImageOptions<TOutput = ImageGenerationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface CreateGenerateImageReturn<TOutput = ImageGenerationResult> {
+export interface CreateGenerateImageReturn<
+  TOutput = ImageGenerationResult,
+> extends Omit<CreateGenerationReturn<TOutput>, 'generate'> {
   /** The generation result containing images, or null */
   readonly result: TOutput | null
   /** Whether generation is in progress */
@@ -57,12 +72,6 @@ export interface CreateGenerateImageReturn<TOutput = ImageGenerationResult> {
   readonly status: GenerationClientState
   /** Trigger image generation */
   generate: (input: ImageGenerateInput) => Promise<void>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
-  /** Update additional body parameters */
-  updateBody: (body: Record<string, any>) => void
 }
 
 /**
@@ -101,9 +110,12 @@ export interface CreateGenerateImageReturn<TOutput = ImageGenerationResult> {
  * ```
  */
 export function createGenerateImage<TTransformed = void>(
-  options: Omit<CreateGenerateImageOptions, 'onResult'> & {
+  options: Omit<
+    CreateGenerateImageOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: ImageGenerationResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): CreateGenerateImageReturn<
   InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>
 > {
@@ -120,6 +132,7 @@ export function createGenerateImage<TTransformed = void>(
   >({
     ...options,
     devtools,
+    reconstructResult: reconstructImageResult,
   })
 
   return {
@@ -135,9 +148,13 @@ export function createGenerateImage<TTransformed = void>(
     get status() {
       return gen.status
     },
-    generate: gen.generate as (input: ImageGenerateInput) => Promise<void>,
+    generate: gen.generate,
     stop: gen.stop,
     reset: gen.reset,
     updateBody: gen.updateBody,
+    dispose: gen.dispose,
+    get runId() {
+      return gen.runId
+    },
   }
 }

package/src/create-generate-speech.svelte.ts

@@ -1,10 +1,16 @@
 import { createGeneration } from './create-generation.svelte'
+import { reconstructSpeechResult } from '@tanstack/ai-client'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.svelte'
 import type { StreamChunk, TTSResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   InferGenerationOutputFromReturn,
   SpeechGenerateInput,
 } from '@tanstack/ai-client'
@@ -14,12 +20,17 @@ import type {
  *
  * @template TOutput - The output type after optional transform (defaults to TTSResult)
  */
-export interface CreateGenerateSpeechOptions<TOutput = TTSResult> {
+export interface CreateGenerateSpeechOptions<TOutput = TTSResult> extends Pick<
+  CreateGenerationOptions<SpeechGenerateInput, TTSResult, TOutput>,
+  'persistence' | 'threadId' | 'hydrateGeneration' | 'joinRun'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for speech generation */
   fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>
-  /** Unique identifier for this generation instance */
+  /**
+   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+   */
   id?: string
   /** Additional body parameters to send with connect-based adapter requests */
   body?: Record<string, any>
@@ -46,7 +57,10 @@ export interface CreateGenerateSpeechOptions<TOutput = TTSResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface CreateGenerateSpeechReturn<TOutput = TTSResult> {
+export interface CreateGenerateSpeechReturn<TOutput = TTSResult> extends Omit<
+  CreateGenerationReturn<TOutput>,
+  'generate'
+> {
   /** The TTS result containing audio data, or null */
   readonly result: TOutput | null
   /** Whether generation is in progress */
@@ -57,12 +71,6 @@ export interface CreateGenerateSpeechReturn<TOutput = TTSResult> {
   readonly status: GenerationClientState
   /** Trigger speech generation */
   generate: (input: SpeechGenerateInput) => Promise<void>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
-  /** Update additional body parameters */
-  updateBody: (body: Record<string, any>) => void
 }
 
 /**
@@ -92,9 +100,12 @@ export interface CreateGenerateSpeechReturn<TOutput = TTSResult> {
  * ```
  */
 export function createGenerateSpeech<TTransformed = void>(
-  options: Omit<CreateGenerateSpeechOptions, 'onResult'> & {
+  options: Omit<
+    CreateGenerateSpeechOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: TTSResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): CreateGenerateSpeechReturn<
   InferGenerationOutputFromReturn<TTSResult, TTransformed>
 > {
@@ -107,6 +118,7 @@ export function createGenerateSpeech<TTransformed = void>(
   const gen = createGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
     ...options,
     devtools,
+    reconstructResult: reconstructSpeechResult,
   })
 
   return {
@@ -122,9 +134,13 @@ export function createGenerateSpeech<TTransformed = void>(
     get status() {
       return gen.status
     },
-    generate: gen.generate as (input: SpeechGenerateInput) => Promise<void>,
+    generate: gen.generate,
     stop: gen.stop,
     reset: gen.reset,
     updateBody: gen.updateBody,
+    dispose: gen.dispose,
+    get runId() {
+      return gen.runId
+    },
   }
 }