@tanstack/ai 0.0.1

package/src/message-converters.ts

@@ -0,0 +1,285 @@
+/**
+ * Message Converters
+ *
+ * Functions for converting between UIMessage and ModelMessage formats.
+ */
+
+import type {
+  ContentPart,
+  MessagePart,
+  ModelMessage,
+  TextPart,
+  ToolCallPart,
+  ToolResultPart,
+  UIMessage,
+} from './types'
+
+/**
+ * Helper to extract text content from string or ContentPart array
+ * For multimodal content, this extracts only the text parts
+ */
+function getTextContent(content: string | null | Array<ContentPart>): string {
+  if (content === null) {
+    return ''
+  }
+  if (typeof content === 'string') {
+    return content
+  }
+  // Extract text from ContentPart array
+  return content
+    .filter((part) => part.type === 'text')
+    .map((part) => part.content)
+    .join('')
+}
+
+/**
+ * Convert UIMessages or ModelMessages to ModelMessages
+ */
+export function convertMessagesToModelMessages(
+  messages: Array<UIMessage | ModelMessage>,
+): Array<ModelMessage> {
+  const modelMessages: Array<ModelMessage> = []
+  for (const msg of messages) {
+    if ('parts' in msg) {
+      // UIMessage - convert to ModelMessages
+      modelMessages.push(...uiMessageToModelMessages(msg))
+    } else {
+      // Already ModelMessage
+      modelMessages.push(msg)
+    }
+  }
+  return modelMessages
+}
+
+/**
+ * Convert a UIMessage to ModelMessage(s)
+ *
+ * This conversion handles the parts-based structure:
+ * - Text parts → content field
+ * - ToolCall parts → toolCalls array
+ * - ToolResult parts → separate role="tool" messages
+ *
+ * @param uiMessage - The UIMessage to convert
+ * @returns An array of ModelMessages (may be multiple if tool results are present)
+ */
+export function uiMessageToModelMessages(
+  uiMessage: UIMessage,
+): Array<ModelMessage> {
+  const messages: Array<ModelMessage> = []
+
+  // Skip system messages - they're handled via systemPrompts, not ModelMessages
+  if (uiMessage.role === 'system') {
+    return messages
+  }
+
+  // Separate parts by type
+  // Note: thinking parts are UI-only and not included in ModelMessages
+  const textParts: Array<TextPart> = []
+  const toolCallParts: Array<ToolCallPart> = []
+  const toolResultParts: Array<ToolResultPart> = []
+
+  for (const part of uiMessage.parts) {
+    if (part.type === 'text') {
+      textParts.push(part)
+    } else if (part.type === 'tool-call') {
+      toolCallParts.push(part)
+    } else if (part.type === 'tool-result') {
+      toolResultParts.push(part)
+    }
+    // thinking parts are skipped - they're UI-only
+  }
+
+  // Build the main message (user or assistant)
+  const content = textParts.map((p) => p.content).join('') || null
+  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,
+            type: 'function' as const,
+            function: {
+              name: p.name,
+              arguments: p.arguments,
+            },
+          }))
+      : undefined
+
+  // Create the main message
+  if (uiMessage.role !== 'assistant' || content || !toolCalls) {
+    messages.push({
+      role: uiMessage.role,
+      content,
+      ...(toolCalls && toolCalls.length > 0 && { toolCalls }),
+    })
+  } else if (toolCalls.length > 0) {
+    // Assistant message with only tool calls
+    messages.push({
+      role: 'assistant',
+      content,
+      toolCalls,
+    })
+  }
+
+  // Add tool result messages (only completed ones)
+  for (const toolResultPart of toolResultParts) {
+    if (
+      toolResultPart.state === 'complete' ||
+      toolResultPart.state === 'error'
+    ) {
+      messages.push({
+        role: 'tool',
+        content: toolResultPart.content,
+        toolCallId: toolResultPart.toolCallId,
+      })
+    }
+  }
+
+  return messages
+}
+
+/**
+ * Convert a ModelMessage to UIMessage
+ *
+ * This conversion creates a parts-based structure:
+ * - content field → TextPart
+ * - toolCalls array → ToolCallPart[]
+ * - role="tool" messages should be converted separately and merged
+ *
+ * @param modelMessage - The ModelMessage to convert
+ * @param id - Optional ID for the UIMessage (generated if not provided)
+ * @returns A UIMessage with parts
+ */
+export function modelMessageToUIMessage(
+  modelMessage: ModelMessage,
+  id?: string,
+): UIMessage {
+  const parts: Array<MessagePart> = []
+
+  // Handle content (convert multimodal content to text for UI)
+  const textContent = getTextContent(modelMessage.content)
+  if (textContent) {
+    parts.push({
+      type: 'text',
+      content: textContent,
+    })
+  }
+
+  // Handle tool calls
+  if (modelMessage.toolCalls && modelMessage.toolCalls.length > 0) {
+    for (const toolCall of modelMessage.toolCalls) {
+      parts.push({
+        type: 'tool-call',
+        id: toolCall.id,
+        name: toolCall.function.name,
+        arguments: toolCall.function.arguments,
+        state: 'input-complete', // Model messages have complete arguments
+      })
+    }
+  }
+
+  // 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,
+    parts,
+  }
+}
+
+/**
+ * Convert an array of ModelMessages to UIMessages
+ *
+ * This handles merging tool result messages with their corresponding assistant messages
+ *
+ * @param modelMessages - Array of ModelMessages to convert
+ * @returns Array of UIMessages
+ */
+export function modelMessagesToUIMessages(
+  modelMessages: Array<ModelMessage>,
+): Array<UIMessage> {
+  const uiMessages: Array<UIMessage> = []
+  let currentAssistantMessage: UIMessage | null = null
+
+  for (const msg of modelMessages) {
+    if (msg.role === 'tool') {
+      // Tool result - merge into the last assistant message if possible
+      if (
+        currentAssistantMessage &&
+        currentAssistantMessage.role === 'assistant'
+      ) {
+        currentAssistantMessage.parts.push({
+          type: 'tool-result',
+          toolCallId: msg.toolCallId!,
+          content: getTextContent(msg.content),
+          state: 'complete',
+        })
+      } else {
+        // No assistant message to merge into, create a standalone one
+        const toolResultUIMessage = modelMessageToUIMessage(msg)
+        uiMessages.push(toolResultUIMessage)
+      }
+    } else {
+      // Regular message
+      const uiMessage = modelMessageToUIMessage(msg)
+      uiMessages.push(uiMessage)
+
+      // Track assistant messages for potential tool result merging
+      if (msg.role === 'assistant') {
+        currentAssistantMessage = uiMessage
+      } else {
+        currentAssistantMessage = null
+      }
+    }
+  }
+
+  return uiMessages
+}
+
+/**
+ * Normalize a message (UIMessage or ModelMessage) to a UIMessage
+ * Ensures the message has an ID and createdAt timestamp
+ *
+ * @param message - Either a UIMessage or ModelMessage
+ * @param generateId - Function to generate a message ID if needed
+ * @returns A UIMessage with guaranteed id and createdAt
+ */
+export function normalizeToUIMessage(
+  message: UIMessage | ModelMessage,
+  generateId: () => string,
+): UIMessage {
+  if ('parts' in message) {
+    // Already a UIMessage
+    return {
+      ...message,
+      id: message.id || generateId(),
+      createdAt: message.createdAt || new Date(),
+    }
+  } else {
+    // ModelMessage - convert to UIMessage
+    return {
+      ...modelMessageToUIMessage(message, generateId()),
+      createdAt: new Date(),
+    }
+  }
+}
+
+/**
+ * Generate a unique message ID
+ */
+export function generateMessageId(): string {
+  return `msg-${Date.now()}-${Math.random().toString(36).substring(7)}`
+}

