@tanstack/ai 0.15.0 → 0.16.0

package/dist/esm/types.d.ts

@@ -70,15 +70,17 @@ export type SchemaInput = StandardJSONSchemaV1<any, any> | JSONSchema;
  * For plain JSONSchema, returns `any` since we can't infer types from JSON Schema at compile time.
  */
 export type InferSchemaType<T> = T extends StandardJSONSchemaV1<infer TInput, unknown> ? TInput : unknown;
-export interface ToolCall {
+export interface ToolCall<TMetadata = unknown> {
     id: string;
     type: 'function';
     function: {
         name: string;
         arguments: string;
     };
-    /** Provider-specific metadata to carry through the tool call lifecycle */
-    providerMetadata?: Record<string, unknown>;
+    /** Provider-specific metadata to carry through the tool call lifecycle.
+     * Typed per-adapter via `TToolCallMetadata`. For example,
+     * `@tanstack/ai-gemini` sets this to `{ thoughtSignature?: string }`. */
+    metadata?: TMetadata;
 }
 /**
  * Supported input modality types for multimodal content.
@@ -221,7 +223,7 @@ export interface TextPart<TMetadata = unknown> {
     content: string;
     metadata?: TMetadata;
 }
-export interface ToolCallPart {
+export interface ToolCallPart<TMetadata = unknown> {
     type: 'tool-call';
     id: string;
     name: string;
@@ -235,6 +237,9 @@ export interface ToolCallPart {
     };
     /** Tool execution output (for client tools or after approval) */
     output?: any;
+    /** Provider-specific metadata that round-trips with the tool call.
+     * Typed per-adapter via `TToolCallMetadata`. */
+    metadata?: TMetadata;
 }
 export interface ToolResultPart {
     type: 'tool-result';
@@ -740,7 +745,7 @@ export interface TextMessageEndEvent extends AGUITextMessageEndEvent {
  * Emitted when a tool call starts.
  *
  * @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?`
- * TanStack AI adds: `model?`, `toolName` (deprecated alias), `index?`, `providerMetadata?`
+ * TanStack AI adds: `model?`, `toolName` (deprecated alias), `index?`, `metadata?`
  */
 export interface ToolCallStartEvent extends AGUIToolCallStartEvent {
     /** Model identifier for multi-model support */
@@ -752,8 +757,11 @@ export interface ToolCallStartEvent extends AGUIToolCallStartEvent {
     toolName: string;
     /** Index for parallel tool calls */
     index?: number;
-    /** Provider-specific metadata to carry into the ToolCall */
-    providerMetadata?: Record<string, unknown>;
+    /** Provider-specific metadata to carry into the ToolCall.
+     * Untyped at the event layer because events flow through a discriminated
+     * union that does not survive generics; adapters cast it to their typed
+     * `TToolCallMetadata` shape when emitting. */
+    metadata?: Record<string, unknown>;
 }
 /**
  * Emitted when tool call arguments are streaming.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@ag-ui/core": "0.0.49",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.2.9"
+    "@tanstack/ai-event-client": "0.3.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/src/activities/chat/adapter.ts

@@ -54,6 +54,7 @@ export interface StructuredOutputResult<T = unknown> {
  * - TInputModalities: Supported input modalities for this model (already resolved)
  * - TMessageMetadata: Metadata types for content parts (already resolved)
  * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`
+ * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)
  */
 export interface TextAdapter<
   TModel extends string,
@@ -61,6 +62,7 @@ export interface TextAdapter<
   TInputModalities extends ReadonlyArray<Modality>,
   TMessageMetadataByModality extends DefaultMessageMetadataByModality,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TToolCallMetadata = unknown,
 > {
   /** Discriminator for adapter kind */
   readonly kind: 'text'
@@ -77,6 +79,7 @@ export interface TextAdapter<
     inputModalities: TInputModalities
     messageMetadataByModality: TMessageMetadataByModality
     toolCapabilities: TToolCapabilities
+    toolCallMetadata: TToolCallMetadata
   }
 
   /**
@@ -103,7 +106,7 @@ export interface TextAdapter<
  * A TextAdapter with any/unknown type parameters.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyTextAdapter = TextAdapter<any, any, any, any, any>
+export type AnyTextAdapter = TextAdapter<any, any, any, any, any, any>
 
 /**
  * Abstract base class for text adapters.
@@ -117,12 +120,14 @@ export abstract class BaseTextAdapter<
   TInputModalities extends ReadonlyArray<Modality>,
   TMessageMetadataByModality extends DefaultMessageMetadataByModality,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TToolCallMetadata = unknown,
 > implements TextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
   TMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  TToolCallMetadata
 > {
   readonly kind = 'text' as const
   abstract readonly name: string
@@ -134,6 +139,7 @@ export abstract class BaseTextAdapter<
     inputModalities: TInputModalities
     messageMetadataByModality: TMessageMetadataByModality
     toolCapabilities: TToolCapabilities
+    toolCallMetadata: TToolCallMetadata
   }
 
   protected config: TextAdapterConfig

package/src/activities/chat/messages.ts

@@ -138,6 +138,10 @@ interface AssistantSegment {
     id: string
     type: 'function'
     function: { name: string; arguments: string }
+    /** Provider-specific metadata that round-trips with the tool call.
+     * Untyped at this framework layer; adapters narrow it via their
+     * `TToolCallMetadata` generic. */
+    metadata?: unknown
   }>
 }
 
