@tanstack/ai-client 0.20.0 → 0.22.0

package/src/realtime-client.ts

@@ -4,6 +4,7 @@ import type {
   AudioVisualization,
   RealtimeMessage,
   RealtimeMode,
+  RealtimeSessionConfig,
   RealtimeStatus,
   RealtimeToken,
 } from '@tanstack/ai/client'
@@ -101,6 +102,7 @@ export class RealtimeClient {
         this.clientTools.size > 0
           ? Array.from(this.clientTools.values())
           : undefined
+
       this.connection = await this.options.adapter.connect(
         this.token,
         toolsList,
@@ -282,6 +284,38 @@ export class RealtimeClient {
     return this.connection?.getAudioVisualization() ?? null
   }
 
+  /**
+   * Update the session configuration.
+   * This applies changes to the active connection and persists them for future reconnections.
+   */
+  updateSession(config: Partial<RealtimeSessionConfig>): void {
+    // Persist type-compatible fields so future (re)connections use the updated
+    // config. `tools` is intentionally excluded: a session's tool configs are
+    // serialized descriptors, whereas `options.tools` holds executable client
+    // tools tracked separately via `clientTools`.
+    const o = this.options
+    if (config.instructions !== undefined) o.instructions = config.instructions
+    if (config.voice !== undefined) o.voice = config.voice
+    if (config.vadMode !== undefined) o.vadMode = config.vadMode
+    if (config.outputModalities !== undefined) {
+      o.outputModalities = config.outputModalities
+    }
+    if (config.temperature !== undefined) o.temperature = config.temperature
+    if (config.maxOutputTokens !== undefined) {
+      o.maxOutputTokens = config.maxOutputTokens
+    }
+    if (config.semanticEagerness !== undefined) {
+      o.semanticEagerness = config.semanticEagerness
+    }
+    if (config.providerOptions !== undefined) {
+      o.providerOptions = config.providerOptions
+    }
+
+    if (this.connection) {
+      this.applySessionConfig()
+    }
+  }
+
   // ============================================================================
   // State Subscription
   // ============================================================================
@@ -353,6 +387,7 @@ export class RealtimeClient {
     try {
       this.token = await this.options.getToken()
       this.scheduleTokenRefresh()
+      this.connection?.updateToken?.(this.token)
       // Note: Some providers may require reconnection with new token
       // This is handled by the adapter implementation
     } catch (error) {
@@ -487,6 +522,18 @@ export class RealtimeClient {
         this.options.onError?.(error)
       }),
     )
+
+    this.unsubscribers.push(
+      this.connection.on('go_away', ({ timeLeft }) => {
+        this.options.onGoAway?.(timeLeft)
+      }),
+    )
+
+    this.unsubscribers.push(
+      this.connection.on('usage', (usage) => {
+        this.options.onUsage?.(usage)
+      }),
+    )
   }
 
   private applySessionConfig(): void {
@@ -513,18 +560,22 @@ export class RealtimeClient {
       semanticEagerness
     if (!hasConfig) return
 
-    // `RealtimeToolConfig.inputSchema` is `Record<string, any>` (no
-    // `undefined` under `exactOptionalPropertyTypes`). Conditionally spread
-    // it so we don't pass `undefined` when the tool has no input schema.
+    // `RealtimeToolConfig.inputSchema`/`outputSchema` are `Record<string, any>`
+    // (no `undefined` under `exactOptionalPropertyTypes`). Conditionally spread
+    // each so we don't pass `undefined` when the tool has no such schema.
     const toolsConfig = tools
       ? Array.from(this.clientTools.values()).map((t) => {
           const inputSchema = t.inputSchema
             ? convertSchemaToJsonSchema(t.inputSchema)
             : undefined
+          const outputSchema = t.outputSchema
+            ? convertSchemaToJsonSchema(t.outputSchema)
+            : undefined
           return {
             name: t.name,
             description: t.description,
             ...(inputSchema ? { inputSchema } : {}),
+            ...(outputSchema ? { outputSchema } : {}),
           }
         })
       : undefined

package/src/realtime-types.ts

@@ -6,6 +6,7 @@ import type {
   RealtimeStatus,
   RealtimeToken,
 } from '@tanstack/ai/client'
+import type { UsageInfo } from '@tanstack/ai'
 
 // The realtime adapter contract lives in `@tanstack/ai` (the shared layer both
 // providers and this client depend on) so provider packages don't need to
@@ -82,6 +83,11 @@ export interface RealtimeClientOptions {
    */
   semanticEagerness?: 'low' | 'medium' | 'high'
 
+  /**
+   * Provider-specific options
+   */
+  providerOptions?: Record<string, unknown>
+
   // Callbacks
   onStatusChange?: (status: RealtimeStatus) => void
   onModeChange?: (mode: RealtimeMode) => void
@@ -90,6 +96,8 @@ export interface RealtimeClientOptions {
   onConnect?: () => void
   onDisconnect?: () => void
   onInterrupted?: () => void
+  onUsage?: (usage: UsageInfo) => void
+  onGoAway?: (timeLeft?: string) => void
 }
 
 // ============================================================================

package/src/types.ts

@@ -144,6 +144,88 @@ export interface MultimodalContent {
   id?: string
 }
 
+/**
+ * Action taken when `sendMessage` is called while the client is busy
+ * (streaming, claiming a send, or draining the queue).
+ * - `queue`: hold the message; it auto-sends when the current run settles
+ *   **successfully**.
+ * - `drop`: ignore the send (promise still resolves; does not throw).
+ * - `interrupt`: abort the current stream and send immediately. Unlike
+ *   `stop()`, does **not** flush already-queued messages — they still drain
+ *   after the interrupting send settles successfully.
+ */
+export type WhenBusy = 'queue' | 'drop' | 'interrupt'
+
+/**
+ * Why the client is busy when a {@link QueueStrategy} runs.
+ * - `streaming` — an LLM stream is active (`isLoading`).
+ * - `sendInFlight` — a send has claimed the client but is not yet loading.
+ * - `draining` — the queue drain loop is delivering pending messages.
+ */
+export type QueueBusyReason = 'streaming' | 'sendInFlight' | 'draining'
+
+/**
+ * A user message held in the send queue while a stream is active.
+ * Rendered separately from `messages`; cancellable via `cancelQueued(id)`
+ * until it drains.
+ */
+export interface QueuedMessage {
+  id: string
+  content: string | MultimodalContent
+  createdAt: number
+}
+
+/**
+ * Declarative queue policy.
+ */
+export interface QueueConfig {
+  /**
+   * Action when the client is busy (streaming, claiming a send, or draining).
+   * Default `'queue'`.
+   */
+  whenBusy?: WhenBusy
+  /**
+   * How queued items leave the queue.
+   * - `'fifo'`: one at a time, in order (default).
+   * - `'batch'`: merge all queued items into one send when the run settles
+   *   successfully.
+   */
+  drain?: 'fifo' | 'batch'
+  /** Max queued items. Unlimited when omitted. `0` means never queue. */
+  maxSize?: number
+  /**
+   * Behavior when `maxSize` is reached. Default `'reject'`.
+   * `'reject'` silently discards the new send (does not throw);
+   * `'drop-oldest'` evicts the oldest queued item to make room.
+   * Only meaningful when `maxSize` is set.
+   */
+  onOverflow?: 'reject' | 'drop-oldest'
+}
+
+/**
+ * Escape hatch: decide the action for a single send. Drain stays FIFO for the
+ * function form (no `batch` via function). Per-call `sendOptions.whenBusy`
+ * overrides the strategy for that send.
+ *
+ * Actions match {@link WhenBusy}: `'queue' | 'drop' | 'interrupt'`. Concurrent
+ * streams are not supported. `pending.id` is the id that will be stored if the
+ * action is `'queue'` (safe to pass to `cancelQueued`).
+ */
+export type QueueStrategy = (ctx: {
+  pending: QueuedMessage
+  busyReason: QueueBusyReason
+  queued: ReadonlyArray<QueuedMessage>
+}) => { action: WhenBusy }
+
+/** A `WhenBusy` shorthand, a full config, or a strategy function. */
+export type QueueOption = WhenBusy | QueueConfig | QueueStrategy
+
+/** Per-call overrides for `sendMessage`. */
+export interface SendMessageOptions {
+  /** Overrides the configured `whenBusy` for this one send. */
+  whenBusy?: WhenBusy
+}
+
 /**
  * Message parts - building blocks of UIMessage
  */
@@ -166,15 +248,27 @@ type ToolCallPartForTool<T> = T extends AnyClientTool
       /** Parsed tool input (typed from inputSchema) */
       input?: InferToolInput<T>
       state: ToolCallState
-      /** Approval metadata if tool requires user approval */
-      approval?: {
-        id: string // Unique approval ID
-        needsApproval: boolean // Always true if present
-        approved?: boolean // User's decision (undefined until responded)
-      }
       /** Tool execution output (for client tools or after approval) */
       output?: InferToolOutput<T>
-    }
+    } & (NonNullable<T['needsApproval']> extends true
+      ? {
+          /**
+           * Approval metadata — present only on tools defined with
+           * `needsApproval: true`. Populated once the call reaches
+           * `state: 'approval-requested'`. `needsApproval` is an optional
+           * property on the tool, so we index into it (rather than
+           * `T extends { needsApproval: true }`, which an optional property
+           * never satisfies) and strip `undefined` before comparing to `true`.
+           */
+          approval?: {
+            id: string // Unique approval ID
+            needsApproval: boolean // Always true if present
+            approved?: boolean // User's decision (undefined until responded)
+          }
+        }
+      : // Tools without `needsApproval: true` never carry an approval field.
+        // `& unknown` is a no-op intersection (adds nothing).
+        unknown)
   : never
 
 /**
@@ -480,6 +574,23 @@ export interface ChatClientBaseOptions<
    */
   onSessionGeneratingChange?: (isGenerating: boolean) => void
 
+  /**
+   * Policy for messages sent while the client is busy (streaming, claiming
+   * a send, or draining the queue). Accepts a `WhenBusy` string, a
+   * `QueueConfig`, or a `QueueStrategy` function.
+   * Default: `{ whenBusy: 'queue', drain: 'fifo' }`.
+   * Queued items auto-send only after a **successful** settle; they are
+   * discarded on error/abort, `stop()`, `clear()`, `unsubscribe()`, and
+   * `reload()`.
+   */
+  queue?: QueueOption
+
+  /**
+   * Callback when the pending send queue changes (enqueue, cancel, drain,
+   * or flush).
+   */
+  onQueueChange?: (queue: Array<QueuedMessage>) => void
+
   /**
    * Callback when a custom event is received from a server-side tool.
    * Custom events are emitted by tools using `context.emitCustomEvent()` during execution.