@tanstack/ai 0.13.0 → 0.15.0

package/src/activities/chat/index.ts

@@ -281,6 +281,10 @@ class TextEngine<
   private totalChunkCount = 0
   private currentMessageId: string | null = null
   private accumulatedContent = ''
+  private accumulatedThinking: Array<{ content: string; signature?: string }> =
+    []
+  private currentThinkingContent = ''
+  private currentThinkingSignature = ''
   private eventOptions?: Record<string, unknown>
   private eventToolNames?: Array<string>
   private finishedEvent: RunFinishedEvent | null = null
@@ -556,6 +560,9 @@ class TextEngine<
   private async beginIteration(): Promise<void> {
     this.currentMessageId = this.createId('msg')
     this.accumulatedContent = ''
+    this.accumulatedThinking = []
+    this.currentThinkingContent = ''
+    this.currentThinkingSignature = ''
     this.finishedEvent = null
 
     // Update mutable context fields
@@ -666,6 +673,9 @@ class TextEngine<
       case 'RUN_ERROR':
         this.handleRunErrorEvent(chunk)
         break
+      case 'STEP_STARTED':
+        this.handleStepStartedEvent()
+        break
       case 'STEP_FINISHED':
         this.handleStepFinishedEvent(chunk)
         break
@@ -683,7 +693,7 @@ class TextEngine<
         break
 
       default:
-        // RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_END, STEP_STARTED,
+        // RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_END,
         // STATE_SNAPSHOT, STATE_DELTA, CUSTOM
         // - no special handling needed in chat activity
         break
@@ -726,10 +736,32 @@ class TextEngine<
     this.earlyTermination = true
   }
 
+  private finalizeCurrentThinkingStep(): void {
+    if (this.currentThinkingContent) {
+      this.accumulatedThinking.push({
+        content: this.currentThinkingContent,
+        ...(this.currentThinkingSignature && {
+          signature: this.currentThinkingSignature,
+        }),
+      })
+      this.currentThinkingContent = ''
+      this.currentThinkingSignature = ''
+    }
+  }
+
+  private handleStepStartedEvent(): void {
+    this.finalizeCurrentThinkingStep()
+  }
+
   private handleStepFinishedEvent(
-    _chunk: Extract<StreamChunk, { type: 'STEP_FINISHED' }>,
+    chunk: Extract<StreamChunk, { type: 'STEP_FINISHED' }>,
   ): void {
-    // State tracking for STEP_FINISHED is handled by middleware
+    if (chunk.delta) {
+      this.currentThinkingContent += chunk.delta
+    }
+    if (chunk.signature) {
+      this.currentThinkingSignature = chunk.signature
+    }
   }
 
   private async *checkForPendingToolCalls(): AsyncGenerator<
@@ -1057,12 +1089,17 @@ class TextEngine<
   }
 
   private addAssistantToolCallMessage(toolCalls: Array<ToolCall>): void {
+    this.finalizeCurrentThinkingStep()
+
     this.messages = [
       ...this.messages,
       {
         role: 'assistant',
         content: this.accumulatedContent || null,
         toolCalls,
+        ...(this.accumulatedThinking.length > 0 && {
+          thinking: this.accumulatedThinking,
+        }),
       },
     ]
   }
@@ -1213,6 +1250,7 @@ class TextEngine<
           timestamp: Date.now(),
           model: finishEvent.model,
           toolCallId: result.toolCallId,
+          toolCallName: result.toolName,
           toolName: result.toolName,
         } as StreamChunk)
 
@@ -1248,14 +1286,39 @@ class TextEngine<
         role: 'tool',
       } as StreamChunk)
 
-      this.messages = [
-        ...this.messages,
-        {
-          role: 'tool',
-          content,
-          toolCallId: result.toolCallId,
-        },
-      ]
+      // If a placeholder tool message exists for this toolCallId (created by
+      // uiMessageToModelMessages for an approval-responded part with no
+      // output yet), replace it with the real result. Otherwise the LLM sees
+      // both messages — and since the Anthropic adapter dedupes tool_result
+      // blocks by tool_use_id keeping the first match, the placeholder wins
+      // and the real result is dropped (see issue #532).
+      const placeholderIdx = this.messages.findIndex((m) => {
+        if (m.role !== 'tool' || m.toolCallId !== result.toolCallId) {
+          return false
+        }
+        if (typeof m.content !== 'string') return false
+        try {
+          return JSON.parse(m.content)?.pendingExecution === true
+        } catch {
+          return false
+        }
+      })
+
+      const newToolMessage: ModelMessage = {
+        role: 'tool',
+        content,
+        toolCallId: result.toolCallId,
+      }
+
+      if (placeholderIdx >= 0) {
+        this.messages = [
+          ...this.messages.slice(0, placeholderIdx),
+          newToolMessage,
+          ...this.messages.slice(placeholderIdx + 1),
+        ]
+      } else {
+        this.messages = [...this.messages, newToolMessage]
+      }
     }
 
     return chunks

