@tanstack/ai 0.4.2 → 0.5.1

package/dist/esm/extend-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend-adapter.js","sources":["../../src/extend-adapter.ts"],"sourcesContent":["import type { Modality } from './types'\n\n// ===========================\n// Extended Model Definition\n// ===========================\n\n/**\n * Definition for a custom model to add to an adapter.\n *\n * @template TName - The model name as a literal string type\n * @template TInput - Array of supported input modalities\n * @template TOptions - Provider options type for this model\n *\n * @example\n * ```typescript\n * const customModels = [\n *   createModel('my-custom-model', ['text', 'image']),\n * ] as const\n * ```\n */\nexport interface ExtendedModelDef<\n  TName extends string = string,\n  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,\n  TOptions = unknown,\n> {\n  /** The model name identifier */\n  name: TName\n  /** Supported input modalities for this model */\n  input: TInput\n  /** Type brand for provider options - use `{} as YourOptionsType` */\n  modelOptions: TOptions\n}\n\n/**\n * Creates a custom model definition for use with `extendAdapter`.\n *\n * This is a helper function that provides proper type inference without\n * requiring manual `as const` casts on individual properties.\n *\n * @template TName - The model name (inferred from argument)\n * @template TInput - The input modalities array (inferred from argument)\n *\n * @param name - The model name identifier (literal string)\n * @param input - Array of supported input modalities\n * @returns A properly typed model definition for use with `extendAdapter`\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models with full type inference\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * const myOpenai = extendAdapter(openaiText, customModels)\n * ```\n */\nexport function createModel<\n  const TName extends string,\n  const TInput extends ReadonlyArray<Modality>,\n>(name: TName, input: TInput): ExtendedModelDef<TName, TInput> {\n  return {\n    name,\n    input,\n    modelOptions: {} as unknown,\n  }\n}\n\n// ===========================\n// Type Extraction Utilities\n// ===========================\n\n/**\n * Extract the model name union from an array of model definitions.\n */\ntype ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =\n  TDefs[number]['name']\n\n// ===========================\n// Factory Type Inference\n// ===========================\n\n/**\n * Infer the model parameter type from an adapter factory function.\n * For generic functions like `<T extends Union>(model: T)`, this gets `T` which\n * TypeScript treats as the constraint union when used in parameter position.\n */\ntype InferFactoryModels<TFactory> = TFactory extends (\n  model: infer TModel,\n  ...args: Array<any>\n) => any\n  ? TModel extends string\n    ? TModel\n    : string\n  : string\n\n/**\n * Infer the config parameter type from an adapter factory function.\n */\ntype InferConfig<TFactory> = TFactory extends (\n  model: any,\n  config?: infer TConfig,\n) => any\n  ? TConfig\n  : undefined\n\n/**\n * Infer the adapter return type from a factory function.\n */\ntype InferAdapterReturn<TFactory> = TFactory extends (\n  ...args: Array<any>\n) => infer TReturn\n  ? TReturn\n  : never\n\n// ===========================\n// extendAdapter Function\n// ===========================\n\n/**\n * Extends an existing adapter factory with additional custom models.\n *\n * The extended adapter accepts both original models (with full original type inference)\n * and custom models (with types from your definitions).\n *\n * At runtime, this simply passes through to the original factory - no validation is performed.\n * The original factory's signature is fully preserved, including any config parameters.\n *\n * @param factory - The original adapter factory function (e.g., `openaiText`, `anthropicText`)\n * @param models - Array of custom model definitions with `name` and `input`\n * @returns A new factory function that accepts both original and custom models\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * // Create extended adapter\n * const myOpenai = extendAdapter(openaiText, customModels)\n *\n * // Use with original models - full type inference preserved\n * const gpt4 = myOpenai('gpt-4o')\n *\n * // Use with custom models\n * const custom = myOpenai('my-fine-tuned-gpt4')\n *\n * // Type error: 'invalid-model' is not a valid model\n * // myOpenai('invalid-model')\n *\n * // Works with chat()\n * chat({\n *   adapter: myOpenai('my-fine-tuned-gpt4'),\n *   messages: [...]\n * })\n * ```\n */\nexport function extendAdapter<\n  TFactory extends (...args: Array<any>) => any,\n  const TDefs extends ReadonlyArray<ExtendedModelDef>,\n>(\n  factory: TFactory,\n  _customModels: TDefs,\n): (\n  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,\n  ...args: InferConfig<TFactory> extends undefined\n    ? []\n    : [config?: InferConfig<TFactory>]\n) => InferAdapterReturn<TFactory> {\n  // At runtime, we simply pass through to the original factory.\n  // The _customModels parameter is only used for type inference.\n  // No runtime validation - users are trusted to pass valid model names.\n  return factory as any\n}\n"],"names":[],"mappings":"AA4DO,SAAS,YAGd,MAAa,OAAgD;AAC7D,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,cAAc,CAAA;AAAA,EAAC;AAEnB;AAgGO,SAAS,cAId,SACA,eAMgC;AAIhC,SAAO;AACT;"}

