@tanstack/ai 0.17.0 → 0.19.0

package/src/activities/chat/index.ts

@@ -22,7 +22,7 @@ import {
   parseWithStandardSchema,
 } from './tools/schema-converter'
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
-import { convertMessagesToModelMessages } from './messages'
+import { convertMessagesToModelMessages, generateMessageId } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
 import type {
   ApprovalRequest,
@@ -48,6 +48,7 @@ import type {
   ToolCallArgsEvent,
   ToolCallEndEvent,
   ToolCallStartEvent,
+  UIMessage,
 } from '../../types'
 import type {
   ChatMiddleware,
@@ -85,12 +86,21 @@ export interface TextActivityOptions<
 > {
   /** The text adapter to use (created by a provider function like openaiText('gpt-4o')) */
   adapter: TAdapter
-  /** Conversation messages - content types are constrained by the adapter's input modalities and metadata */
+  /**
+   * Conversation messages. Accepts:
+   * - `ConstrainedModelMessage` — content types constrained by the adapter's input modalities.
+   * - `ModelMessage` — unconstrained model message (e.g., forwarded from an AG-UI wire payload).
+   * - `UIMessage` — parts-based UI representation; converted internally via `convertMessagesToModelMessages`.
+   *
+   * The three shapes can be mixed in a single array (e.g., when forwarding a wire payload that includes both anchor UIMessages and AG-UI fan-out ModelMessages).
+   */
   messages?: Array<
-    ConstrainedModelMessage<{
-      inputModalities: TAdapter['~types']['inputModalities']
-      messageMetadataByModality: TAdapter['~types']['messageMetadataByModality']
-    }>
+    | UIMessage
+    | ModelMessage
+    | ConstrainedModelMessage<{
+        inputModalities: TAdapter['~types']['inputModalities']
+        messageMetadataByModality: TAdapter['~types']['messageMetadataByModality']
+      }>
   >
   /** System prompts to prepend to the conversation */
   systemPrompts?: TextOptions['systemPrompts']
@@ -128,6 +138,8 @@ export interface TextActivityOptions<
   threadId?: TextOptions['threadId']
   /** Run ID override for AG-UI protocol. Auto-generated by adapter if not provided. */
   runId?: TextOptions['runId']
+  /** Parent run ID for AG-UI protocol nested run correlation. */
+  parentRunId?: TextOptions['parentRunId']
   /**
    * Optional Standard Schema for structured output.
    * When provided, the activity will:
@@ -313,6 +325,7 @@ class TextEngine<
   // AG-UI protocol IDs
   private threadId: string
   private runIdOverride?: string
+  private parentRunIdOverride?: string
 
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner
@@ -364,8 +377,15 @@ class TextEngine<
       ? { signal: config.params.abortController.signal }
       : undefined
     this.effectiveSignal = config.params.abortController?.signal
-    this.threadId = config.params.threadId || this.createId('thread')
+    // `conversationId` is the legacy alias of `threadId` — accept it
+    // as a fallback so `chat({ conversationId })` keeps working, with
+    // explicit `threadId` winning when both are set.
+    this.threadId =
+      config.params.threadId ||
+      config.params.conversationId ||
+      this.createId('thread')
     this.runIdOverride = config.params.runId
+    this.parentRunIdOverride = config.params.parentRunId
 
     // Initialize middleware — devtools first, strip-to-spec always last.
     // handleStreamChunk processes raw chunks BEFORE middleware, so internal
@@ -381,7 +401,10 @@ class TextEngine<
     this.middlewareCtx = {
       requestId: this.requestId,
       streamId: this.streamId,
-      conversationId: config.params.conversationId,
+      threadId: this.threadId,
+      // Legacy alias kept on the ctx so middleware that reads
+      // `ctx.conversationId` keeps working. Always equals `threadId`.
+      conversationId: this.threadId,
       phase: 'init' as ChatMiddlewarePhase,
       iteration: 0,
       chunkIndex: 0,
@@ -429,7 +452,7 @@ class TextEngine<
   async *run(): AsyncGenerator<StreamChunk> {
     this.beforeRun()
     this.logger.agentLoop('run started', {
-      conversationId: this.middlewareCtx.conversationId,
+      threadId: this.middlewareCtx.threadId,
     })
 
     try {
@@ -508,7 +531,7 @@ class TextEngine<
           // Genuine error — call onError
           this.logger.errors('chat run failed', {
             error,
-            conversationId: this.middlewareCtx.conversationId,
+            threadId: this.middlewareCtx.threadId,
           })
           await this.middlewareRunner.runOnError(this.middlewareCtx, {
             error,
@@ -634,6 +657,7 @@ class TextEngine<
       logger: this.logger,
       threadId: this.threadId,
       runId: this.runIdOverride,
+      parentRunId: this.parentRunIdOverride,
     })) {
       if (this.isCancelled()) {
         break
@@ -2021,7 +2045,100 @@ async function* runStreamingStructuredOutputImpl<TSchema extends SchemaInput>(
         outputSchema: jsonSchema,
       })
 
+  // Tag the start/complete events with the assistant messageId so the
+  // client-side processor can route JSON deltas to (and snap) the right
+  // StructuredOutputPart. Missing messageId is treated as a hard error
+  // below to avoid silently rendering JSON as plain text.
+  let structuredMessageId: string | null = null
+  let startEmitted = false
+
+  const extractMessageId = (c: StreamChunk): string | null => {
+    const id = (c as { messageId?: unknown }).messageId
+    return typeof id === 'string' && id !== '' ? id : null
+  }
+
+  // Emit a `structured-output.start` (synthesizing a messageId if the
+  // adapter hasn't picked one yet) so that the client processor can route
+  // the forthcoming error chunk into a `structured-output` part on the
+  // placeholder assistant message. Without this, a RUN_ERROR that fires
+  // before the adapter has yielded any TEXT_MESSAGE_START leaves the
+  // assistant message with zero parts — the structured-output UI surface
+  // never sees the error.
+  const emitStartIfNeeded = function* (
+    referenceChunk: StreamChunk,
+  ): Generator<StreamChunk, void, void> {
+    if (startEmitted) return
+    const idForStart = structuredMessageId ?? generateMessageId()
+    structuredMessageId = idForStart
+    startEmitted = true
+    yield {
+      type: EventType.CUSTOM,
+      name: 'structured-output.start',
+      value: { messageId: idForStart },
+      model:
+        'model' in referenceChunk ? (referenceChunk.model ?? model) : model,
+      timestamp:
+        'timestamp' in referenceChunk
+          ? (referenceChunk.timestamp ?? Date.now())
+          : Date.now(),
+      runId,
+    }
+  }
+
   for await (const chunk of stream) {
+    if (!structuredMessageId) {
+      if (
+        chunk.type === EventType.TEXT_MESSAGE_START ||
+        chunk.type === EventType.TEXT_MESSAGE_CONTENT
+      ) {
+        structuredMessageId = extractMessageId(chunk)
+      }
+    }
+
+    // RUN_ERROR before any text deltas: synthesize the structured-output.start
+    // so the client snaps an errored part instead of a silent UI. The
+    // synthesized messageId becomes the assistant message id the client
+    // creates on its side (handleRunErrorEvent calls ensureAssistantMessage()
+    // which picks up the same id from the structured-output.start above).
+    if (chunk.type === EventType.RUN_ERROR && !startEmitted) {
+      yield* emitStartIfNeeded(chunk)
+    }
+
+    // Adapter emitted content with no usable messageId. Routing JSON deltas
+    // into a TextPart would silently render raw JSON in the user's chat, so
+    // fail loudly here instead.
+    if (!structuredMessageId && chunk.type === EventType.TEXT_MESSAGE_CONTENT) {
+      yield {
+        type: EventType.RUN_ERROR,
+        runId,
+        model,
+        timestamp: Date.now(),
+        message:
+          'Structured-output stream produced text content without a messageId; ' +
+          'adapter is not honoring the AG-UI contract.',
+        code: 'structured-output-missing-message-id',
+      }
+      return
+    }
+
+    if (
+      !startEmitted &&
+      structuredMessageId &&
+      (chunk.type === EventType.TEXT_MESSAGE_START ||
+        chunk.type === EventType.TEXT_MESSAGE_CONTENT)
+    ) {
+      startEmitted = true
+      yield {
+        type: EventType.CUSTOM,
+        name: 'structured-output.start',
+        value: { messageId: structuredMessageId },
+        model: 'model' in chunk ? (chunk.model ?? model) : model,
+        timestamp:
+          'timestamp' in chunk ? (chunk.timestamp ?? Date.now()) : Date.now(),
+        runId,
+      }
+    }
+
     if (
       chunk.type === EventType.CUSTOM &&
       chunk.name === 'structured-output.complete'
@@ -2041,10 +2158,15 @@ async function* runStreamingStructuredOutputImpl<TSchema extends SchemaInput>(
             ...chunk,
             // Forward `reasoning` through schema validation so consumers that
             // only listen for the terminal event don't lose chain-of-thought.
+            // Tag with messageId so the client processor can snap the right
+            // assistant message's structured-output part.
             value: {
               object: validated,
               raw: value.raw,
               ...(value.reasoning ? { reasoning: value.reasoning } : {}),
+              ...(structuredMessageId
+                ? { messageId: structuredMessageId }
+                : {}),
             },
           }
           continue
@@ -2076,6 +2198,18 @@ async function* runStreamingStructuredOutputImpl<TSchema extends SchemaInput>(
           return
         }
       }
+      // No Standard schema (raw JSONSchema). Still tag the terminal event
+      // with messageId so the client processor can snap the right part.
+      if (structuredMessageId) {
+        yield {
+          ...chunk,
+          value: {
+            ...(chunk.value as Record<string, unknown>),
+            messageId: structuredMessageId,
+          },
+        }
+        continue
+      }
       yield chunk
       continue
     }

package/src/activities/chat/messages.ts

@@ -24,6 +24,14 @@ function isContentPart(part: MessagePart): part is ContentPart {
   )
 }
 
+function safeJsonStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return ''
+  }
+}
+
 /**
  * Collapse an array of ContentParts into the most compact ModelMessage content:
  * - Empty array → null
@@ -63,15 +71,55 @@ function getTextContent(content: string | null | Array<ContentPart>): string {
 export function convertMessagesToModelMessages(
   messages: Array<UIMessage | ModelMessage>,
 ): Array<ModelMessage> {
+  // Pre-pass: collect toolCallIds already represented in anchor UIMessage parts.
+  // Fan-out tool messages whose toolCallId matches an anchored ToolResultPart
+  // are AG-UI duplicates and must be dropped to avoid double-feeding the LLM.
+  const anchoredToolCallIds = new Set<string>()
+  for (const msg of messages) {
+    if ('parts' in msg) {
+      for (const part of msg.parts) {
+        if (part.type === 'tool-result') {
+          anchoredToolCallIds.add(part.toolCallId)
+        }
+      }
+    }
+  }
+
   const modelMessages: Array<ModelMessage> = []
   for (const msg of messages) {
     if ('parts' in msg) {
-      // UIMessage - convert to ModelMessages
+      // UIMessage anchor — existing fan-out path
       modelMessages.push(...uiMessageToModelMessages(msg))
-    } else {
-      // Already ModelMessage
-      modelMessages.push(msg)
+      continue
+    }
+
+    const role = (msg as { role: string }).role
+
+    // AG-UI tool fan-out duplicate — drop if anchor already covers it
+    if (
+      role === 'tool' &&
+      msg.toolCallId &&
+      anchoredToolCallIds.has(msg.toolCallId)
+    ) {
+      continue
+    }
+
+    // AG-UI reasoning and activity — no ModelMessage equivalent today
+    if (role === 'reasoning' || role === 'activity') {
+      continue
     }
+
+    // AG-UI developer — collapse to system
+    if (role === 'developer') {
+      modelMessages.push({
+        role: 'system' as ModelMessage['role'],
+        content: (msg as { content: string }).content,
+      } as ModelMessage)
+      continue
+    }
+
+    // Already a ModelMessage (user, assistant, system, tool with no anchor) — pass through
+    modelMessages.push(msg)
   }
   return modelMessages
 }
@@ -244,6 +292,24 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         }
         break
 
+      case 'structured-output':
+        // Only emit completed structured responses into history. Streaming or
+        // errored buffers would push malformed JSON into the next LLM turn's
+        // assistant content. `raw` is the source of truth; `data` is the
+        // defensive fallback for terminal-only completes that didn't ship raw.
+        if (part.status === 'complete') {
+          const serialized =
+            part.raw !== ''
+              ? part.raw
+              : part.data !== undefined
+                ? safeJsonStringify(part.data)
+                : ''
+          if (serialized !== '') {
+            current.contentParts.push({ type: 'text', content: serialized })
+          }
+        }
+        break
+
       default:
         break
     }

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

@@ -26,7 +26,7 @@ function instrumentCtx(ctx: ChatMiddlewareContext) {
   return {
     requestId: ctx.requestId,
     streamId: ctx.streamId,
-    clientId: ctx.conversationId,
+    clientId: ctx.threadId,
     timestamp: Date.now(),
   }
 }

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

@@ -28,7 +28,18 @@ export interface ChatMiddlewareContext {
   requestId: string
   /** Unique identifier for this stream */
   streamId: string
-  /** Conversation identifier, if provided by the caller */
+  /**
+   * AG-UI thread identifier — a stable per-conversation ID used to
+   * correlate client and server devtools events. Resolves to the
+   * caller-provided `threadId` (or legacy `conversationId`), or an
+   * auto-generated value when neither is supplied.
+   */
+  threadId: string
+  /**
+   * @deprecated Use `threadId` instead. Retained as an alias of
+   * `threadId` so middleware written before the AG-UI rename keeps
+   * working unchanged. Will be removed in a future major release.
+   */
   conversationId?: string
   /** Current lifecycle phase */
   phase: ChatMiddlewarePhase

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

@@ -5,7 +5,9 @@
  * These are used by StreamProcessor to manage the message array.
  */
 
+import { parsePartialJSON } from './json-parser'
 import type {
+  StructuredOutputPart,
   ThinkingPart,
   ToolCallPart,
   ToolResultPart,
@@ -251,6 +253,175 @@ export function updateToolCallApprovalResponse(
   })
 }
 
+/**
+ * Append a delta to the structured-output part on `messageId`, or create one
+ * if absent. Progressive parse of the accumulated buffer fills `partial`.
+ *
+ * Callers must only invoke this while the part is still in flight — the
+ * helper unconditionally writes `status: 'streaming'`, so feeding it a delta
+ * after a `complete`/`error` terminal would regress the part. In practice the
+ * processor gates calls via `structuredMessageIds`, which is dropped on
+ * terminal events.
+ *
+ * If the progressive parse returns null/undefined (the buffer is not yet a
+ * parseable JSON prefix), the previously-good `partial` is preserved so the
+ * UI doesn't flicker back to empty for a single render.
+ */
+export function appendStructuredOutputDelta(
+  messages: Array<UIMessage>,
+  messageId: string,
+  delta: string,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    const existingIndex = parts.findIndex(
+      (p): p is StructuredOutputPart => p.type === 'structured-output',
+    )
+    const existing =
+      existingIndex >= 0 ? (parts[existingIndex] as StructuredOutputPart) : null
+
+    const nextRaw = (existing?.raw ?? '') + delta
+    const progressive = parsePartialJSON(nextRaw)
+    const nextPartial =
+      progressive !== undefined && progressive !== null
+        ? progressive
+        : existing?.partial
+
+    const nextPart: StructuredOutputPart = {
+      type: 'structured-output',
+      status: 'streaming',
+      raw: nextRaw,
+      ...(nextPartial !== undefined ? { partial: nextPartial } : {}),
+      ...(existing?.reasoning !== undefined
+        ? { reasoning: existing.reasoning }
+        : {}),
+    }
+
+    if (existingIndex >= 0) {
+      parts[existingIndex] = nextPart
+    } else {
+      parts.push(nextPart)
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Snap the structured-output part on `messageId` to `complete` with the
+ * validated `data`. Picks the freshest available `raw` so the wire
+ * round-trip stays internally consistent:
+ *
+ *   1. Caller-supplied `raw` (the original streamed bytes from the model).
+ *   2. The existing part's `raw` (deltas accumulated before this terminal).
+ *   3. `JSON.stringify(data)` as a defensive fallback for terminal-only
+ *      completes that never shipped raw — keeps the part self-consistent
+ *      so downstream consumers never see a complete part with empty raw.
+ */
+export function completeStructuredOutputPart(
+  messages: Array<UIMessage>,
+  messageId: string,
+  data: unknown,
+  raw: string,
+  reasoning?: string,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    const existingIndex = parts.findIndex(
+      (p): p is StructuredOutputPart => p.type === 'structured-output',
+    )
+
+    const existingRaw =
+      existingIndex >= 0
+        ? (parts[existingIndex] as StructuredOutputPart).raw
+        : ''
+    let resolvedRaw = raw || existingRaw
+    if (resolvedRaw === '' && data !== undefined) {
+      try {
+        resolvedRaw = JSON.stringify(data)
+      } catch {
+        // Unserializable (circular, BigInt, throwing toJSON). Leave raw
+        // empty. Both downstream paths handle this: `ag-ui-wire.ts`
+        // `collectText` skips complete parts with empty raw entirely, and
+        // `uiMessageToModelMessages` falls back to a defensive
+        // `safeJsonStringify(data)` which itself returns `''` for the same
+        // unserializable inputs — so the turn is silently dropped from the
+        // next request rather than shipping garbage or crashing the stream.
+      }
+    }
+
+    const nextPart: StructuredOutputPart = {
+      type: 'structured-output',
+      status: 'complete',
+      data,
+      partial: data,
+      raw: resolvedRaw,
+      ...(reasoning !== undefined ? { reasoning } : {}),
+    }
+
+    if (existingIndex >= 0) {
+      parts[existingIndex] = nextPart
+    } else {
+      parts.push(nextPart)
+    }
+
+    return { ...msg, parts }
+  })
+}
+
+/**
+ * Mark the structured-output part on `messageId` as errored. If no part
+ * exists yet — RUN_ERROR fired after `structured-output.start` but before
+ * any delta — create an empty errored placeholder so consumers have
+ * something renderable. Existing complete parts are left alone (an error
+ * after a successful complete should not retroactively un-complete it).
+ */
+export function errorStructuredOutputPart(
+  messages: Array<UIMessage>,
+  messageId: string,
+  errorMessage: string,
+): Array<UIMessage> {
+  return messages.map((msg) => {
+    if (msg.id !== messageId) {
+      return msg
+    }
+
+    const parts = [...msg.parts]
+    const existingIndex = parts.findIndex(
+      (p): p is StructuredOutputPart => p.type === 'structured-output',
+    )
+
+    if (existingIndex < 0) {
+      parts.push({
+        type: 'structured-output',
+        status: 'error',
+        raw: '',
+        errorMessage,
+      })
+      return { ...msg, parts }
+    }
+
+    const existing = parts[existingIndex] as StructuredOutputPart
+    if (existing.status === 'complete') {
+      return msg
+    }
+    parts[existingIndex] = {
+      ...existing,
+      status: 'error',
+      errorMessage,
+    }
+    return { ...msg, parts }
+  })
+}
+
 /**
  * Update or add a thinking part to a message, keyed by stepId.
  * Each distinct stepId produces its own ThinkingPart.