@tanstack/ai 0.45.0 → 0.46.0

package/src/activities/chat/index.ts

@@ -25,6 +25,7 @@ import {
 import { normalizeToolResult } from '../../utilities/tool-result'
 import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
 import { LazyToolManager } from './tools/lazy-tool-manager'
+import { assertUniqueToolNames } from './tools/unique-tool-names'
 import {
   MiddlewareAbortError,
   ToolCallManager,
@@ -42,7 +43,11 @@ import {
 } from './tools/approval-schema'
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import { isCancelRequestedReason } from './cancel'
-import { convertMessagesToModelMessages, generateMessageId } from './messages'
+import {
+  convertMessagesToModelMessages,
+  generateMessageId,
+  modelMessageToUIMessage,
+} from './messages'
 import { MiddlewareRunner } from './middleware/compose'
 import { getRunDetached } from './middleware/run-store'
 import { publishRunDetachedSignal } from '../../delivery-detach'
@@ -738,9 +743,11 @@ class TextEngine<
     []
   private currentThinkingContent = ''
   private currentThinkingSignature = ''
+  private hasSeenReasoningEvents = false
   private eventOptions?: Record<string, unknown> | undefined
   private eventToolNames?: Array<string>
   private finishedEvent: RunFinishedEvent | null = null
+  private readonly streamedToolErrorResults = new Map<string, ToolResult>()
   private deferredToolCallRunFinishedChunks: Array<StreamChunk> = []
   private earlyTermination = false
   private toolPhase: ToolPhaseResult = 'continue'
@@ -840,6 +847,7 @@ class TextEngine<
     this.messages = convertMessagesToModelMessages(config.params.messages)
 
     // Initialize lazy tool manager after messages are converted (needs message history for scanning)
+    assertUniqueToolNames(config.params.tools || [])
     this.lazyToolManager = new LazyToolManager(
       config.params.tools || [],
       this.messages,
@@ -1151,6 +1159,7 @@ class TextEngine<
             duration: Date.now() - this.streamStartTime,
           })
         } else {
+          this.addTerminalReasoningMessage()
           this.terminalHookCalled = true
           await this.middlewareRunner.runOnFinish(this.middlewareCtx, {
             finishReason: this.lastFinishReason,
@@ -1281,7 +1290,9 @@ class TextEngine<
     this.accumulatedThinking = []
     this.currentThinkingContent = ''
     this.currentThinkingSignature = ''
+    this.hasSeenReasoningEvents = false
     this.finishedEvent = null
+    this.streamedToolErrorResults.clear()
 
     // Update mutable context fields
     this.middlewareCtx.currentMessageId = this.currentMessageId
@@ -1531,16 +1542,19 @@ class TextEngine<
         this.handleStepFinishedEvent(chunk)
         break
 
+      case 'REASONING_MESSAGE_CONTENT':
+        this.handleReasoningMessageContentEvent(chunk)
+        break
+
       case 'TOOL_CALL_RESULT':
         // Tool result is already added to messages in buildToolResultChunks
         break
 
       case 'REASONING_START':
       case 'REASONING_MESSAGE_START':
-      case 'REASONING_MESSAGE_CONTENT':
       case 'REASONING_MESSAGE_END':
       case 'REASONING_END':
-        // Reasoning events are handled by StreamProcessor
+        // No special handling needed
         break
 
       default:
@@ -1588,6 +1602,20 @@ class TextEngine<
 
   private handleToolCallEndEvent(chunk: ToolCallEndEvent): void {
     this.toolCallManager.completeToolCall(chunk)
+    if (chunk.state !== 'output-error' || chunk.result === undefined) return
+
+    const toolCall = this.toolCallManager
+      .getToolCalls()
+      .find((candidate) => candidate.id === chunk.toolCallId)
+    if (!toolCall) return
+
+    this.streamedToolErrorResults.set(chunk.toolCallId, {
+      toolCallId: chunk.toolCallId,
+      toolName: toolCall.function.name,
+      result: chunk.result,
+      ...(chunk.input !== undefined && { input: chunk.input }),
+      state: 'output-error',
+    })
   }
 
   private handleRunFinishedEvent(chunk: RunFinishedEvent): void {
@@ -1635,14 +1663,29 @@ class TextEngine<
   private handleStepFinishedEvent(
     chunk: Extract<StreamChunk, { type: 'STEP_FINISHED' }>,
   ): void {
-    if (chunk.delta) {
-      this.currentThinkingContent += chunk.delta
+    if (!this.hasSeenReasoningEvents) {
+      if (chunk.delta) {
+        this.currentThinkingContent += chunk.delta
+      } else if (chunk.content) {
+        if (chunk.content.startsWith(this.currentThinkingContent)) {
+          this.currentThinkingContent = chunk.content
+        } else if (!this.currentThinkingContent.startsWith(chunk.content)) {
+          this.currentThinkingContent += chunk.content
+        }
+      }
     }
     if (chunk.signature) {
       this.currentThinkingSignature = chunk.signature
     }
   }
 
+  private handleReasoningMessageContentEvent(
+    chunk: Extract<StreamChunk, { type: 'REASONING_MESSAGE_CONTENT' }>,
+  ): void {
+    this.hasSeenReasoningEvents = true
+    this.currentThinkingContent += chunk.delta
+  }
+
   /**
    * Tools available for execution this turn. The discovery tool is dropped
    * from the advertised set (`this.tools`) once every lazy tool is discovered,
@@ -1843,6 +1886,9 @@ class TextEngine<
     // Handle undiscovered lazy tool calls with self-correcting error messages
     const undiscoveredLazyResults: Array<ToolResult> = []
     const executableToolCalls = toolCalls.filter((tc) => {
+      if (this.streamedToolErrorResults.has(tc.id)) {
+        return false
+      }
       if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
         undiscoveredLazyResults.push({
           toolCallId: tc.id,
@@ -1859,14 +1905,17 @@ class TextEngine<
       return true
     })
 
-    // Non-executed outcomes (undiscovered lazy). Per-turn skips come from
-    // middleware and appear in execution results.
-    const deferredErrorResults = [...undiscoveredLazyResults]
+    // Non-executed outcomes. Per-turn skips come from middleware and appear in
+    // execution results.
+    const deferredErrorResults = [
+      ...this.streamedToolErrorResults.values(),
+      ...undiscoveredLazyResults,
+    ]
 
     if (executableToolCalls.length === 0) {
       yield* this.flushDeferredToolCallRunFinishedChunks()
-      // All tool calls were undiscovered lazy tools — errors emitted, continue
-      // loop (strategy / onShouldContinue may stop).
+      // All tool calls already have error results — emit them, then continue
+      // the loop (strategy / onShouldContinue may stop).
       if (deferredErrorResults.length > 0) {
         for (const chunk of this.buildToolResultChunks(
           deferredErrorResults,
@@ -2043,6 +2092,30 @@ class TextEngine<
     this.middlewareCtx.messages = this.messages
   }
 
+  private addTerminalReasoningMessage(): void {
+    this.finalizeCurrentThinkingStep()
+    if (this.accumulatedThinking.length === 0) return
+
+    const messages = this.middlewareCtx.messages
+    const alreadyPresent = messages.some(
+      (message) =>
+        message.role === 'assistant' && message.id === this.currentMessageId,
+    )
+    if (alreadyPresent) return
+
+    this.messages = [
+      ...messages,
+      {
+        role: 'assistant',
+        content: this.accumulatedContent || null,
+        id: this.currentMessageId ?? undefined,
+        createdAt: this.currentMessageCreatedAt ?? undefined,
+        thinking: this.accumulatedThinking,
+      },
+    ]
+    this.middlewareCtx.messages = this.messages
+  }
+
   /**
    * Extract client state (approvals and client tool results) from original messages.
    * This is called in the constructor BEFORE converting to ModelMessage format,
@@ -2232,12 +2305,18 @@ class TextEngine<
             : message.content === null
               ? undefined
               : JSON.stringify(message.content)
+        const id =
+          message.id ||
+          `snapshot_${this.runIdOverride ?? this.requestId}_${index}`
+        const parts =
+          message.role === 'assistant' && message.thinking?.length
+            ? modelMessageToUIMessage(message, id).parts
+            : undefined
         return {
-          id:
-            message.id ||
-            `snapshot_${this.runIdOverride ?? this.requestId}_${index}`,
+          id,
           role: message.role,
           ...(content !== undefined ? { content } : {}),
+          ...(parts ? { parts } : {}),
           ...('toolCalls' in message && message.toolCalls
             ? { toolCalls: message.toolCalls }
             : {}),
@@ -3551,6 +3630,7 @@ class TextEngine<
     this.applyResumeToolState(config.resumeToolState)
     this.messages = config.messages
     this.systemPrompts = config.systemPrompts
+    assertUniqueToolNames(config.tools)
     this.tools = config.tools
     this.params = {
       ...this.params,
@@ -3743,6 +3823,9 @@ export function chat<
   >,
 ): TextActivityResult<TSchema, TStream, TTools> {
   validateCapabilities(options.middleware ?? [], options.adapter)
+  if (options.tools) {
+    assertUniqueToolNames(options.tools)
+  }
 
   const { outputSchema, stream } = options
 

package/src/activities/chat/tools/unique-tool-names.ts

@@ -0,0 +1,73 @@
+import type { Tool } from '../../../types'
+
+/**
+ * Thrown when `chat({ tools })` (or a provider converter) receives two tools
+ * with the same public `name`.
+ *
+ * The common case is a provider-native factory (`webSearchTool()`) next to an
+ * ordinary function that reused the reserved name (`web_search`). Providers
+ * reject that pair, so we fail before the request is built.
+ */
+export class DuplicateToolNameError extends Error {
+  readonly toolName: string
+
+  constructor(toolName: string, message: string) {
+    super(message)
+    this.name = 'DuplicateToolNameError'
+    this.toolName = toolName
+  }
+}
+
+function isProviderNativeTool(tool: Tool): boolean {
+  const kind = tool.metadata?.['__kind']
+  return typeof kind === 'string' && kind.length > 0
+}
+
+function nativeAndCustomMessage(toolName: string) {
+  return [
+    `Cannot pass two tools named "${toolName}" in the same chat() call.`,
+    `One is the provider-native tool from a factory (for example webSearchTool()).`,
+    `The other is your own function with the same public name.`,
+    `Tool names in one tools array must be unique.`,
+    `Keep the factory for hosted search, or keep your function and give it a different name.`,
+  ].join(' ')
+}
+
+function duplicateNameMessage(toolName: string) {
+  return [
+    `Cannot pass two tools named "${toolName}" in the same chat() call.`,
+    `Tool names in one tools array must be unique.`,
+  ].join(' ')
+}
+
+/**
+ * Throws {@link DuplicateToolNameError} when two tools share a public name.
+ *
+ * The native-vs-custom message fires when one of the colliding tools carries
+ * adapter `metadata.__kind` (set by a provider factory) and another does not.
+ */
+export function assertUniqueToolNames(tools: ReadonlyArray<Tool>): void {
+  const byName = new Map<string, Array<Tool>>()
+  for (const tool of tools) {
+    const group = byName.get(tool.name)
+    if (group) {
+      group.push(tool)
+    } else {
+      byName.set(tool.name, [tool])
+    }
+  }
+
+  for (const [name, group] of byName) {
+    if (group.length < 2) {
+      continue
+    }
+    const hasNative = group.some(isProviderNativeTool)
+    const hasCustom = group.some((tool) => !isProviderNativeTool(tool))
+    throw new DuplicateToolNameError(
+      name,
+      hasNative && hasCustom
+        ? nativeAndCustomMessage(name)
+        : duplicateNameMessage(name),
+    )
+  }
+}

package/src/adapter-internals.ts

@@ -25,6 +25,10 @@ export {
   PendingTurnCapability,
   providePendingTurn,
 } from './activities/chat/middleware/pending-turn'
+export {
+  assertUniqueToolNames,
+  DuplicateToolNameError,
+} from './activities/chat/tools/unique-tool-names'
 export {
   appendOutputSchemaInstruction,
   parseJsonFromAssistantText,

package/src/index.ts

@@ -103,6 +103,7 @@ export type {
 
 // MCP error classes (value exports — usable with instanceof)
 export { MCPDuplicateToolNameError } from './activities/chat/mcp/manager'
+export { DuplicateToolNameError } from './activities/chat/tools/unique-tool-names'
 
 // Schema conversion (Standard JSON Schema compliant)
 export {
@@ -138,6 +139,22 @@ export type {
   UpsertableStreamDurability,
 } from './stream-durability'
 
+// WebSocket transport utilities
+export {
+  toWebSocketStream,
+  toWebSocketResponse,
+  resumeWebSocketStream,
+  resumeWebSocketResponse,
+  encodeWsFrame,
+  decodeWsFrame,
+} from './stream-to-websocket'
+export type {
+  WebSocketLike,
+  WsRunContext,
+  WebSocketStreamInit,
+  InboundFrame,
+} from './stream-to-websocket'
+
 // Tool call management
 export { ToolCallManager } from './activities/chat/tools/tool-calls'
 

package/src/middlewares/usage-attributes.ts

@@ -12,8 +12,8 @@ import type { TokenUsage } from '../types'
  * `gen_ai.usage.cost` and `gen_ai.usage.total_tokens` are de-facto extensions
  * consumed by backends like PostHog (which otherwise re-derive cost from their
  * own price tables, losing cache discounts and gateway markup). Fields with no
- * semconv or de-facto convention (`costDetails`, `durationSeconds`,
- * `unitsBilled`) are TanStack-namespaced.
+ * semconv or de-facto convention (`billed`, `costDetails`, and the deprecated
+ * `durationSeconds`/`unitsBilled`) are TanStack-namespaced.
  *
  * Shared by `otelMiddleware` across every activity (chat and the media
  * activities) so usage lands identically whichever activity produced the span.
@@ -30,6 +30,16 @@ export function usageAttributes(
     'gen_ai.usage.input_tokens': usage.promptTokens,
     'gen_ai.usage.output_tokens': usage.completionTokens,
   }
+  // The self-describing billed quantity: the unit rides along as a string
+  // attribute so backends can label/aggregate non-token usage without
+  // out-of-band knowledge of the provider.
+  if (usage.billed !== undefined) {
+    const quantity = firstNumber(usage.billed.quantity)
+    if (quantity !== undefined) {
+      attrs['tanstack.ai.usage.billed_quantity'] = quantity
+      attrs['tanstack.ai.usage.billed_unit'] = usage.billed.unit
+    }
+  }
   const optional: Array<[key: string, value: unknown]> = [
     ['gen_ai.usage.total_tokens', usage.totalTokens],
     ['gen_ai.usage.cost', usage.cost],

package/src/stream-to-response.ts

@@ -78,7 +78,7 @@ function combineFailures(
   )
 }
 
-function runErrorChunk(
+export function runErrorChunk(
   error: unknown,
 ): Extract<StreamChunk, { type: 'RUN_ERROR' }> {
   const payload = toRunErrorPayload(error)
@@ -366,7 +366,7 @@ export const RUN_ACCEPTED_EVENT = 'run.accepted'
  * The returned `getId` maps each forwarded chunk to the exact opaque offset
  * returned by the durability adapter for the SSE `id:` line.
  */
-function durableStreamSource<TOffset extends string>(
+export function durableStreamSource<TOffset extends string>(
   stream: AsyncIterable<StreamChunk>,
   durability: StreamDurability<TOffset>,
   options: {