feat(ai): typed metadata on tool calls + thread through pipeline

Renames `providerMetadata` to `metadata` and types it per-adapter via a
new `TToolCallMetadata` generic on `BaseTextAdapter`, mirroring the
existing typed-metadata pattern on content parts (`ImagePart<TMetadata>`,
etc.).

Also threads metadata through the client-side UIMessage pipeline so it
round-trips with each tool call, fixing the silent drop surfaced in
#403/#404 (incorporates that PR's plumbing under the new name).

Gemini adapter now declares `TToolCallMetadata = GeminiToolCallMetadata`,
giving consumers typed `toolCall.metadata?.thoughtSignature` end-to-end.

Per maintainer feedback on #459 (AlemTuzlak): use `metadata` (typed
per-adapter generic) rather than the previous `providerMetadata` bag.
The `ToolCallStartEvent` event remains non-generic with
`metadata?: Record<string, unknown>` because making it generic breaks
the AGUIEvent discriminated-union narrowing.

Breaking: consumers reading `toolCall.providerMetadata` or
`toolCallStartEvent.providerMetadata` should rename to `metadata`.

Co-authored-by: houmark <noreply@github.com>

Author: pemontto

.changeset/fix-gemini-thought-signature-part-level.md

@@ -1,12 +1,26 @@
 ---
 '@tanstack/ai-gemini': patch
+'@tanstack/ai': minor
+'@tanstack/ai-event-client': minor
 ---
 
-fix(ai-gemini): read/write thoughtSignature at Part level
+fix(ai-gemini): read/write thoughtSignature at Part level + thread typed metadata through tool-call lifecycle
 