@@ -208,6 +212,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
               name: part.name,
               arguments: part.arguments,
             },
+            ...(part.metadata !== undefined && { metadata: part.metadata }),
           })
         }
         break
@@ -362,6 +367,7 @@ export function modelMessageToUIMessage(
         name: toolCall.function.name,
         arguments: toolCall.function.arguments,
         state: 'input-complete', // Model messages have complete arguments
+        ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
       })
     }
   }

package/src/activities/chat/stream/message-updaters.ts

@@ -55,6 +55,7 @@ export function updateToolCallPart(
     name: string
     arguments: string
     state: ToolCallState
+    metadata?: Record<string, unknown>
   },
 ): Array<UIMessage> {
   return messages.map((msg) => {
@@ -67,6 +68,12 @@ export function updateToolCallPart(
       (p): p is ToolCallPart => p.type === 'tool-call' && p.id === toolCall.id,
     )
 
+    // Carry forward metadata from either the new toolCall or the existing
+    // part. Once the adapter has emitted metadata for a tool call (e.g.
+    // Gemini's thoughtSignature on TOOL_CALL_START) we must not lose it on
+    // subsequent updates that don't re-supply it.
+    const metadata = toolCall.metadata ?? existing?.metadata
+
     const toolCallPart: ToolCallPart = {
       type: 'tool-call',
       id: toolCall.id,
@@ -76,6 +83,7 @@ export function updateToolCallPart(
       // Carry forward approval and output from the existing part
       ...(existing?.approval && { approval: { ...existing.approval } }),
       ...(existing?.output !== undefined && { output: existing.output }),
+      ...(metadata !== undefined && { metadata }),
     }
 
     if (existing) {

package/src/activities/chat/stream/processor.ts

@@ -936,6 +936,11 @@ export class StreamProcessor {
       const toolName =
         (chunk as { toolCallName?: string }).toolCallName ?? chunk.toolName
 
+      // Capture provider metadata that arrived on TOOL_CALL_START so it
+      // round-trips back through the assistant message on the next turn
+      // (e.g. Gemini's thoughtSignature).
+      const chunkMetadata = chunk.metadata
+
       const newToolCall: InternalToolCallState = {
         id: chunk.toolCallId,
         name: toolName,
@@ -943,6 +948,7 @@ export class StreamProcessor {
         state: initialState,
         parsedArguments: undefined,
         index: chunk.index ?? state.toolCalls.size,
+        ...(chunkMetadata !== undefined && { metadata: chunkMetadata }),
       }
 
       state.toolCalls.set(toolCallId, newToolCall)
@@ -957,6 +963,7 @@ export class StreamProcessor {
         name: toolName,
         arguments: '',
         state: initialState,
+        ...(chunkMetadata !== undefined && { metadata: chunkMetadata }),
       })
       this.emitMessagesChange()
 
@@ -1504,6 +1511,7 @@ export class StreamProcessor {
       name: toolCall.name,
       arguments: toolCall.arguments,
       state: 'input-complete',
+      ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
     })
     this.emitMessagesChange()
 
@@ -1619,6 +1627,10 @@ export class StreamProcessor {
               name: tc.name,
               arguments: tc.arguments,
             },
+            // Preserve provider metadata (e.g. Gemini thoughtSignature) on
+            // ProcessorResult.toolCalls so callers using process()/getResult()
+            // get the same round-trip support as the streaming UI path.
+            ...(tc.metadata !== undefined && { metadata: tc.metadata }),
           })
         }
       }

package/src/activities/chat/stream/types.ts

@@ -25,6 +25,11 @@ export interface InternalToolCallState {
   state: ToolCallState
   parsedArguments?: any
   index: number
+  /** Provider-specific metadata that round-trips with the tool call
+   * (e.g. Gemini's `thoughtSignature`). Untyped at this layer because
+   * the stream processor is provider-agnostic; adapters narrow it
+   * via their `TToolCallMetadata` generic. */
+  metadata?: Record<string, unknown>
 }
 
 /**

package/src/activities/chat/tools/tool-calls.ts

@@ -103,9 +103,7 @@ export class ToolCallManager {
         name,
         arguments: '',
       },
-      ...(event.providerMetadata && {
-        providerMetadata: event.providerMetadata,
-      }),
+      ...(event.metadata !== undefined && { metadata: event.metadata }),
     })
   }
 

package/src/types.ts

@@ -111,15 +111,17 @@ export type SchemaInput = StandardJSONSchemaV1<any, any> | JSONSchema
 export type InferSchemaType<T> =
   T extends StandardJSONSchemaV1<infer TInput, unknown> ? TInput : unknown
 
-export interface ToolCall {
+export interface ToolCall<TMetadata = unknown> {
   id: string
   type: 'function'
   function: {
     name: string
     arguments: string // JSON string
   }
-  /** Provider-specific metadata to carry through the tool call lifecycle */
-  providerMetadata?: Record<string, unknown>
+  /** Provider-specific metadata to carry through the tool call lifecycle.
+   * Typed per-adapter via `TToolCallMetadata`. For example,
+   * `@tanstack/ai-gemini` sets this to `{ thoughtSignature?: string }`. */
+  metadata?: TMetadata
 }
 
 // ============================================================================