package/src/stream/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Stream Processing Module
+ *
+ * Unified stream processing for both server and client.
+ */
+
+// Core processor
+export { StreamProcessor, createReplayStream } from './processor'
+export type {
+  StreamProcessorEvents,
+  StreamProcessorHandlers,
+  StreamProcessorOptions,
+} from './processor'
+
+// Strategies
+export {
+  ImmediateStrategy,
+  PunctuationStrategy,
+  BatchStrategy,
+  WordBoundaryStrategy,
+  CompositeStrategy,
+} from './strategies'
+
+// JSON parser
+export {
+  PartialJSONParser,
+  defaultJSONParser,
+  parsePartialJSON,
+} from './json-parser'
+export type { JSONParser } from './json-parser'
+
+// Types
+export type {
+  ChunkStrategy,
+  ChunkRecording,
+  InternalToolCallState,
+  ProcessorResult,
+  ProcessorState,
+  ToolCallState,
+  ToolResultState,
+} from './types'

package/src/stream/json-parser.ts

@@ -0,0 +1,58 @@
+/**
+ * JSON Parser for partial/incomplete JSON strings
+ *
+ * Used during streaming to parse tool call arguments that may be incomplete.
+ */
+
+import { parse as parsePartialJSONLib } from 'partial-json'
+
+/**
+ * JSON Parser interface - allows for custom parser implementations
+ */
+export interface JSONParser {
+  /**
+   * Parse a JSON string (may be incomplete/partial)
+   * @param jsonString - The JSON string to parse
+   * @returns The parsed object, or undefined if parsing fails
+   */
+  parse: (jsonString: string) => any
+}
+
+/**
+ * Partial JSON Parser implementation using the partial-json library
+ * This parser can handle incomplete JSON strings during streaming
+ */
+export class PartialJSONParser implements JSONParser {
+  /**
+   * Parse a potentially incomplete JSON string
+   * @param jsonString - The JSON string to parse (may be incomplete)
+   * @returns The parsed object, or undefined if parsing fails
+   */
+  parse(jsonString: string): any {
+    if (!jsonString || jsonString.trim() === '') {
+      return undefined
+    }
+
+    try {
+      return parsePartialJSONLib(jsonString)
+    } catch {
+      // If partial parsing fails, return undefined
+      // This is expected during early streaming when we have very little data
+      return undefined
+    }
+  }
+}
+
+/**
+ * Default parser instance
+ */
+export const defaultJSONParser = new PartialJSONParser()
+
+/**
+ * Parse partial JSON string (convenience function)
+ * @param jsonString - The JSON string to parse (may be incomplete)
+ * @returns The parsed object, or undefined if parsing fails
+ */
+export function parsePartialJSON(jsonString: string): any {
+  return defaultJSONParser.parse(jsonString)
+}