package/dist/esm/index.d.ts

@@ -17,3 +17,5 @@ export * from './event-client.js';
 export { convertMessagesToModelMessages, generateMessageId, uiMessageToModelMessages, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, } from './activities/chat/messages.js';
 export { StreamProcessor, createReplayStream, ImmediateStrategy, PunctuationStrategy, BatchStrategy, WordBoundaryStrategy, CompositeStrategy, PartialJSONParser, defaultJSONParser, parsePartialJSON, } from './activities/chat/stream/index.js';
 export type { ChunkStrategy, ChunkRecording, InternalToolCallState, ProcessorResult, ProcessorState, StreamProcessorEvents, StreamProcessorOptions, ToolCallState, ToolResultState, JSONParser, } from './activities/chat/stream/index.js';
+export { createModel, extendAdapter } from './extend-adapter.js';
+export type { ExtendedModelDef } from './extend-adapter.js';

package/dist/esm/index.js

@@ -12,6 +12,7 @@ import { combineStrategies, maxIterations, untilFinishReason } from "./activitie
 import { detectImageMimeType } from "./utils.js";
 import { aiEventClient } from "./event-client.js";
 import { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, uiMessageToModelMessages } from "./activities/chat/messages.js";
+import { createModel, extendAdapter } from "./extend-adapter.js";
 import { StreamProcessor, createReplayStream } from "./activities/chat/stream/processor.js";
 import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PunctuationStrategy, WordBoundaryStrategy } from "./activities/chat/stream/strategies.js";
 import { PartialJSONParser, defaultJSONParser, parsePartialJSON } from "./activities/chat/stream/json-parser.js";
@@ -31,6 +32,7 @@ export {
   convertSchemaToJsonSchema,
   createChatOptions,
   createImageOptions,
+  createModel,
   createReplayStream,
   createSpeechOptions,
   createSummarizeOptions,
@@ -38,6 +40,7 @@ export {
   createVideoOptions,
   defaultJSONParser,
   detectImageMimeType,
+  extendAdapter,
   generateImage,
   generateMessageId,
   generateSpeech,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;"}

package/dist/esm/types.d.ts

@@ -652,9 +652,9 @@ export interface TextMessageContentEvent extends BaseAGUIEvent {
     type: 'TEXT_MESSAGE_CONTENT';
     /** Message identifier */
     messageId: string;
-    /** The incremental content token (may be undefined if only content is provided) */
-    delta?: string;
-    /** Full accumulated content so far */
+    /** The incremental content token */
+    delta: string;
+    /** Full accumulated content so far (optional, for debugging) */
     content?: string;
 }
 /**
@@ -721,8 +721,8 @@ export interface StepFinishedEvent extends BaseAGUIEvent {
     /** Step identifier */
     stepId: string;
     /** Incremental thinking content */
-    delta?: string;
-    /** Full accumulated thinking content */
+    delta: string;
+    /** Full accumulated thinking content (optional, for debugging) */
     content?: string;
 }
 /**
@@ -793,7 +793,7 @@ export interface SummarizationResult {
  * Options for image generation.
  * These are the common options supported across providers.
  */
-export interface ImageGenerationOptions<TProviderOptions extends object = object> {
+export interface ImageGenerationOptions<TProviderOptions extends object = object, TSize extends string = string> {
     /** The model to use for image generation */
     model: string;
     /** Text description of the desired image(s) */
@@ -801,7 +801,7 @@ export interface ImageGenerationOptions<TProviderOptions extends object = object
     /** Number of images to generate (default: 1) */
     numberOfImages?: number;
     /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
-    size?: string;
+    size?: TSize;
     /** Model-specific options for image generation */
     modelOptions?: TProviderOptions;
 }
@@ -839,13 +839,13 @@ export interface ImageGenerationResult {
  *
  * @experimental Video generation is an experimental feature and may change.
  */
-export interface VideoGenerationOptions<TProviderOptions extends object = object> {
+export interface VideoGenerationOptions<TProviderOptions extends object = object, TSize extends string = string> {
     /** The model to use for video generation */
     model: string;
     /** Text description of the desired video */
     prompt: string;
-    /** Video size in WIDTHxHEIGHT format (e.g., "1280x720") */
-    size?: string;
+    /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
+    size?: TSize;
     /** Video duration in seconds */
     duration?: number;
     /** Model-specific options for video generation */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",

package/src/activities/chat/index.ts

@@ -555,15 +555,6 @@ class TextEngine<
       })
     }
 
-    // Don't overwrite a tool_calls finishReason with a stop finishReason
-    if (
-      this.finishedEvent?.finishReason === 'tool_calls' &&
-      chunk.finishReason === 'stop'
-    ) {
-      this.lastFinishReason = chunk.finishReason
-      return
-    }
-
     this.finishedEvent = chunk
     this.lastFinishReason = chunk.finishReason
   }
@@ -800,6 +791,18 @@ class TextEngine<
         } catch {
           output = message.content
         }
