@tanstack/ai 0.10.3 → 0.11.1

package/src/activities/chat/index.ts

@@ -6,6 +6,7 @@
  */
 
 import { devtoolsMiddleware } from '@tanstack/ai-event-client'
+import { stripToSpecMiddleware } from '../../strip-to-spec-middleware'
 import { streamToText } from '../../stream-to-response.js'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import {
@@ -104,6 +105,10 @@ export interface TextActivityOptions<
   agentLoopStrategy?: TextOptions['agentLoopStrategy']
   /** Unique conversation identifier for tracking */
   conversationId?: TextOptions['conversationId']
+  /** Thread/conversation ID for AG-UI protocol. Auto-generated if not provided. */
+  threadId?: TextOptions['threadId']
+  /** Run ID override for AG-UI protocol. Auto-generated by adapter if not provided. */
+  runId?: TextOptions['runId']
   /**
    * Optional Standard Schema for structured output.
    * When provided, the activity will:
@@ -263,6 +268,10 @@ class TextEngine<
   private readonly initialApprovals: Map<string, boolean>
   private readonly initialClientToolResults: Map<string, any>
 
+  // AG-UI protocol IDs
+  private threadId: string
+  private runIdOverride?: string
+
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner
   private readonly middlewareCtx: ChatMiddlewareContext
@@ -307,9 +316,18 @@ class TextEngine<
       ? { signal: config.params.abortController.signal }
       : undefined
     this.effectiveSignal = config.params.abortController?.signal
-
-    // Initialize middleware — devtools middleware is always first
-    const allMiddleware = [devtoolsMiddleware(), ...(config.middleware || [])]
+    this.threadId = config.params.threadId || this.createId('thread')
+    this.runIdOverride = config.params.runId
+
+    // Initialize middleware — devtools first, strip-to-spec always last.
+    // handleStreamChunk processes raw chunks BEFORE middleware, so internal
+    // state management sees extended fields (finishReason, delta, toolCallName, etc.).
+    // The strip middleware ensures the yielded public stream is AG-UI spec-compliant.
+    const allMiddleware = [
+      devtoolsMiddleware(),
+      ...(config.middleware || []),
+      stripToSpecMiddleware(),
+    ]
     this.middlewareRunner = new MiddlewareRunner(allMiddleware)
     this.middlewareAbortController = new AbortController()
     this.middlewareCtx = {
@@ -535,6 +553,8 @@ class TextEngine<
       request: this.effectiveRequest,
       modelOptions,
       systemPrompts: this.systemPrompts,
+      threadId: this.threadId,
+      runId: this.runIdOverride,
     })) {
       if (this.isCancelled()) {
         break
@@ -542,14 +562,17 @@ class TextEngine<
 
       this.totalChunkCount++
 
-      // Pipe chunk through middleware (devtools middleware observes and emits events)
+      // Process the original (unstripped) chunk for internal state management
+      // BEFORE middleware, so fields like finishReason, delta, etc. are available
+      this.handleStreamChunk(chunk)
+
+      // Pipe chunk through middleware (devtools middleware observes; strip-to-spec cleans)
       const outputChunks = await this.middlewareRunner.runOnChunk(
         this.middlewareCtx,
         chunk,
       )
       for (const outputChunk of outputChunks) {
         yield outputChunk
-        this.handleStreamChunk(outputChunk)
         this.middlewareCtx.chunkIndex++
       }
 
@@ -589,6 +612,18 @@ class TextEngine<
         this.handleStepFinishedEvent(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
+        break
+
       default:
         // RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_END, STEP_STARTED,
         // STATE_SNAPSHOT, STATE_DELTA, CUSTOM
@@ -624,7 +659,7 @@ class TextEngine<
 
   private handleRunFinishedEvent(chunk: RunFinishedEvent): void {
     this.finishedEvent = chunk
-    this.lastFinishReason = chunk.finishReason
+    this.lastFinishReason = chunk.finishReason ?? null
   }
 
   private handleRunErrorEvent(
@@ -675,7 +710,7 @@ class TextEngine<
         undiscoveredLazyResults,
         finishEvent,
       )) {
-        yield chunk
+        yield* this.pipeThroughMiddleware(chunk)
       }
     }
 
@@ -748,7 +783,7 @@ class TextEngine<
           finishEvent,
           argsMap,
         )) {
-          yield chunk
+          yield* this.pipeThroughMiddleware(chunk)
         }
       }
 
@@ -756,14 +791,14 @@ class TextEngine<
         executionResult.needsApproval,
         finishEvent,
       )) {
-        yield chunk
+        yield* this.pipeThroughMiddleware(chunk)
       }
 
       for (const chunk of this.buildClientToolChunks(
         executionResult.needsClientExecution,
         finishEvent,
       )) {
-        yield chunk
+        yield* this.pipeThroughMiddleware(chunk)
       }
 
       this.setToolPhase('wait')
@@ -777,7 +812,7 @@ class TextEngine<
     )
 
     for (const chunk of toolResultChunks) {
-      yield chunk
+      yield* this.pipeThroughMiddleware(chunk)
     }
 
     return 'continue'
@@ -824,7 +859,7 @@ class TextEngine<
         undiscoveredLazyResults,
         finishEvt,
       )) {
-        yield chunk
+        yield* this.pipeThroughMiddleware(chunk)
       }
     }
 
@@ -895,7 +930,7 @@ class TextEngine<
           executionResult.results,
           finishEvent,
         )) {
-          yield chunk
+          yield* this.pipeThroughMiddleware(chunk)
         }
       }
 
@@ -903,14 +938,14 @@ class TextEngine<
         executionResult.needsApproval,
         finishEvent,
       )) {
-        yield chunk
+        yield* this.pipeThroughMiddleware(chunk)
       }
 
       for (const chunk of this.buildClientToolChunks(
         executionResult.needsClientExecution,
         finishEvent,
       )) {
-        yield chunk
+        yield* this.pipeThroughMiddleware(chunk)
       }
 
       this.setToolPhase('wait')
@@ -923,7 +958,7 @@ class TextEngine<
     )
 
     for (const chunk of toolResultChunks) {
-      yield chunk
+      yield* this.pipeThroughMiddleware(chunk)
     }
 
     // Refresh tools if lazy tools were discovered in this batch
@@ -1057,7 +1092,7 @@ class TextEngine<
             needsApproval: true,
           },
         },
-      })
+      } as StreamChunk)
     }
 
     return chunks
@@ -1080,7 +1115,7 @@ class TextEngine<
           toolName: clientTool.toolName,
           input: clientTool.input,
         },
-      })
+      } as StreamChunk)
     }
 
     return chunks
@@ -1105,7 +1140,7 @@ class TextEngine<
           model: finishEvent.model,
           toolCallId: result.toolCallId,
           toolName: result.toolName,
-        })
+        } as StreamChunk)
 
         const args = argsMap.get(result.toolCallId) ?? '{}'
         chunks.push({
@@ -1115,7 +1150,7 @@ class TextEngine<
           toolCallId: result.toolCallId,
           delta: args,
           args,
-        })
+        } as StreamChunk)
       }
 
       chunks.push({
@@ -1123,9 +1158,21 @@ class TextEngine<
         timestamp: Date.now(),
         model: finishEvent.model,
         toolCallId: result.toolCallId,
+        toolCallName: result.toolName,
         toolName: result.toolName,
         result: content,
-      })
+      } as StreamChunk)
+
+      // AG-UI spec TOOL_CALL_RESULT event
+      chunks.push({
+        type: 'TOOL_CALL_RESULT',
+        timestamp: Date.now(),
+        model: finishEvent.model,
+        messageId: this.createId('tool-result'),
+        toolCallId: result.toolCallId,
+        content,
+        role: 'tool',
+      } as StreamChunk)
 
       this.messages = [
         ...this.messages,
@@ -1186,10 +1233,11 @@ class TextEngine<
     return {
       type: 'RUN_FINISHED',
       runId: this.createId('pending'),
+      threadId: this.threadId,
       model: this.params.model,
       timestamp: Date.now(),
       finishReason: 'tool_calls',
-    }
+    } as RunFinishedEvent
   }
 
   private shouldContinue(): boolean {
@@ -1256,9 +1304,26 @@ class TextEngine<
     this.toolPhase = phase
   }
 
+  /**
+   * Pipe a single chunk through the middleware pipeline (strip-to-spec, devtools, etc.)
+   * and yield all resulting output chunks.
+   */
+  private async *pipeThroughMiddleware(
+    chunk: StreamChunk,
+  ): AsyncGenerator<StreamChunk, void, void> {
+    const outputChunks = await this.middlewareRunner.runOnChunk(
+      this.middlewareCtx,
+      chunk,
+    )
+    for (const outputChunk of outputChunks) {
+      yield outputChunk
+      this.middlewareCtx.chunkIndex++
+    }
+  }
+
   /**
    * Drain an executeToolCalls async generator, yielding any CustomEvent chunks
-   * and returning the final ExecuteToolCallsResult.
+   * through the middleware pipeline and returning the final ExecuteToolCallsResult.
    */
   private async *drainToolCallGenerator(
     generator: AsyncGenerator<
@@ -1281,7 +1346,7 @@ class TextEngine<
   > {
     let next = await generator.next()
     while (!next.done) {
-      yield next.value
+      yield* this.pipeThroughMiddleware(next.value)
       next = await generator.next()
     }
     return next.value
@@ -1297,7 +1362,7 @@ class TextEngine<
       model: this.params.model,
       name: eventName,
       value,
-    }
+    } as CustomEvent
   }
 
   private createId(prefix: string): string {

package/src/activities/chat/middleware/compose.ts

@@ -17,7 +17,7 @@ import type {
 
 /** Check if a middleware should be skipped for instrumentation events. */
 function shouldSkipInstrumentation(mw: ChatMiddleware): boolean {
-  return mw.name === 'devtools'
+  return mw.name === 'devtools' || mw.name === 'strip-to-spec'
 }
 
 /** Build the base context for middleware instrumentation events. */
@@ -132,6 +132,8 @@ export class MiddlewareRunner {
 
       const nextChunks: Array<StreamChunk> = []
       for (const c of chunks) {
+        // Cast: @ag-ui/core Zod passthrough types prevent direct `.type` access
+        const chunkType = (c as StreamChunk & { type: string }).type
         const result = await mw.onChunk(ctx, c)
         if (result === null) {
           // Drop this chunk
@@ -139,7 +141,7 @@ export class MiddlewareRunner {
             aiEventClient.emit('middleware:chunk:transformed', {
               ...instrumentCtx(ctx),
               middlewareName: mw.name || 'unnamed',
-              originalChunkType: c.type,
+              originalChunkType: chunkType,
               resultCount: 0,
               wasDropped: true,
             })
@@ -155,7 +157,7 @@ export class MiddlewareRunner {
             aiEventClient.emit('middleware:chunk:transformed', {
               ...instrumentCtx(ctx),
               middlewareName: mw.name || 'unnamed',
-              originalChunkType: c.type,
+              originalChunkType: chunkType,
               resultCount: result.length,
               wasDropped: false,
             })
@@ -167,7 +169,7 @@ export class MiddlewareRunner {
             aiEventClient.emit('middleware:chunk:transformed', {
               ...instrumentCtx(ctx),
               middlewareName: mw.name || 'unnamed',
-              originalChunkType: c.type,
+              originalChunkType: chunkType,
               resultCount: 1,
               wasDropped: false,
             })

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

@@ -431,7 +431,7 @@ export class StreamProcessor {
    *
    * Central dispatch for all AG-UI events. Each event type maps to a specific
    * handler. Events not listed in the switch are intentionally ignored
-   * (RUN_STARTED, STEP_STARTED, STATE_DELTA).
+   * (STEP_STARTED, STATE_SNAPSHOT, STATE_DELTA).
    *
    * @see docs/chat-architecture.md#adapter-contract — Expected event types and ordering
    */
@@ -445,54 +445,100 @@ export class StreamProcessor {
       })
     }
 
-    switch (chunk.type) {
+    // Cast needed: @ag-ui/core Zod passthrough types add `& { [k: string]: unknown }`
+    // which prevents TypeScript from narrowing the `type` discriminant in switch.
+    const c = chunk as StreamChunk & { type: string }
+    switch (c.type) {
       // AG-UI Events
       case 'TEXT_MESSAGE_START':
-        this.handleTextMessageStartEvent(chunk)
+        this.handleTextMessageStartEvent(
+          chunk as Extract<StreamChunk, { type: 'TEXT_MESSAGE_START' }>,
+        )
         break
 
       case 'TEXT_MESSAGE_CONTENT':
-        this.handleTextMessageContentEvent(chunk)
+        this.handleTextMessageContentEvent(
+          chunk as Extract<StreamChunk, { type: 'TEXT_MESSAGE_CONTENT' }>,
+        )
         break
 
       case 'TEXT_MESSAGE_END':
-        this.handleTextMessageEndEvent(chunk)
+        this.handleTextMessageEndEvent(
+          chunk as Extract<StreamChunk, { type: 'TEXT_MESSAGE_END' }>,
+        )
         break
 
       case 'TOOL_CALL_START':
-        this.handleToolCallStartEvent(chunk)
+        this.handleToolCallStartEvent(
+          chunk as Extract<StreamChunk, { type: 'TOOL_CALL_START' }>,
+        )
         break
 
       case 'TOOL_CALL_ARGS':
-        this.handleToolCallArgsEvent(chunk)
+        this.handleToolCallArgsEvent(
+          chunk as Extract<StreamChunk, { type: 'TOOL_CALL_ARGS' }>,
+        )
         break
 
       case 'TOOL_CALL_END':
-        this.handleToolCallEndEvent(chunk)
+        this.handleToolCallEndEvent(
+          chunk as Extract<StreamChunk, { type: 'TOOL_CALL_END' }>,
+        )
         break
 
       case 'RUN_FINISHED':
-        this.handleRunFinishedEvent(chunk)
+        this.handleRunFinishedEvent(
+          chunk as Extract<StreamChunk, { type: 'RUN_FINISHED' }>,
+        )
         break
 
       case 'RUN_ERROR':
-        this.handleRunErrorEvent(chunk)
+        this.handleRunErrorEvent(
+          chunk as Extract<StreamChunk, { type: 'RUN_ERROR' }>,
+        )
         break
 
       case 'STEP_FINISHED':
-        this.handleStepFinishedEvent(chunk)
+        this.handleStepFinishedEvent(
+          chunk as Extract<StreamChunk, { type: 'STEP_FINISHED' }>,
+        )
         break
 
       case 'MESSAGES_SNAPSHOT':
-        this.handleMessagesSnapshotEvent(chunk)
+        this.handleMessagesSnapshotEvent(
+          chunk as Extract<StreamChunk, { type: 'MESSAGES_SNAPSHOT' }>,
+        )
         break
 
       case 'CUSTOM':
-        this.handleCustomEvent(chunk)
+        this.handleCustomEvent(
+          chunk as Extract<StreamChunk, { type: 'CUSTOM' }>,
+        )
         break
 
       case 'RUN_STARTED':
-        this.handleRunStartedEvent(chunk)
+        this.handleRunStartedEvent(
+          chunk as Extract<StreamChunk, { type: 'RUN_STARTED' }>,
+        )
+        break
+
+      case 'REASONING_START':
+      case 'REASONING_MESSAGE_START':
+      case 'REASONING_MESSAGE_END':
+      case 'REASONING_END':
+        // No special handling needed
+        break
+
+      case 'REASONING_MESSAGE_CONTENT':
+        this.handleReasoningMessageContentEvent(
+          chunk as Extract<StreamChunk, { type: 'REASONING_MESSAGE_CONTENT' }>,
+        )
+        break
+
+      case 'TOOL_CALL_RESULT':
+        this.handleToolCallResultEvent(
+          chunk as Extract<StreamChunk, { type: 'TOOL_CALL_RESULT' }>,
+        )
         break
 
       default:
@@ -519,6 +565,7 @@ export class StreamProcessor {
       currentSegmentText: '',
       lastEmittedText: '',
       thinkingContent: '',
+      hasSeenReasoningEvents: false,
       toolCalls: new Map(),
       toolCallOrder: [],
       hasToolCallsSinceTextStart: false,
@@ -632,11 +679,11 @@ export class StreamProcessor {
   ): void {
     const { messageId, role } = chunk
 
-    // Map 'tool' role to 'assistant' for both UIMessage and MessageStreamState
-    // (UIMessage doesn't support 'tool' role, and lookups like
+    // Map 'tool' and 'developer' roles to 'assistant' for both UIMessage and MessageStreamState
+    // (UIMessage doesn't support 'tool'/'developer' role, and lookups like
     // getActiveAssistantMessageId() check state.role === 'assistant')
     const uiRole: 'system' | 'user' | 'assistant' =
-      role === 'tool' ? 'assistant' : role
+      role === 'user' || role === 'system' ? role : 'assistant'
 
     // Case 1: A manual message was created via startAssistantMessage()
     if (this.pendingManualMessageId) {
@@ -739,7 +786,8 @@ export class StreamProcessor {
     chunk: Extract<StreamChunk, { type: 'MESSAGES_SNAPSHOT' }>,
   ): void {
     this.resetStreamState()
-    this.messages = [...chunk.messages]
+    // AG-UI Message[] is compatible with UIMessage[] at runtime
+    this.messages = [...chunk.messages] as unknown as Array<UIMessage>
     this.emitMessagesChange()
   }
 
@@ -849,9 +897,11 @@ export class StreamProcessor {
       // New tool call starting
       const initialState: ToolCallState = 'awaiting-input'
 
+      const toolName = chunk.toolCallName
+
       const newToolCall: InternalToolCallState = {
         id: chunk.toolCallId,
-        name: chunk.toolName,
+        name: toolName,
         arguments: '',
         state: initialState,
         parsedArguments: undefined,
@@ -867,7 +917,7 @@ export class StreamProcessor {
       // Update UIMessage
       this.messages = updateToolCallPart(this.messages, messageId, {
         id: chunk.toolCallId,
-        name: chunk.toolName,
+        name: toolName,
         arguments: '',
         state: initialState,
       })
@@ -1012,6 +1062,44 @@ export class StreamProcessor {
     }
   }
 
+  /**
+   * Handle TOOL_CALL_RESULT event (AG-UI spec).
+   *
+   * Creates a tool-result part and updates the tool-call output field,
+   * mirroring the logic from TOOL_CALL_END when it carries a result.
+   * This is the spec-compliant path for delivering tool results to the client.
+   */
+  private handleToolCallResultEvent(
+    chunk: Extract<StreamChunk, { type: 'TOOL_CALL_RESULT' }>,
+  ): void {
+    const messageId = this.toolCallToMessage.get(chunk.toolCallId)
+    if (!messageId) return
+
+    // Step 1: Update the tool-call part's output field
+    let output: unknown
+    try {
+      output = JSON.parse(chunk.content)
+    } catch {
+      output = chunk.content
+    }
+    this.messages = updateToolCallWithOutput(
+      this.messages,
+      chunk.toolCallId,
+      output,
+    )
+
+    // Step 2: Create/update the tool-result part
+    const resultState: ToolResultState = 'complete'
+    this.messages = updateToolResultPart(
+      this.messages,
+      messageId,
+      chunk.toolCallId,
+      chunk.content,
+      resultState,
+    )
+    this.emitMessagesChange()
+  }
+
   /**
    * Handle RUN_STARTED event.
    *
@@ -1037,7 +1125,7 @@ export class StreamProcessor {
   private handleRunFinishedEvent(
     chunk: Extract<StreamChunk, { type: 'RUN_FINISHED' }>,
   ): void {
-    this.finishReason = chunk.finishReason
+    this.finishReason = chunk.finishReason ?? null
     this.activeRuns.delete(chunk.runId)
 
     if (this.activeRuns.size === 0) {
@@ -1054,13 +1142,17 @@ export class StreamProcessor {
     chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
   ): void {
     this.hasError = true
-    if (chunk.runId) {
-      this.activeRuns.delete(chunk.runId)
+    const runId = (chunk as any).runId as string | undefined
+    if (runId) {
+      this.activeRuns.delete(runId)
     } else {
       this.activeRuns.clear()
     }
     this.ensureAssistantMessage()
-    this.events.onError?.(new Error(chunk.error.message || 'An error occurred'))
+    // Prefer spec field `message`; fall back to deprecated `error.message`
+    const errorMessage =
+      chunk.message || chunk.error?.message || 'An error occurred'
+    this.events.onError?.(new Error(errorMessage))
   }
 
   /**
@@ -1078,6 +1170,14 @@ export class StreamProcessor {
       this.getActiveAssistantMessageId() ?? undefined,
     )
 
+    // During the transition period, adapters emit BOTH STEP_FINISHED and
+    // REASONING_MESSAGE_CONTENT with the same delta. If we've already processed
+    // REASONING_MESSAGE_CONTENT events for this message, skip the duplicate
+    // thinking content from STEP_FINISHED to avoid doubled content.
+    if (state.hasSeenReasoningEvents) {
+      return
+    }
+
     const previous = state.thinkingContent
     let nextThinking = previous
 
@@ -1108,6 +1208,33 @@ export class StreamProcessor {
     this.events.onThinkingUpdate?.(messageId, state.thinkingContent)
   }
 
+  /**
+   * Handle REASONING_MESSAGE_CONTENT event (AG-UI reasoning protocol).
+   *
+   * Accumulates reasoning delta into thinkingContent and updates the ThinkingPart
+   * in the UIMessage.
+   */
+  private handleReasoningMessageContentEvent(
+    chunk: Extract<StreamChunk, { type: 'REASONING_MESSAGE_CONTENT' }>,
+  ): void {
+    const { messageId, state } = this.ensureAssistantMessage(
+      this.getActiveAssistantMessageId() ?? undefined,
+    )
+
+    state.hasSeenReasoningEvents = true
+    const delta = chunk.delta || ''
+    state.thinkingContent = state.thinkingContent + delta
+
+    this.messages = updateThinkingPart(
+      this.messages,
+      messageId,
+      state.thinkingContent,
+    )
+    this.emitMessagesChange()
+
+    this.events.onThinkingUpdate?.(messageId, state.thinkingContent)
+  }
+
   /**
    * Handle CUSTOM event.
    *
@@ -1178,7 +1305,7 @@ export class StreamProcessor {
     if (this.events.onCustomEvent) {
       const toolCallId =
         chunk.value && typeof chunk.value === 'object'
-          ? (chunk.value as any).toolCallId
+          ? chunk.value.toolCallId
           : undefined
       this.events.onCustomEvent(chunk.name, chunk.value, { toolCallId })
     }

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

@@ -57,6 +57,7 @@ export interface MessageStreamState {
   currentSegmentText: string
   lastEmittedText: string
   thinkingContent: string
+  hasSeenReasoningEvents: boolean
   toolCalls: Map<string, InternalToolCallState>
   toolCallOrder: Array<string>
   hasToolCallsSinceTextStart: boolean

package/src/activities/chat/tools/schema-converter.ts

@@ -75,18 +75,24 @@ function makeStructuredOutputCompatible(
 
       // Recursively transform nested objects/arrays
       if (prop.type === 'object' && prop.properties) {
-        properties[propName] = makeStructuredOutputCompatible(
+        const transformed = makeStructuredOutputCompatible(
           prop,
           prop.required || [],
         )
+        properties[propName] = wasOptional
+          ? { ...transformed, type: ['object', 'null'] }
+          : transformed
       } else if (prop.type === 'array' && prop.items) {
-        properties[propName] = {
+        const transformed = {
           ...prop,
           items: makeStructuredOutputCompatible(
             prop.items,
             prop.items.required || [],
           ),
         }
+        properties[propName] = wasOptional
+          ? { ...transformed, type: ['array', 'null'] }
+          : transformed
       } else if (wasOptional) {
         // Make optional fields nullable by adding null to the type
         if (prop.type && !Array.isArray(prop.type)) {