package/src/activities/chat/messages.ts

@@ -165,6 +165,7 @@ function isToolCallIncluded(part: ToolCallPart): boolean {
 function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
   const messageList: Array<ModelMessage> = []
   let current = createSegment()
+  let pendingThinking: Array<{ content: string; signature?: string }> = []
 
   // Track emitted tool result IDs to avoid duplicates.
   // A tool call can have BOTH an explicit tool-result part AND an output
@@ -181,7 +182,9 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         role: 'assistant',
         content,
         ...(hasToolCalls && { toolCalls: current.toolCalls }),
+        ...(pendingThinking.length > 0 && { thinking: pendingThinking }),
       })
+      pendingThinking = []
     }
     current = createSegment()
   }
@@ -227,7 +230,15 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         }
         break
 
-      // thinking parts are skipped - they're UI-only
+      case 'thinking':
+        if (part.content) {
+          pendingThinking.push({
+            content: part.content,
+            ...(part.signature && { signature: part.signature }),
+          })
+        }
+        break
+
       default:
         break
     }
@@ -306,6 +317,17 @@ export function modelMessageToUIMessage(
 ): UIMessage {
   const parts: Array<MessagePart> = []
 
+  if (modelMessage.role === 'assistant' && modelMessage.thinking?.length) {
+    for (const thinking of modelMessage.thinking) {
+      if (!thinking.content) continue
+      parts.push({
+        type: 'thinking',
+        content: thinking.content,
+        ...(thinking.signature && { signature: thinking.signature }),
+      })
+    }
+  }
+
   // Handle tool results (when role is "tool") - only produce tool-result part,
   // not a text part (the content IS the tool result, not display text)
   if (modelMessage.role === 'tool' && modelMessage.toolCallId) {

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

@@ -244,12 +244,15 @@ export function updateToolCallApprovalResponse(
 }
 
 /**
- * Update or add a thinking part to a message.
+ * Update or add a thinking part to a message, keyed by stepId.
+ * Each distinct stepId produces its own ThinkingPart.
  */
 export function updateThinkingPart(
   messages: Array<UIMessage>,
   messageId: string,
+  stepId: string,
   content: string,
+  signature?: string,
 ): Array<UIMessage> {
   return messages.map((msg) => {
     if (msg.id !== messageId) {
@@ -257,15 +260,19 @@ export function updateThinkingPart(
     }
 
     const parts = [...msg.parts]
-    const thinkingPartIndex = parts.findIndex((p) => p.type === 'thinking')
+    const thinkingPartIndex = parts.findIndex(
+      (p) => p.type === 'thinking' && p.stepId === stepId,
+    )
 
     const thinkingPart: ThinkingPart = {
       type: 'thinking',
       content,
+      stepId,
+      ...(signature && { signature }),
     }
 
     if (thinkingPartIndex >= 0) {
-      // Update existing thinking part
+      // Update existing thinking part for this step
       parts[thinkingPartIndex] = thinkingPart
     } else {
       // Add new thinking part at the end (preserve natural streaming order)

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

@@ -90,7 +90,11 @@ export interface StreamProcessorEvents {
     state: ToolCallState,
     args: string,
   ) => void
-  onThinkingUpdate?: (messageId: string, content: string) => void
+  onThinkingUpdate?: (
+    messageId: string,
+    stepId: string,
+    content: string,
+  ) => void
 }
 
 /**
@@ -139,6 +143,7 @@ export class StreamProcessor {
   private activeMessageIds: Set<string> = new Set()
   private toolCallToMessage: Map<string, string> = new Map()
   private pendingManualMessageId: string | null = null
+  private pendingThinkingStepId: string | null = null
 
   // Run tracking (for concurrent run safety)
   private activeRuns = new Set<string>()
@@ -541,8 +546,14 @@ export class StreamProcessor {
         )
         break
 
+      case 'STEP_STARTED':
+        this.handleStepStartedEvent(
+          chunk as Extract<StreamChunk, { type: 'STEP_STARTED' }>,
+        )
+        break
+
       default:
-        // STEP_STARTED, STATE_SNAPSHOT, STATE_DELTA - no special handling needed
+        // STATE_SNAPSHOT, STATE_DELTA - no special handling needed
         break
     }
   }
@@ -564,8 +575,11 @@ export class StreamProcessor {
       totalTextContent: '',
       currentSegmentText: '',
       lastEmittedText: '',
-      thinkingContent: '',
       hasSeenReasoningEvents: false,
+      thinkingSteps: new Map(),
+      thinkingStepSignatures: new Map(),
+      thinkingStepOrder: [],
+      currentThinkingStepId: null,
       toolCalls: new Map(),
       toolCallOrder: [],
       hasToolCallsSinceTextStart: false,
@@ -582,6 +596,23 @@ export class StreamProcessor {
     return this.messageStates.get(messageId)
   }
 
+  /**
+   * Promote a pending stepId from a STEP_STARTED that fired before the
+   * assistant message existed onto the given message state, so the next
+   * thinking event (STEP_FINISHED or REASONING_MESSAGE_CONTENT) attributes
+   * to the correct step.
+   */
+  private consumePendingThinkingStep(state: MessageStreamState): void {
+    if (!this.pendingThinkingStepId) return
+    const stepId = this.pendingThinkingStepId
+    state.currentThinkingStepId = stepId
+    if (!state.thinkingSteps.has(stepId)) {
+      state.thinkingSteps.set(stepId, '')
+      state.thinkingStepOrder.push(stepId)
+    }
+    this.pendingThinkingStepId = null
+  }
+
   /**
    * Get the most recent active assistant message ID.
    * Used as fallback for events that don't include a messageId.
@@ -897,7 +928,13 @@ export class StreamProcessor {
       // New tool call starting
       const initialState: ToolCallState = 'awaiting-input'
 
-      const toolName = chunk.toolCallName
+      // `toolName` is a deprecated alias for `toolCallName` (see ToolCallStartEvent
+      // in types.ts). Accept either so chunks from older code paths or any
+      // adapter that only sets the deprecated field still produce a named part.
+      // The type marks both as required strings, but in practice some emitters
+      // only set one — fall back via the runtime value rather than the type.
+      const toolName =
+        (chunk as { toolCallName?: string }).toolCallName ?? chunk.toolName
 
       const newToolCall: InternalToolCallState = {
         id: chunk.toolCallId,
@@ -1155,11 +1192,45 @@ export class StreamProcessor {
     this.events.onError?.(new Error(errorMessage))
   }
 
+  /**
+   * Handle STEP_STARTED event (for thinking/reasoning content).
+   *
+   * Records the stepId so that subsequent STEP_FINISHED deltas accumulate
+   * into their own ThinkingPart. Does not create a message — the message
+   * is lazily created when the first STEP_FINISHED content arrives.
+   */
+  private handleStepStartedEvent(
+    chunk: Extract<StreamChunk, { type: 'STEP_STARTED' }>,
+  ): void {
+    const stepId = chunk.stepId ?? generateMessageId()
+    const activeId = this.getActiveAssistantMessageId()
+    if (activeId) {
+      const state = this.getMessageState(activeId)
+      if (state) {
+        state.currentThinkingStepId = stepId
+        if (!state.thinkingSteps.has(stepId)) {
+          state.thinkingSteps.set(stepId, '')
+          state.thinkingStepOrder.push(stepId)
+        }
+        // Clear any pending stepId from a prior STEP_STARTED that fired
+        // before the assistant message existed. Now that we're tracking
+        // the step directly on message state, the pending value is stale
+        // and must not leak into the next STEP_FINISHED (which would
+        // misattribute its delta to the stale step).
+        this.pendingThinkingStepId = null
+        return
+      }
+    }
+
+    // No active message yet — defer until ensureAssistantMessage in STEP_FINISHED
+    this.pendingThinkingStepId = stepId
+  }
+
   /**
    * Handle STEP_FINISHED event (for thinking/reasoning content).
    *
-   * Accumulates delta into thinkingContent and updates a single ThinkingPart
-   * in the UIMessage (replaced in-place, not appended).
+   * Accumulates delta into the current thinking step's content and updates
+   * the corresponding ThinkingPart in the UIMessage.
    *
    * @see docs/chat-architecture.md#thinkingreasoning-content — Thinking flow
    */
@@ -1175,10 +1246,38 @@ export class StreamProcessor {
     // REASONING_MESSAGE_CONTENT events for this message, skip the duplicate
     // thinking content from STEP_FINISHED to avoid doubled content.
     if (state.hasSeenReasoningEvents) {
+      if (chunk.signature) {
+        const stepId = state.currentThinkingStepId ?? chunk.stepId
+        if (!stepId) return
+        const thinking = state.thinkingSteps.get(stepId)
+        if (thinking !== undefined) {
+          state.thinkingStepSignatures.set(stepId, chunk.signature)
+          this.messages = updateThinkingPart(
+            this.messages,
+            messageId,
+            stepId,
+            thinking,
+            chunk.signature,
+          )
+          this.emitMessagesChange()
+        }
+      }
       return
     }
 
-    const previous = state.thinkingContent
+    this.consumePendingThinkingStep(state)
+
+    const stepId =
+      state.currentThinkingStepId ?? chunk.stepId ?? generateMessageId()
+
+    // Auto-initialize if no prior STEP_STARTED (backward compat)
+    if (!state.thinkingSteps.has(stepId)) {
+      state.thinkingSteps.set(stepId, '')
+      state.thinkingStepOrder.push(stepId)
+      state.currentThinkingStepId = stepId
+    }
+
+    const previous = state.thinkingSteps.get(stepId)!
     let nextThinking = previous
 
     // Prefer delta over content
@@ -1194,25 +1293,31 @@ export class StreamProcessor {
       }
     }
 
-    state.thinkingContent = nextThinking
+    state.thinkingSteps.set(stepId, nextThinking)
+
+    if (chunk.signature) {
+      state.thinkingStepSignatures.set(stepId, chunk.signature)
+    }
 
     // Update UIMessage
     this.messages = updateThinkingPart(
       this.messages,
       messageId,
-      state.thinkingContent,
+      stepId,
+      nextThinking,
+      state.thinkingStepSignatures.get(stepId),
     )
     this.emitMessagesChange()
 
     // Emit granular event
-    this.events.onThinkingUpdate?.(messageId, state.thinkingContent)
+    this.events.onThinkingUpdate?.(messageId, stepId, nextThinking)
   }
 
   /**
    * Handle REASONING_MESSAGE_CONTENT event (AG-UI reasoning protocol).
    *
-   * Accumulates reasoning delta into thinkingContent and updates the ThinkingPart
-   * in the UIMessage.
+   * Accumulates reasoning delta into thinking content and updates the
+   * corresponding ThinkingPart in the UIMessage.
    */
   private handleReasoningMessageContentEvent(
     chunk: Extract<StreamChunk, { type: 'REASONING_MESSAGE_CONTENT' }>,
@@ -1223,16 +1328,29 @@ export class StreamProcessor {
 
     state.hasSeenReasoningEvents = true
     const delta = chunk.delta || ''
-    state.thinkingContent = state.thinkingContent + delta
+
+    this.consumePendingThinkingStep(state)
+
+    const stepId = state.currentThinkingStepId ?? chunk.messageId
+    if (!state.thinkingSteps.has(stepId)) {
+      state.thinkingSteps.set(stepId, '')
+      state.thinkingStepOrder.push(stepId)
+      state.currentThinkingStepId = stepId
+    }
+
+    const nextThinking = (state.thinkingSteps.get(stepId) ?? '') + delta
+    state.thinkingSteps.set(stepId, nextThinking)
 
     this.messages = updateThinkingPart(
       this.messages,
       messageId,
-      state.thinkingContent,
+      stepId,
+      nextThinking,
+      state.thinkingStepSignatures.get(stepId),
     )
     this.emitMessagesChange()
 
-    this.events.onThinkingUpdate?.(messageId, state.thinkingContent)
+    this.events.onThinkingUpdate?.(messageId, stepId, nextThinking)
   }
 
   /**
@@ -1518,7 +1636,9 @@ export class StreamProcessor {
 
     for (const state of this.messageStates.values()) {
       content += state.totalTextContent
-      thinking += state.thinkingContent
+      for (const stepId of state.thinkingStepOrder) {
+        thinking += state.thinkingSteps.get(stepId) ?? ''
+      }
     }
 
     return {
@@ -1540,7 +1660,9 @@ export class StreamProcessor {
 
     for (const state of this.messageStates.values()) {
       content += state.totalTextContent
-      thinking += state.thinkingContent
+      for (const stepId of state.thinkingStepOrder) {
+        thinking += state.thinkingSteps.get(stepId) ?? ''
+      }
       for (const [id, tc] of state.toolCalls) {
         toolCalls.set(id, tc)
       }
@@ -1586,6 +1708,7 @@ export class StreamProcessor {
     this.activeRuns.clear()
     this.toolCallToMessage.clear()
     this.pendingManualMessageId = null
+    this.pendingThinkingStepId = null
     this.finishReason = null
     this.hasError = false
     this.isDone = false

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

@@ -56,8 +56,11 @@ export interface MessageStreamState {
   totalTextContent: string
   currentSegmentText: string
   lastEmittedText: string
-  thinkingContent: string
   hasSeenReasoningEvents: boolean
+  thinkingSteps: Map<string, string>
+  thinkingStepSignatures: Map<string, string>
+  thinkingStepOrder: Array<string>
+  currentThinkingStepId: string | null
   toolCalls: Map<string, InternalToolCallState>
   toolCallOrder: Array<string>
   hasToolCallsSinceTextStart: boolean

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

@@ -93,7 +93,9 @@ export class ToolCallManager {
    */
   addToolCallStartEvent(event: ToolCallStartEvent): void {
     const index = event.index ?? this.toolCallsMap.size
-    const name = event.toolCallName
+    const runtimeEvent = event as Partial<ToolCallStartEvent> &
+      Pick<ToolCallStartEvent, 'toolName'>
+    const name = runtimeEvent.toolCallName ?? runtimeEvent.toolName
     this.toolCallsMap.set(index, {
       id: event.toolCallId,
       type: 'function',

package/src/activities/error-payload.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared error-narrowing helper for activities that convert thrown values
+ * into structured `RUN_ERROR` events.
+ *
+ * Accepts Error instances, objects with string-ish `message`/`code`, or bare
+ * strings; always returns a shape safe to serialize. Never leaks the full
+ * error object (which may carry request/response state from an SDK).
+ */
+export function toRunErrorPayload(
+  error: unknown,
+  fallbackMessage = 'Unknown error occurred',
+): { message: string; code: string | undefined } {
+  if (error instanceof Error) {
+    const codeField = (error as Error & { code?: unknown }).code
+    return {
+      message: error.message || fallbackMessage,
+      code: typeof codeField === 'string' ? codeField : undefined,
+    }
+  }
+  if (typeof error === 'object' && error !== null) {
+    const messageField = (error as { message?: unknown }).message
+    const codeField = (error as { code?: unknown }).code
+    return {
+      message:
+        typeof messageField === 'string' && messageField.length > 0
+          ? messageField
+          : fallbackMessage,
+      code: typeof codeField === 'string' ? codeField : undefined,
+    }
+  }
+  if (typeof error === 'string' && error.length > 0) {
+    return { message: error, code: undefined }
+  }
+  return { message: fallbackMessage, code: undefined }
+}

package/src/activities/generateAudio/adapter.ts

@@ -0,0 +1,89 @@
+import type { AudioGenerationOptions, AudioGenerationResult } from '../../types'
+
+/**
+ * Configuration for audio generation adapter instances
+ */
+export interface AudioAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Audio generation adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'fal-ai/diffrhythm')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface AudioAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  /** Discriminator for adapter kind - used to determine API shape */
+  readonly kind: 'audio'
+  /** Adapter name identifier */
+  readonly name: string
+  /** The model this adapter is configured for */
+  readonly model: TModel
+
+  /**
+   * @internal Type-only properties for inference. Not assigned at runtime.
+   */
+  '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  /**
+   * Generate audio from a text prompt
+   */
+  generateAudio: (
+    options: AudioGenerationOptions<TProviderOptions>,
+  ) => Promise<AudioGenerationResult>
+}
+
+/**
+ * An AudioAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyAudioAdapter = AudioAdapter<any, any>
+
+/**
+ * Abstract base class for audio generation adapters.
+ * Extend this class to implement an audio adapter for a specific provider.
+ *
+ * Generic parameters match AudioAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseAudioAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> implements AudioAdapter<TModel, TProviderOptions> {
+  readonly kind = 'audio' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  protected config: AudioAdapterConfig
+
+  constructor(model: TModel, config: AudioAdapterConfig = {}) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract generateAudio(
+    options: AudioGenerationOptions<TProviderOptions>,
+  ): Promise<AudioGenerationResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}