+        // Skip approval response messages (they have pendingExecution marker)
+        // These are NOT real client tool results — they are synthetic tool messages
+        // created by uiMessageToModelMessages for approved-but-not-yet-executed tools.
+        // Treating them as results would prevent the server from requesting actual
+        // client-side execution after approval (see GitHub issue #225).
+        if (
+          output &&
+          typeof output === 'object' &&
+          (output as any).pendingExecution === true
+        ) {
+          continue
+        }
         clientToolResults.set(message.toolCallId, output)
       }
     }

package/src/activities/chat/messages.ts

@@ -1,27 +1,22 @@
 import type {
-  AudioPart,
   ContentPart,
-  DocumentPart,
-  ImagePart,
   MessagePart,
   ModelMessage,
   TextPart,
   ToolCallPart,
-  ToolResultPart,
   UIMessage,
-  VideoPart,
 } from '../../types'
 // ===========================
 // Message Converters
 // ===========================
 
 /**
- * Helper to check if a part is a multimodal content part (image, audio, video, document)
+ * Check if a MessagePart is a content part (text, image, audio, video, document)
+ * that maps directly to a ModelMessage ContentPart.
  */
-function isMultimodalPart(
-  part: MessagePart,
-): part is ImagePart | AudioPart | VideoPart | DocumentPart {
+function isContentPart(part: MessagePart): part is ContentPart {
   return (
+    part.type === 'text' ||
     part.type === 'image' ||
     part.type === 'audio' ||
     part.type === 'video' ||
@@ -30,19 +25,34 @@ function isMultimodalPart(
 }
 
 /**
- * Helper to extract text content from string or ContentPart array
- * For multimodal content, this extracts only the text parts
+ * Collapse an array of ContentParts into the most compact ModelMessage content:
+ * - Empty array → null
+ * - All text parts → joined string (or null if empty)
+ * - Mixed content → ContentPart array as-is
  */
-function getTextContent(content: string | null | Array<ContentPart>): string {
-  if (content === null) {
-    return ''
-  }
-  if (typeof content === 'string') {
-    return content
+function collapseContentParts(
+  parts: Array<ContentPart>,
+): string | null | Array<ContentPart> {
+  if (parts.length === 0) return null
+
+  const allText = parts.every((p) => p.type === 'text')
+  if (allText) {
+    const joined = parts.map((p) => p.content).join('')
+    return joined || null
   }
-  // Extract text from ContentPart array
+
+  return parts
+}
+
+/**
+ * Extract text content from ModelMessage content (string, null, or ContentPart array).
+ * Used when only the text portion is needed (e.g., tool result content).
+ */
+function getTextContent(content: string | null | Array<ContentPart>): string {
+  if (content === null) return ''
+  if (typeof content === 'string') return content
   return content
-    .filter((part) => part.type === 'text')
+    .filter((part): part is TextPart => part.type === 'text')
     .map((part) => part.content)
     .join('')
 }
@@ -69,157 +79,214 @@ export function convertMessagesToModelMessages(
 /**
  * Convert a UIMessage to ModelMessage(s)
  *
- * This conversion handles the parts-based structure:
- * - Text parts → content field (string or as part of ContentPart array)
- * - Multimodal parts (image, audio, video, document) → ContentPart array
- * - ToolCall parts → toolCalls array
- * - ToolResult parts → separate role="tool" messages
+ * Walks the parts array IN ORDER to preserve the interleaving of text,
+ * tool calls, and tool results. This is critical for multi-round tool
+ * flows where the model generates text, calls a tool, gets the result,
+ * then generates more text and calls another tool.
+ *
+ * The output preserves the sequential structure:
+ *   text1 → toolCall1 → toolResult1 → text2 → toolCall2 → toolResult2
+ * becomes:
+ *   assistant: {content: "text1", toolCalls: [toolCall1]}
+ *   tool: toolResult1
+ *   assistant: {content: "text2", toolCalls: [toolCall2]}
+ *   tool: toolResult2
  *
  * @param uiMessage - The UIMessage to convert
- * @returns An array of ModelMessages (may be multiple if tool results are present)
+ * @returns An array of ModelMessages preserving part ordering
  */
 export function uiMessageToModelMessages(
   uiMessage: UIMessage,
 ): Array<ModelMessage> {
-  const messageList: Array<ModelMessage> = []
-
   // Skip system messages - they're handled via systemPrompts, not ModelMessages
   if (uiMessage.role === 'system') {
-    return messageList
+    return []
   }
 
-  // Separate parts by type
-  // Note: thinking parts are UI-only and not included in ModelMessages
-  const textParts: Array<TextPart> = []
-  const multimodalParts: Array<
-    ImagePart | AudioPart | VideoPart | DocumentPart
-  > = []
-  const toolCallParts: Array<ToolCallPart> = []
-  const toolResultParts: Array<ToolResultPart> = []
+  // For non-assistant messages (user), use the simpler path since they
+  // don't have tool calls or tool results to interleave
+  if (uiMessage.role !== 'assistant') {
+    return [buildUserOrToolMessage(uiMessage)]
+  }
 
+  // For assistant messages, walk parts in order to preserve interleaving
+  return buildAssistantMessages(uiMessage)
+}
+
+/**
+ * Build a single ModelMessage for user messages (simple path).
+ * Preserves ordering of text and multimodal content parts.
+ */
+function buildUserOrToolMessage(uiMessage: UIMessage): ModelMessage {
+  const contentParts: Array<ContentPart> = []
   for (const part of uiMessage.parts) {
-    if (part.type === 'text') {
-      textParts.push(part)
-    } else if (isMultimodalPart(part)) {
-      multimodalParts.push(part)
-    } else if (part.type === 'tool-call') {
-      toolCallParts.push(part)
-    } else if (part.type === 'tool-result') {
-      toolResultParts.push(part)
+    if (isContentPart(part)) {
+      contentParts.push(part)
     }
-    // thinking parts are skipped - they're UI-only
   }
 
-  // Build the content field
-  // If we have multimodal parts, use ContentPart array format
-  // Otherwise, use simple string format for backward compatibility
-  let content: string | null | Array<ContentPart>
-  if (multimodalParts.length > 0) {
-    // Build ContentPart array preserving the order of text and multimodal parts
-    const contentParts: Array<ContentPart> = []
-    for (const part of uiMessage.parts) {
-      if (part.type === 'text') {
-        contentParts.push(part)
-      } else if (isMultimodalPart(part)) {
-        contentParts.push(part)
-      }
+  return {
+    role: uiMessage.role as 'user' | 'assistant' | 'tool',
+    content: collapseContentParts(contentParts),
+  }
+}
+
+// Accumulator for building an assistant segment (content + tool calls)
+interface AssistantSegment {
+  contentParts: Array<ContentPart>
+  toolCalls: Array<{
+    id: string
+    type: 'function'
+    function: { name: string; arguments: string }
+  }>
+}
+
+function createSegment(): AssistantSegment {
+  return { contentParts: [], toolCalls: [] }
+}
+
+function isToolCallIncluded(part: ToolCallPart): boolean {
+  return (
+    part.state === 'input-complete' ||
+    part.state === 'approval-responded' ||
+    part.output !== undefined
+  )
+}
+
+/**
+ * Build ModelMessages for an assistant UIMessage, preserving the
+ * sequential interleaving of text, tool calls, and tool results.
+ *
+ * Walks parts in order. Text and tool-call parts accumulate into the
+ * current "segment". When a tool-result part is encountered, the
+ * current segment is flushed as an assistant message, then the tool
+ * result is emitted as a tool message.
+ */
+function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
+  const messageList: Array<ModelMessage> = []
+  let current = createSegment()
+
+  // Track emitted tool result IDs to avoid duplicates.
+  // A tool call can have BOTH an explicit tool-result part AND an output
+  // field on the tool-call part. We only want one per tool call ID.
+  const emittedToolResultIds = new Set<string>()
+
+  function flushSegment(): void {
+    const content = collapseContentParts(current.contentParts)
+    const hasContent = content !== null
+    const hasToolCalls = current.toolCalls.length > 0
+
+    if (hasContent || hasToolCalls) {
+      messageList.push({
+        role: 'assistant',
+        content,
+        ...(hasToolCalls && { toolCalls: current.toolCalls }),
+      })
     }
-    content = contentParts
-  } else {
-    // Simple string content for text-only messages
-    content = textParts.map((p) => p.content).join('') || null
+    current = createSegment()
   }
 
-  const toolCalls =
-    toolCallParts.length > 0
-      ? toolCallParts
-          .filter(
-            (p) =>
-              p.state === 'input-complete' ||
-              p.state === 'approval-responded' ||
-              p.output !== undefined, // Include if has output (client tool result)
-          )
-          .map((p) => ({
-            id: p.id,
+  for (const part of uiMessage.parts) {
+    switch (part.type) {
+      case 'text':
+      case 'image':
+      case 'audio':
+      case 'video':
+      case 'document':
+        current.contentParts.push(part)
+        break
+
+      case 'tool-call':
+        if (isToolCallIncluded(part)) {
+          current.toolCalls.push({
+            id: part.id,
             type: 'function' as const,
             function: {
-              name: p.name,
-              arguments: p.arguments,
+              name: part.name,
+              arguments: part.arguments,
             },
-          }))
-      : undefined
+          })
+        }
+        break
 
-  // Create the main message
-  // For multimodal content, we always create a message even if content is an empty array
-  const hasContent = Array.isArray(content) ? true : content !== null
-  if (uiMessage.role !== 'assistant' || hasContent || !toolCalls) {
-    messageList.push({
-      role: uiMessage.role,
-      content,
-      ...(toolCalls && toolCalls.length > 0 && { toolCalls }),
-    })
-  } else if (toolCalls.length > 0) {
-    // Assistant message with only tool calls
-    messageList.push({
-      role: 'assistant',
-      content,
-      toolCalls,
-    })
-  }
+      case 'tool-result':
+        // Flush the current assistant segment before emitting the tool result
+        flushSegment()
 
-  // Add tool result messages for completed tool calls
-  // This includes:
-  // 1. Explicit tool-result parts (from server tools)
-  // 2. Client tool calls with output set
-  // 3. Approval-responded tool calls (approval result)
-  for (const toolResultPart of toolResultParts) {
-    if (
-      toolResultPart.state === 'complete' ||
-      toolResultPart.state === 'error'
-    ) {
-      messageList.push({
-        role: 'tool',
-        content: toolResultPart.content,
-        toolCallId: toolResultPart.toolCallId,
-      })
+        // Emit the tool result
+        if (
+          (part.state === 'complete' || part.state === 'error') &&
+          !emittedToolResultIds.has(part.toolCallId)
+        ) {
+          messageList.push({
+            role: 'tool',
+            content: part.content,
+            toolCallId: part.toolCallId,
+          })
+          emittedToolResultIds.add(part.toolCallId)
+        }
+        break
+
+      // thinking parts are skipped - they're UI-only
+      default:
+        break
     }
   }
 
-  // Add tool result messages for client tool results (tools with output)
-  // and approval responses (so iteration tracking works correctly)
-  for (const toolCallPart of toolCallParts) {
-    // Client tool with output - add as tool result
-    if (toolCallPart.output !== undefined && !toolCallPart.approval) {
+  // Flush any remaining accumulated content
+  flushSegment()
+
+  // Emit tool results from client tool-call parts with output or approval,
+  // but only if not already covered by an explicit tool-result part above.
+  // These are appended at the end since they don't have explicit tool-result
+  // parts in the parts array to trigger inline emission.
+  for (const part of uiMessage.parts) {
+    if (part.type !== 'tool-call') continue
+
+    // Client tool with output - add as tool result (if not already emitted)
+    if (
+      part.output !== undefined &&
+      !part.approval &&
+      !emittedToolResultIds.has(part.id)
+    ) {
       messageList.push({
         role: 'tool',
-        content: JSON.stringify(toolCallPart.output),
-        toolCallId: toolCallPart.id,
+        content: JSON.stringify(part.output),
+        toolCallId: part.id,
       })
+      emittedToolResultIds.add(part.id)
     }
 
     // Approval response - add as tool result for iteration tracking
-    // For APPROVED: includes pendingExecution marker so the tool still executes
-    // For DENIED: just marks the tool as complete (no execution needed)
     if (
-      toolCallPart.state === 'approval-responded' &&
-      toolCallPart.approval?.approved !== undefined
+      part.state === 'approval-responded' &&
+      part.approval?.approved !== undefined &&
+      !emittedToolResultIds.has(part.id)
     ) {
-      const approved = toolCallPart.approval.approved
+      const approved = part.approval.approved
       messageList.push({
         role: 'tool',
         content: JSON.stringify({
           approved,
-          // Mark approved tools as pending execution - they still need to run
           ...(approved && { pendingExecution: true }),
           message: approved
             ? 'User approved this action'
             : 'User denied this action',
         }),
-        toolCallId: toolCallPart.id,
+        toolCallId: part.id,
       })
+      emittedToolResultIds.add(part.id)
     }
   }
 
+  // If no messages were produced (e.g., empty parts), emit a minimal assistant message
+  if (messageList.length === 0) {
+    messageList.push({
+      role: 'assistant',
+      content: null,
+    })
+  }
+
   return messageList
 }
 
@@ -241,13 +308,29 @@ export function modelMessageToUIMessage(
 ): UIMessage {
   const parts: Array<MessagePart> = []
 
-  // Handle content (convert multimodal content to text for UI)
-  const textContent = getTextContent(modelMessage.content)
-  if (textContent) {
+  // 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) {
     parts.push({
-      type: 'text',
-      content: textContent,
+      type: 'tool-result',
+      toolCallId: modelMessage.toolCallId,
+      content: getTextContent(modelMessage.content),
+      state: 'complete',
     })
+  } else if (Array.isArray(modelMessage.content)) {
+    // Multimodal content - preserve all content parts as MessageParts
+    for (const part of modelMessage.content) {
+      parts.push(part)
+    }
+  } else {
+    // String or null content
+    const textContent = getTextContent(modelMessage.content)
+    if (textContent) {
+      parts.push({
+        type: 'text',
+        content: textContent,
+      })
+    }
   }
 
   // Handle tool calls
@@ -263,16 +346,6 @@ export function modelMessageToUIMessage(
     }
   }
 
-  // Handle tool results (when role is "tool")
-  if (modelMessage.role === 'tool' && modelMessage.toolCallId) {
-    parts.push({
-      type: 'tool-result',
-      toolCallId: modelMessage.toolCallId,
-      content: getTextContent(modelMessage.content),
-      state: 'complete',
-    })
-  }
-
   return {
     id: id || generateMessageId(),
     role: modelMessage.role === 'tool' ? 'assistant' : modelMessage.role,