package/src/stream/message-updaters.ts

@@ -0,0 +1,275 @@
+/**
+ * Message Updaters (Internal)
+ *
+ * Internal helper functions for updating UIMessage parts.
+ * These are used by StreamProcessor to manage the message array.
+ */
+
+import type {
+  ThinkingPart,
+  ToolCallPart,
+  ToolResultPart,
+  UIMessage,
+} from '../types'
+import type { ToolCallState, ToolResultState } from './types'
+
+/**
+ * Update or add a text part to a message.
+ *
+ * If the last part is a text part, update it (continuing the same text segment).
+ * Otherwise, create a new text part (starting a new text segment after tool calls).
+ */
+export function updateTextPart(
+  messages: Array<UIMessage>,
+  messageId: string,
+  content: string,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    const lastPart = parts.length > 0 ? parts[parts.length - 1] : null
+
+    if (lastPart && lastPart.type === 'text') {
+      // Update the last text part (continuing same text segment)
+      parts[parts.length - 1] = { type: 'text', content }
+    } else {
+      // Create new text part (starting new text segment after tool calls/results)
+      parts.push({ type: 'text', content })
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Update or add a tool call part to a message.
+ */
+export function updateToolCallPart(
+  messages: Array<UIMessage>,
+  messageId: string,
+  toolCall: {
+    id: string
+    name: string
+    arguments: string
+    state: ToolCallState
+  },
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    // Find by ID, not index!
+    const existingPartIndex = parts.findIndex(
+      (p): p is ToolCallPart => p.type === 'tool-call' && p.id === toolCall.id,
+    )
+
+    const toolCallPart: ToolCallPart = {
+      type: 'tool-call',
+      id: toolCall.id,
+      name: toolCall.name,
+      arguments: toolCall.arguments,
+      state: toolCall.state,
+    }
+
+    if (existingPartIndex >= 0) {
+      // Update existing tool call
+      parts[existingPartIndex] = toolCallPart
+    } else {
+      // Add new tool call at the end (preserve natural streaming order)
+      parts.push(toolCallPart)
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Update or add a tool result part to a message.
+ */
+export function updateToolResultPart(
+  messages: Array<UIMessage>,
+  messageId: string,
+  toolCallId: string,
+  content: string,
+  state: ToolResultState,
+  error?: string,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    const resultPartIndex = parts.findIndex(
+      (p): p is ToolResultPart =>
+        p.type === 'tool-result' && p.toolCallId === toolCallId,
+    )
+
+    const toolResultPart: ToolResultPart = {
+      type: 'tool-result',
+      toolCallId,
+      content,
+      state,
+      ...(error && { error }),
+    }
+
+    if (resultPartIndex >= 0) {
+      parts[resultPartIndex] = toolResultPart
+    } else {
+      parts.push(toolResultPart)
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Update a tool call part with approval request metadata.
+ */
+export function updateToolCallApproval(
+  messages: Array<UIMessage>,
+  messageId: string,
+  toolCallId: string,
+  approvalId: string,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    const toolCallPart = parts.find(
+      (p): p is ToolCallPart => p.type === 'tool-call' && p.id === toolCallId,
+    )
+
+    if (toolCallPart) {
+      toolCallPart.state = 'approval-requested'
+      toolCallPart.approval = {
+        id: approvalId,
+        needsApproval: true,
+      }
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Update a tool call part's state (e.g., to "input-complete").
+ */
+export function updateToolCallState(
+  messages: Array<UIMessage>,
+  messageId: string,
+  toolCallId: string,
+  state: ToolCallState,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    const toolCallPart = parts.find(
+      (p): p is ToolCallPart => p.type === 'tool-call' && p.id === toolCallId,
+    )
+
+    if (toolCallPart) {
+      toolCallPart.state = state
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Update a tool call part with output.
+ * Searches all messages to find the tool call by ID.
+ */
+export function updateToolCallWithOutput(
+  messages: Array<UIMessage>,
+  toolCallId: string,
+  output: any,
+  state?: ToolCallState,
+  errorText?: string,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    const parts = [...msg.parts]
+    const toolCallPart = parts.find(
+      (p): p is ToolCallPart => p.type === 'tool-call' && p.id === toolCallId,
+    )
+
+    if (toolCallPart) {
+      toolCallPart.output = errorText ? { error: errorText } : output
+      if (state) {
+        toolCallPart.state = state
+      } else {
+        toolCallPart.state = 'input-complete'
+      }
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Update a tool call part with approval response.
+ * Searches all messages to find the tool call by approval ID.
+ */
+export function updateToolCallApprovalResponse(
+  messages: Array<UIMessage>,
+  approvalId: string,
+  approved: boolean,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    const parts = [...msg.parts]
+    const toolCallPart = parts.find(
+      (p): p is ToolCallPart =>
+        p.type === 'tool-call' && p.approval?.id === approvalId,
+    )
+
+    if (toolCallPart && toolCallPart.approval) {
+      toolCallPart.approval.approved = approved
+      toolCallPart.state = 'approval-responded'
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Update or add a thinking part to a message.
+ */
+export function updateThinkingPart(
+  messages: Array<UIMessage>,
+  messageId: string,
+  content: string,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    const thinkingPartIndex = parts.findIndex((p) => p.type === 'thinking')
+
+    const thinkingPart: ThinkingPart = {
+      type: 'thinking',
+      content,
+    }
+
+    if (thinkingPartIndex >= 0) {
+      // Update existing thinking part
+      parts[thinkingPartIndex] = thinkingPart
+    } else {
+      // Add new thinking part at the end (preserve natural streaming order)
+      parts.push(thinkingPart)
+    }
+
+    return { ...msg, parts }
+  })
+}