@tanstack/ai 0.47.3 → 0.48.0

package/src/utilities/chat-params.ts

@@ -12,32 +12,6 @@ import type {
   UIMessage,
 } from '../types'
 
-const KNOWN_PART_TYPES = new Set([
-  'text',
-  'image',
-  'audio',
-  'video',
-  'document',
-  'tool-call',
-  'tool-result',
-  'thinking',
-  'structured-output',
-])
-
-function isValidParts(value: unknown): value is Array<{ type: string }> {
-  if (!Array.isArray(value)) return false
-  for (const p of value) {
-    if (!p || typeof p !== 'object') return false
-    const type = (p as { type?: unknown }).type
-    if (typeof type !== 'string' || !KNOWN_PART_TYPES.has(type)) return false
-    if (type === 'structured-output') {
-      const raw = (p as { raw?: unknown }).raw
-      if (raw !== undefined && typeof raw !== 'string') return false
-    }
-  }
-  return true
-}
-
 /**
  * Keyed by `AGUIRole` so a role added upstream fails to compile here until it
  * is handled, rather than silently falling through as an unknown role.
@@ -86,7 +60,7 @@ function requireArray(value: unknown, at: string): Array<unknown> {
 /**
  * Assert one AG-UI `Message`, discriminating on `role` exactly as the upstream
  * `MessageSchema` discriminated union does. The record view is retained on the
- * asserted type so callers can still inspect non-AG-UI extras like `parts`.
+ * asserted type so callers can still inspect extras like `metadata`.
  */
 function assertAGUIMessage(
   value: Record<string, unknown>,
@@ -141,16 +115,25 @@ function validateMessage(value: unknown, index: number): AGUIMessage {
   if (!isRecord(value)) invalidBody(`${at} must be an object`)
   assertAGUIMessage(value, at)
 
-  // `parts` is TanStack's canonical extra, carried through so the UIMessage
-  // path inside `chat()` can use it. Keep it only when it holds recognized
-  // part types — the previous schema-based path dropped `parts` during parse
-  // and re-attached it from the raw body behind this same check.
-  if ('parts' in value && !isValidParts(value.parts)) {
-    const withoutParts = { ...value }
-    Reflect.deleteProperty(withoutParts, 'parts')
-    return withoutParts
+  if (value.metadata !== undefined) {
+    if (!isRecord(value.metadata)) {
+      invalidBody(`${at}.metadata must be an object`)
+    }
   }
-  return value
+
+  // Hard cut: inbound `parts` from old clients are dropped. Content,
+  // toolCalls, and metadata stay on the record. Copy so we do not mutate
+  // the caller's message object.
+  return dropInboundParts(value)
+}
+
+function dropInboundParts(
+  message: AGUIMessage & { parts?: unknown },
+): AGUIMessage {
+  if (!('parts' in message)) return message
+  const rest = { ...message }
+  delete rest.parts
+  return rest
 }
 
 function validateTool(
@@ -330,8 +313,8 @@ export async function chatParamsFromRequest(
 
 /**
  * Client-declared tool stub (no execute). `name` is `string`, so arrays that
- * include these stubs intentionally widen `TypedStreamChunk` tool-name
- * discrimination — pass server tools alone when you need a closed name union.
+ * include these stubs intentionally widen tool-name discrimination —
+ * pass server tools alone when you need a closed name union.
  */
 export type ClientToolDeclaration = {
   name: string
@@ -360,7 +343,7 @@ export type MergedAgentTools<TServerTools extends ReadonlyArray<AnyTool>> =
  * Typing:
  * - Empty `clientTools` preserves the server tuple (closed name union).
  * - Non-empty `clientTools` returns a widened array that honestly includes
- *   client stubs, so `TypedStreamChunk` does not claim a closed server-only
+ *   client stubs, so the merged array does not claim a closed server-only
  *   name union.
  *
  * @param serverTools - The server's tool array (e.g. from

package/src/utilities/chunk-ids.ts

@@ -0,0 +1,24 @@
+import type { StreamChunk } from '../types'
+import { tanstackMetadata } from './merge-metadata'
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined
+}
+
+/** Run id on the spec event, or `metadata.tanstack.runId` after normalize. */
+export function getChunkRunId(chunk: StreamChunk): string | undefined {
+  if ('runId' in chunk) {
+    const top = stringField(chunk.runId)
+    if (top !== undefined) return top
+  }
+  return stringField(tanstackMetadata(chunk)?.runId)
+}
+
+/** Thread id on the spec event, or `metadata.tanstack.threadId` after normalize. */
+export function getChunkThreadId(chunk: StreamChunk): string | undefined {
+  if ('threadId' in chunk) {
+    const top = stringField(chunk.threadId)
+    if (top !== undefined) return top
+  }
+  return stringField(tanstackMetadata(chunk)?.threadId)
+}

package/src/utilities/merge-metadata.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest'
+import {
+  mergeMetadata,
+  tanstackMetadata,
+  withTanstackMetadata,
+} from './merge-metadata'
+
+describe('mergeMetadata', () => {
+  it('deep-merges tanstack and last-write-wins sibling keys', () => {
+    const merged = mergeMetadata(
+      { author: 'dana', tanstack: { model: 'gpt-5.5' } },
+      { tanstack: { createdAt: '2026-08-20T00:00:00.000Z' } },
+    )
+    expect(merged).toEqual({
+      author: 'dana',
+      tanstack: {
+        model: 'gpt-5.5',
+        createdAt: '2026-08-20T00:00:00.000Z',
+      },
+    })
+  })
+
+  it('last write wins for overlapping tanstack keys', () => {
+    const merged = mergeMetadata(
+      { tanstack: { model: 'gpt-5.5', finishReason: 'stop' } },
+      { tanstack: { model: 'claude' } },
+    )
+    expect(merged).toEqual({
+      tanstack: { model: 'claude', finishReason: 'stop' },
+    })
+  })
+
+  it('keeps a null value under a key', () => {
+    expect(mergeMetadata({ author: 'dana' }, { author: null })).toEqual({
+      author: null,
+    })
+  })
+
+  it('treats incoming null as absent', () => {
+    expect(mergeMetadata({ author: 'dana' }, null)).toEqual({ author: 'dana' })
+  })
+
+  it('treats incoming undefined as absent', () => {
+    expect(mergeMetadata({ author: 'dana' }, undefined)).toEqual({
+      author: 'dana',
+    })
+  })
+
+  it('returns incoming when current is missing', () => {
+    expect(mergeMetadata(undefined, { author: 'dana' })).toEqual({
+      author: 'dana',
+    })
+  })
+})
+
+describe('tanstackMetadata', () => {
+  it('reads metadata.tanstack when it is an object', () => {
+    expect(
+      tanstackMetadata({ metadata: { tanstack: { model: 'gpt-5.5' } } }),
+    ).toEqual({ model: 'gpt-5.5' })
+  })
+
+  it('returns undefined when tanstack is missing or not an object', () => {
+    expect(tanstackMetadata({})).toBeUndefined()
+    expect(tanstackMetadata({ metadata: { tanstack: 'nope' } })).toBeUndefined()
+    expect(tanstackMetadata({ metadata: { tanstack: [] } })).toBeUndefined()
+  })
+
+  it('returns undefined when nested metadata is null', () => {
+    expect(tanstackMetadata({ metadata: null })).toBeUndefined()
+  })
+
+  it('reads tanstack from a raw record', () => {
+    expect(tanstackMetadata({ tanstack: { model: 'gpt-5.5' } })).toEqual({
+      model: 'gpt-5.5',
+    })
+  })
+})
+
+describe('withTanstackMetadata', () => {
+  it('writes metadata.tanstack and does not set the reserved ag-ui key', () => {
+    const next = withTanstackMetadata(
+      { type: 'RUN_STARTED' },
+      { model: 'gpt-5.5' },
+    )
+    expect(next.metadata).toEqual({ tanstack: { model: 'gpt-5.5' } })
+    expect(next.metadata).not.toHaveProperty('ag-ui')
+  })
+
+  it('merges new tanstack keys into existing metadata without dropping user keys', () => {
+    const next = withTanstackMetadata(
+      { metadata: { author: 'dana', tanstack: { model: 'gpt-5.5' } } },
+      { finishReason: 'stop' },
+    )
+    expect(next.metadata).toEqual({
+      author: 'dana',
+      tanstack: { model: 'gpt-5.5', finishReason: 'stop' },
+    })
+  })
+
+  it('last write wins for overlapping tanstack keys', () => {
+    const next = withTanstackMetadata(
+      { metadata: { tanstack: { model: 'gpt-5.5' } } },
+      { model: 'claude' },
+    )
+    expect(next.metadata).toEqual({ tanstack: { model: 'claude' } })
+  })
+
+  it('treats null metadata as absent and still writes tanstack', () => {
+    expect(() =>
+      withTanstackMetadata({ metadata: null }, { model: 'gpt-5.5' }),
+    ).not.toThrow()
+    expect(
+      withTanstackMetadata({ metadata: null }, { model: 'gpt-5.5' }).metadata,
+    ).toEqual({ tanstack: { model: 'gpt-5.5' } })
+  })
+})

package/src/utilities/merge-metadata.ts

@@ -0,0 +1,59 @@
+import type { TanStackMessageMetadata, TanStackRunMetadata } from '../types'
+
+export type MetadataRecord = Record<string, any>
+
+/** `metadata.tanstack` on a message or run event. Internal getter return type. */
+export type TanStackMetadata = TanStackMessageMetadata & TanStackRunMetadata
+
+function isPlainRecord(value: unknown): value is MetadataRecord {
+  return value != null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function mergeMetadata(
+  current: MetadataRecord | undefined,
+  incoming: MetadataRecord | null | undefined,
+): MetadataRecord | undefined {
+  if (incoming == null) return current
+  if (current == null) return { ...incoming }
+  const merged: MetadataRecord = { ...current, ...incoming }
+  if (isPlainRecord(current.tanstack) && isPlainRecord(incoming.tanstack)) {
+    merged.tanstack = { ...current.tanstack, ...incoming.tanstack }
+  }
+  return merged
+}
+
+/** Read `metadata.tanstack`. Not part of the public SDK surface. */
+export function tanstackMetadata(
+  value: { metadata?: MetadataRecord | null } | MetadataRecord | undefined,
+): TanStackMetadata | undefined {
+  if (value == null) return undefined
+  const nested = 'metadata' in value ? value.metadata : undefined
+  const metadata =
+    nested != null && typeof nested === 'object' && !Array.isArray(nested)
+      ? nested
+      : (value as MetadataRecord)
+  const tanstack = metadata.tanstack
+  if (
+    tanstack == null ||
+    typeof tanstack !== 'object' ||
+    Array.isArray(tanstack)
+  ) {
+    return undefined
+  }
+  return tanstack as TanStackMetadata
+}
+
+export function withTanstackMetadata<T>(
+  value: T & { metadata?: MetadataRecord | null },
+  tanstack: MetadataRecord,
+): Omit<T, 'metadata'> & { metadata: MetadataRecord } {
+  const current = value.metadata
+  const currentTanstack = tanstackMetadata(value) ?? {}
+  return {
+    ...value,
+    metadata: {
+      ...(current ?? {}),
+      tanstack: { ...currentTanstack, ...tanstack },
+    },
+  }
+}