@tanstack/ai 0.40.0 → 0.42.0

package/src/activities/generateVideo/index.ts

@@ -17,10 +17,10 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { VideoAdapter } from './adapter'
 import type {
   MediaPrompt,
@@ -47,7 +47,7 @@ export const kind = 'video' as const
  * Extract provider options from a VideoAdapter via ~types.
  */
 export type VideoProviderOptions<TAdapter> =
-  TAdapter extends VideoAdapter<any, any, any, any>
+  TAdapter extends VideoAdapter<any, any, any, any, any, any>
     ? TAdapter['~types']['providerOptions']
     : object
 
@@ -55,7 +55,14 @@ export type VideoProviderOptions<TAdapter> =
  * Extract the size type for a VideoAdapter's model via ~types.
  */
 export type VideoSizeForAdapter<TAdapter> =
-  TAdapter extends VideoAdapter<infer TModel, any, any, infer TSizeMap>
+  TAdapter extends VideoAdapter<
+    infer TModel,
+    any,
+    any,
+    infer TSizeMap,
+    any,
+    any
+  >
     ? TModel extends keyof TSizeMap
       ? TSizeMap[TModel]
       : string
@@ -68,7 +75,14 @@ export type VideoSizeForAdapter<TAdapter> =
  * without a map fall back to the full MediaPrompt.
  */
 export type VideoPromptForAdapter<TAdapter> =
-  TAdapter extends VideoAdapter<infer TModel, any, any, any, infer ModsByName>
+  TAdapter extends VideoAdapter<
+    infer TModel,
+    any,
+    any,
+    any,
+    infer ModsByName,
+    any
+  >
     ? string extends keyof ModsByName
       ? MediaPrompt
       : TModel extends keyof ModsByName
@@ -108,7 +122,7 @@ function createId(prefix: string): string {
  * The model is extracted from the adapter's model property.
  */
 interface VideoActivityBaseOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 > {
   /** The video adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
@@ -124,7 +138,7 @@ interface VideoActivityBaseOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export type VideoCreateOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
   TStream extends boolean = false,
 > = VideoActivityBaseOptions<TAdapter> & {
   /** Request type - create a new job (default if not specified) */
@@ -191,7 +205,7 @@ export type VideoCreateOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export interface VideoStatusOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 > extends VideoActivityBaseOptions<TAdapter> {
   /** Request type - get job status */
   request: 'status'
@@ -205,7 +219,7 @@ export interface VideoStatusOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export interface VideoUrlOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 > extends VideoActivityBaseOptions<TAdapter> {
   /** Request type - get video URL */
   request: 'url'
@@ -220,7 +234,7 @@ export interface VideoUrlOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export type VideoActivityOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
   TRequest extends 'create' | 'status' | 'url' = 'create',
   TStream extends boolean = false,
 > = TRequest extends 'status'
@@ -296,7 +310,7 @@ export type VideoActivityResult<
  * ```
  */
 export function generateVideo<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
   TStream extends boolean = false,
 >(
   options: VideoCreateOptions<TAdapter, TStream>,
@@ -314,7 +328,7 @@ export function generateVideo<
  * Internal implementation of non-streaming video job creation.
  */
 async function runCreateVideoJob<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, boolean>): Promise<VideoJobResult> {
   const { adapter, prompt, size, duration, modelOptions, middleware } = options
   const model = adapter.model
@@ -383,7 +397,7 @@ function sleep(ms: number): Promise<void> {
  * Handles the full job lifecycle: create job → poll for status → stream updates → yield final result.
  */
 async function* runStreamingVideoGeneration<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, true>): AsyncIterable<StreamChunk> {
   const { adapter, prompt, size, duration, modelOptions, middleware } = options
   const model = adapter.model
@@ -582,7 +596,7 @@ async function* runStreamingVideoGeneration<
  * ```
  */
 export async function getVideoJobStatus<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 >(options: {
   adapter: TAdapter & { kind: typeof kind }
   jobId: string
@@ -692,7 +706,7 @@ export async function getVideoJobStatus<
  * Create typed options for the generateVideo() function without executing.
  */
 export function createVideoOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
   TStream extends boolean = false,
 >(
   options: VideoCreateOptions<TAdapter, TStream>,

package/src/index.ts

@@ -93,6 +93,7 @@ export { brandProviderTool } from './tools/provider-tool'
 // Agent loop strategies
 export {
   maxIterations,
+  maxToolCalls,
   untilFinishReason,
   combineStrategies,
 } from './activities/chat/agent-loop-strategies'
@@ -179,12 +180,13 @@ export { normalizeSystemPrompts } from './system-prompts'
 export { detectImageMimeType } from './utils'
 
 // Realtime
-export { realtimeToken } from './realtime/index'
+export { realtimeToken, createRealtimeEventEmitter } from './realtime/index'
 export type {
   RealtimeToken,
   RealtimeTokenAdapter,
   RealtimeTokenOptions,
   RealtimeSessionConfig,
+  RealtimeToolConfig,
   VADConfig,
   RealtimeMessage,
   RealtimeMessagePart,

package/src/realtime/event-emitter.ts

@@ -0,0 +1,46 @@
+import type {
+  RealtimeEvent,
+  RealtimeEventHandler,
+  RealtimeEventPayloads,
+} from './types'
+
+/**
+ * Handlers are stored with a `never` payload so any specific
+ * `RealtimeEventHandler<TEvent>` is assignable in (contravariance), keeping the
+ * heterogeneous handler map type-safe without `any`. `emit` narrows back to the
+ * event's real payload type via its signature; the lone `as never` at the call
+ * site is the inverse of that stored `never`.
+ */
+type StoredHandler = (payload: never) => void
+
+export function createRealtimeEventEmitter() {
+  const eventHandlers = new Map<RealtimeEvent, Set<StoredHandler>>()
+
+  return {
+    emit<TEvent extends RealtimeEvent>(
+      event: TEvent,
+      payload: RealtimeEventPayloads[TEvent],
+    ) {
+      const handlers = eventHandlers.get(event)
+      if (!handlers) return
+      for (const handler of handlers) {
+        handler(payload as never)
+      }
+    },
+    on<TEvent extends RealtimeEvent>(
+      event: TEvent,
+      handler: RealtimeEventHandler<TEvent>,
+    ): () => void {
+      let handlers = eventHandlers.get(event)
+      if (!handlers) {
+        handlers = new Set<StoredHandler>()
+        eventHandlers.set(event, handlers)
+      }
+      handlers.add(handler)
+
+      return () => {
+        handlers.delete(handler)
+      }
+    },
+  }
+}

package/src/realtime/index.ts

@@ -1,5 +1,7 @@
 import type { RealtimeToken, RealtimeTokenOptions } from './types'
 
+export { createRealtimeEventEmitter } from './event-emitter'
+
 // Re-export all types
 export type * from './types'
 

package/src/realtime/types.ts

@@ -4,6 +4,8 @@ import type { AnyClientTool } from '../activities/chat/tools/tool-definition'
 // Token Types
 // ============================================================================
 
+import type { UsageInfo } from '../activities/chat/middleware/types'
+
 /**
  * Voice activity detection configuration
  */
@@ -24,6 +26,7 @@ export interface RealtimeToolConfig {
   name: string
   description: string
   inputSchema?: Record<string, any>
+  outputSchema?: Record<string, any>
 }
 
 /**
@@ -246,6 +249,8 @@ export type RealtimeEvent =
   | 'message_complete'
   | 'interrupted'
   | 'error'
+  | 'go_away' // Event that signals that the current connection will soon be terminated
+  | 'usage'
 
 /**
  * Event payloads for realtime events
@@ -263,6 +268,8 @@ export interface RealtimeEventPayloads {
   message_complete: { message: RealtimeMessage }
   interrupted: { messageId?: string }
   error: { error: Error }
+  go_away: { timeLeft?: string }
+  usage: UsageInfo
 }
 
 /**
@@ -355,6 +362,8 @@ export interface RealtimeConnection {
   // Session management
   /** Update session configuration */
   updateSession: (config: Partial<RealtimeSessionConfig>) => void
+  /** Update the ephemeral token (e.g. on refresh); provider may reconnect */
+  updateToken?: (token: RealtimeToken) => void
   /** Interrupt the current response */
   interrupt: () => void
 

package/src/types.ts

@@ -372,6 +372,15 @@ export interface ToolCallPart<TMetadata = unknown> {
   id: string
   name: string
   arguments: string // JSON string (may be incomplete)
+  /**
+   * Parsed tool input. Set from the parsed arguments once they are complete
+   * (`state: 'input-complete'` and later). `undefined` while the raw
+   * `arguments` string is still streaming, and may stay `undefined` for a call
+   * that terminates in an error state — the raw `arguments` string is always
+   * available as a fallback. Typed per-tool on the client `ToolCallPart` (see
+   * `@tanstack/ai-client`); `unknown` on this base type.
+   */
+  input?: unknown
   state: ToolCallState
   /** Approval metadata if tool requires user approval */
   approval?: {
@@ -822,12 +831,24 @@ export interface ResponseFormat<TData = any> {
  * State passed to agent loop strategy for determining whether to continue
  */
 export interface AgentLoopState {
-  /** Current iteration count (0-indexed) */
+  /** Current iteration count (0-indexed). One iteration = one model turn. */
   iterationCount: number
   /** Current messages array */
   messages: Array<ModelMessage>
   /** Finish reason from the last response */
   finishReason: string | null
+  /**
+   * Cumulative tool calls counted so far in this run (model-emitted during the
+   * agent loop, including ones skipped by `maxToolCallsPerTurn`, and pending
+   * tools from the inbound message list when resumed). Not a recount of full
+   * message history; not model turns.
+   */
+  toolCallCount: number
+  /**
+   * Tool calls in the most recent budgeted batch — a live model turn or a
+   * pending/resume batch (0 when the last phase produced no tool calls).
+   */
+  lastTurnToolCallCount: number
 }
 
 /**
@@ -838,8 +859,10 @@ export interface AgentLoopState {
  *
  * @example
  * ```typescript
- * // Continue for up to 5 iterations
+ * // Continue for up to 5 iterations (model turns, not tool calls)
  * const strategy: AgentLoopStrategy = ({ iterationCount }) => iterationCount < 5;
+ * // Cap total tool calls across the run
+ * const byTools: AgentLoopStrategy = ({ toolCallCount }) => toolCallCount < 20;
  * ```
  */
 export type AgentLoopStrategy = (state: AgentLoopState) => boolean
@@ -876,6 +899,24 @@ export interface TextOptions<
    */
   systemPrompts?: Array<SystemPrompt>
   agentLoopStrategy?: AgentLoopStrategy
+  /**
+   * Maximum number of tool calls to **execute** from a single model turn (or
+   * pending/resume batch). `0` skips all execution for that batch.
+   *
+   * Models can emit many parallel tool calls in one turn. `agentLoopStrategy`
+   * (including `maxIterations` / `maxToolCalls`) is only evaluated between
+   * turns, so without this cap a single runaway turn can still execute an
+   * unbounded fan-out.
+   *
+   * When set, only the first `maxToolCallsPerTurn` calls are executed; the
+   * remainder receive error tool results so the message history stays
+   * consistent. Unset means no per-turn execution cap. Must be a non-negative
+   * finite number when set.
+   *
+   * Pair with the `maxToolCalls(n)` strategy for a cumulative **emitted**-call
+   * budget across the run (skipped calls still count toward that budget).
+   */
+  maxToolCallsPerTurn?: number
   /**
    * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
    * Tunes how much of each lazy tool's description appears in the discovery