-Gemini emits `thoughtSignature` as a Part-level sibling of `functionCall` (per the `@google/genai` `Part` type definition), not nested inside `functionCall`. The `FunctionCall` type has never had a `thoughtSignature` property. The adapter was reading from `functionCall.thoughtSignature` (which doesn't exist in the SDK types) and writing it back nested inside `functionCall`, causing Gemini 3.x to reject subsequent tool-call turns with `400 INVALID_ARGUMENT: "Function call is missing a thought_signature"`.
+Two fixes shipped together because the adapter fix is only effective once the framework also preserves provider metadata across the tool-call round-trip.
 
-This fix:
+**Adapter (Gemini):** Gemini emits `thoughtSignature` as a Part-level sibling of `functionCall` (per the `@google/genai` `Part` type definition), not nested inside `functionCall`. The `FunctionCall` type has never had a `thoughtSignature` property. The adapter was reading from `functionCall.thoughtSignature` (does not exist in SDK types) and writing it back nested inside `functionCall`, causing Gemini 3.x to reject subsequent tool-call turns with `400 INVALID_ARGUMENT: "Function call is missing a thought_signature"`.
 
-- **Read side:** reads `part.thoughtSignature` directly, using the SDK's typed `Part` interface
-- **Write side:** emits `thoughtSignature` as a Part-level sibling of `functionCall`, using the SDK's typed `Part` interface
+- **Read side:** reads `part.thoughtSignature` directly using the SDK's typed `Part` interface
+- **Write side:** emits `thoughtSignature` as a Part-level sibling of `functionCall`
+
+**Framework (typed tool-call metadata):**
+
+- `ToolCall.providerMetadata: Record<string, unknown>` is now `ToolCall<TMetadata>.metadata?: TMetadata`, mirroring the existing typed-metadata pattern on content parts (`ImagePart<TMetadata>`, `AudioPart<TMetadata>`, etc.).
+- `ToolCallPart` gains a typed `metadata?: TMetadata` field (also generic).
+- `ToolCallStartEvent.providerMetadata` becomes `metadata` (kept as `Record<string, unknown>` because the AGUIEvent discriminated union does not survive a generic on the event type; adapters cast to their typed shape when emitting).
+- `BaseTextAdapter` and `TextAdapter` gain a sixth generic `TToolCallMetadata` (default `unknown`), exposed via `~types.toolCallMetadata` for inference at call sites.
+- `InternalToolCallState` gains a `metadata?: Record<string, unknown>` field captured at `TOOL_CALL_START` and threaded through `updateToolCallPart`, `buildAssistantMessages`, `modelMessageToUIMessage`, and `completeToolCall`, fixing a previously-silent drop of provider metadata across the client-side UIMessage pipeline (closes the gap surfaced in #403/#404).
+
+**Gemini concrete impl:** new `GeminiToolCallMetadata { thoughtSignature?: string }` exported from `@tanstack/ai-gemini`. The adapter declares its `TToolCallMetadata` as this type, so consumers see `toolCall.metadata?.thoughtSignature` typed end-to-end.
+
+**Breaking:** consumers reading `toolCall.providerMetadata` or `toolCallStartEvent.providerMetadata` should rename to `metadata`.

packages/typescript/ai-event-client/src/index.ts

@@ -86,15 +86,17 @@ export type MessagePart =
   | ToolResultPart
   | ThinkingPart
 
-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` (e.g. Gemini's
+   * `{ thoughtSignature?: string }`). */
+  metadata?: TMetadata
 }
 
 /**

packages/typescript/ai-gemini/src/adapters/text.ts

@@ -33,7 +33,10 @@ import type {
   TextOptions,
 } from '@tanstack/ai'
 import type { ExternalTextProviderOptions } from '../text/text-provider-options'
-import type { GeminiMessageMetadataByModality } from '../message-types'
+import type {
+  GeminiMessageMetadataByModality,
+  GeminiToolCallMetadata,
+} from '../message-types'
 import type { GeminiClientConfig } from '../utils'
 
 /** Cast an event object to StreamChunk. Adapters construct events with string
@@ -104,7 +107,8 @@ export class GeminiTextAdapter<
   TProviderOptions,
   TInputModalities,
   GeminiMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  GeminiToolCallMetadata
 > {
   readonly kind = 'text' as const
   readonly name = 'gemini' as const
@@ -435,9 +439,9 @@ export class GeminiTextAdapter<
                 timestamp,
                 index: toolCallData.index,
                 ...(toolCallData.thoughtSignature && {
-                  providerMetadata: {
+                  metadata: {
                     thoughtSignature: toolCallData.thoughtSignature,
-                  },
+                  } satisfies GeminiToolCallMetadata,
                 }),
               })
             }
@@ -714,8 +718,9 @@ export class GeminiTextAdapter<
             >
           }
 
-          const thoughtSignature = toolCall.providerMetadata
-            ?.thoughtSignature as string | undefined
+          const thoughtSignature = (
+            toolCall.metadata as GeminiToolCallMetadata | undefined
+          )?.thoughtSignature
           // Gemini requires thoughtSignature at the Part level (sibling of
           // functionCall), not nested inside functionCall. Nesting it causes
           // the API to reject the next turn with

packages/typescript/ai-gemini/src/message-types.ts

@@ -130,3 +130,17 @@ export interface GeminiMessageMetadataByModality {
   video: GeminiVideoMetadata
   document: GeminiDocumentMetadata
 }
+
+/**
+ * Provider-specific metadata that round-trips with each Gemini tool call.
+ *
+ * `thoughtSignature` is emitted by Gemini 3.x (and 2.5 thinking) models on
+ * the Part containing the `functionCall`. The same signature must be echoed
+ * back at the Part level on the next turn or the API rejects the request
+ * with `400 INVALID_ARGUMENT: "Function call is missing a thought_signature"`.
+ *
+ * @see https://ai.google.dev/gemini-api/docs/thinking
+ */
+export interface GeminiToolCallMetadata {
+  thoughtSignature?: string
+}

packages/typescript/ai/src/activities/chat/adapter.ts

@@ -54,13 +54,15 @@ 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,
   TProviderOptions extends Record<string, any>,
   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

packages/typescript/ai/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
   }>
 }
 
@@ -205,6 +209,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
               name: part.name,
               arguments: part.arguments,
             },
+            ...(part.metadata !== undefined && { metadata: part.metadata }),
           })
         }
         break
@@ -340,6 +345,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 }),
       })
     }
   }

packages/typescript/ai/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) {

packages/typescript/ai/src/activities/chat/stream/processor.ts

@@ -899,13 +899,19 @@ export class StreamProcessor {
 
       const toolName = chunk.toolCallName
 
+      // 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,
         arguments: '',
         state: initialState,
         parsedArguments: undefined,
         index: chunk.index ?? state.toolCalls.size,
+        ...(chunkMetadata !== undefined && { metadata: chunkMetadata }),
       }
 
       state.toolCalls.set(toolCallId, newToolCall)
@@ -920,6 +926,7 @@ export class StreamProcessor {
         name: toolName,
         arguments: '',
         state: initialState,
+        ...(chunkMetadata !== undefined && { metadata: chunkMetadata }),
       })
       this.emitMessagesChange()
 
@@ -1386,6 +1393,7 @@ export class StreamProcessor {
       name: toolCall.name,
       arguments: toolCall.arguments,
       state: 'input-complete',
+      ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
     })
     this.emitMessagesChange()
 

packages/typescript/ai/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>
 }
 
 /**

packages/typescript/ai/src/activities/chat/tools/tool-calls.ts

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