@@ -309,7 +311,7 @@ export interface TextPart<TMetadata = unknown> {
   metadata?: TMetadata
 }
 
-export interface ToolCallPart {
+export interface ToolCallPart<TMetadata = unknown> {
   type: 'tool-call'
   id: string
   name: string
@@ -323,6 +325,9 @@ export interface ToolCallPart {
   }
   /** Tool execution output (for client tools or after approval) */
   output?: any
+  /** Provider-specific metadata that round-trips with the tool call.
+   * Typed per-adapter via `TToolCallMetadata`. */
+  metadata?: TMetadata
 }
 
 export interface ToolResultPart {
@@ -892,7 +897,7 @@ export interface TextMessageEndEvent extends AGUITextMessageEndEvent {
  * Emitted when a tool call starts.
  *
  * @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?`
- * TanStack AI adds: `model?`, `toolName` (deprecated alias), `index?`, `providerMetadata?`
+ * TanStack AI adds: `model?`, `toolName` (deprecated alias), `index?`, `metadata?`
  */
 export interface ToolCallStartEvent extends AGUIToolCallStartEvent {
   /** Model identifier for multi-model support */
@@ -904,8 +909,11 @@ export interface ToolCallStartEvent extends AGUIToolCallStartEvent {
   toolName: string
   /** Index for parallel tool calls */
   index?: number
-  /** Provider-specific metadata to carry into the ToolCall */
-  providerMetadata?: Record<string, unknown>
+  /** Provider-specific metadata to carry into the ToolCall.
+   * Untyped at the event layer because events flow through a discriminated
+   * union that does not survive generics; adapters cast it to their typed
+   * `TToolCallMetadata` shape when emitting. */
+  metadata?: Record<string, unknown>
 }
 
 /**