@tanstack/ai 0.48.0 → 0.50.0

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

@@ -19,6 +19,7 @@
  */
 import {
   aguiSnapshotMessageToUIMessage,
+  coerceCreatedAt,
   generateMessageId,
   uiMessageToModelMessages,
 } from '../messages.js'
@@ -835,11 +836,10 @@ export class StreamProcessor {
           }
         : incomingRecord
     const metadata = mergeMetadata(message.metadata, toMerge)
-    const createdAtRaw = tanstackMetadata(incomingRecord)?.createdAt
-    const createdAt =
-      typeof createdAtRaw === 'string' ? new Date(createdAtRaw) : undefined
-    const createdAtValid =
-      createdAt !== undefined && !Number.isNaN(createdAt.getTime())
+    const createdAt = coerceCreatedAt(
+      tanstackMetadata(incomingRecord)?.createdAt,
+    )
+    const createdAtValid = createdAt !== undefined
     this.messages = this.messages.map((msg) =>
       msg.id === messageId
         ? {
@@ -1050,8 +1050,10 @@ export class StreamProcessor {
       msg.parts.every((part) => part.type === 'thinking')
     const isToolResultOnly = (msg: UIMessage) =>
       msg.role === 'assistant' &&
-      msg.parts.length === 1 &&
-      msg.parts[0]?.type === 'tool-result'
+      msg.parts.some((part) => part.type === 'tool-result') &&
+      msg.parts.every(
+        (part) => part.type === 'tool-result' || part.type === 'ui-resource',
+      )
     const flushPending = () => {
       out.push(...pending)
       pending = []
@@ -1109,9 +1111,16 @@ export class StreamProcessor {
 
     const reconciled: Array<UIMessage> = []
     for (const msg of snapshot) {
+      const toolResultParts = msg.parts.filter(
+        (part): part is ToolResultPart => part.type === 'tool-result',
+      )
       const toolResultPart =
-        msg.role === 'assistant' && msg.parts.length === 1
-          ? msg.parts.find((p): p is ToolResultPart => p.type === 'tool-result')
+        msg.role === 'assistant' &&
+        toolResultParts.length === 1 &&
+        msg.parts.every(
+          (part) => part.type === 'tool-result' || part.type === 'ui-resource',
+        )
+          ? toolResultParts[0]
           : undefined
 
       if (!toolResultPart) {
@@ -1170,7 +1179,7 @@ export class StreamProcessor {
           )
         }
       }
-      parts.push(toolResultPart)
+      parts.push(...msg.parts)
       // Replace rather than push into `target.parts`: a snapshot message that
       // arrived already carrying `parts` (TanStack server echoing UIMessages)
       // shares its array with the incoming chunk, and mutating it in place

package/src/byok/define-provider.ts

@@ -0,0 +1,46 @@
+import { isProviderId } from './providers'
+
+/**
+ * A BYOK provider declared by an adapter. `id` is the `x-byok-<id>` slug and
+ * is required — `{ id?: string }` is not a {@link ByokProvider}.
+ */
+export interface ByokProvider<TId extends string = string> {
+  readonly id: TId
+  readonly label: string
+  /**
+   * Env var names the relay may read. Names only — never put `process.env`
+   * values here. This object is imported on the client.
+   */
+  readonly env?: ReadonlyArray<string>
+}
+
+/**
+ * Input for {@link defineByokProvider}. `id` cannot be optional: if `TId`
+ * includes `undefined`, `id` becomes `never` and the object is unassignable.
+ */
+export type ByokProviderInit<TId extends string> = {
+  readonly id: undefined extends TId ? never : TId
+  readonly label: string
+  readonly env?: string | ReadonlyArray<string>
+}
+
+function normalizeEnv(
+  env: string | ReadonlyArray<string> | undefined,
+): ReadonlyArray<string> | undefined {
+  if (env === undefined) return undefined
+  return typeof env === 'string' ? [env] : env
+}
+
+export function defineByokProvider<const TId extends string>(
+  provider: ByokProviderInit<TId>,
+): ByokProvider<TId> {
+  if (!isProviderId(provider.id)) {
+    throw new Error(`Invalid BYOK provider id: ${String(provider.id)}`)
+  }
+  const env = normalizeEnv(provider.env)
+  return {
+    id: provider.id,
+    label: provider.label,
+    ...(env ? { env } : {}),
+  }
+}

package/src/byok/errors.ts

@@ -0,0 +1,36 @@
+import type { ProviderId } from './providers'
+
+export class ByokMissingError extends Error {
+  readonly provider: ProviderId
+
+  constructor(provider: ProviderId) {
+    super(`Missing ${provider} API key`)
+    this.name = 'ByokMissingError'
+    this.provider = provider
+  }
+}
+
+export class ByokBlockedError extends Error {
+  readonly provider: ProviderId
+  readonly reason: 'missing' | 'locked'
+
+  constructor(provider: ProviderId, reason: 'missing' | 'locked') {
+    super(
+      reason === 'locked'
+        ? `${provider} key is locked`
+        : `Missing ${provider} API key`,
+    )
+    this.name = 'ByokBlockedError'
+    this.provider = provider
+    this.reason = reason
+  }
+}
+
+export class ByokUnresolvedProviderError extends Error {
+  constructor() {
+    super(
+      'BYOK is enabled but no provider slug was resolved. Pass byokProvider or forwardedProps.provider.',
+    )
+    this.name = 'ByokUnresolvedProviderError'
+  }
+}

package/src/byok/get-key.ts

@@ -0,0 +1,27 @@
+import { byokHeaderName, resolveProviderId } from './providers'
+import type { ByokProvider } from './define-provider'
+import type { ProviderId } from './providers'
+
+/**
+ * Read a key on the relay. Import from `@tanstack/ai/byok/server` so this
+ * `process.env` access is not in the client graph.
+ *
+ * The header wins. A {@link ByokProvider} then tries `provider.env` in order.
+ * A slug is header-only.
+ */
+export function getByokKey(
+  request: Request,
+  provider: ProviderId | ByokProvider,
+): string | null {
+  const value = request.headers.get(byokHeaderName(resolveProviderId(provider)))
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (trimmed.length > 0) return trimmed
+  }
+  if (typeof provider === 'string') return null
+  for (const name of provider.env ?? []) {
+    const envValue = process.env[name]
+    if (typeof envValue === 'string' && envValue.length > 0) return envValue
+  }
+  return null
+}

package/src/byok/missing.ts

@@ -0,0 +1,43 @@
+import { isProviderId, resolveProviderId } from './providers'
+import type { ByokProvider } from './define-provider'
+import type { ProviderId } from './providers'
+
+export interface ByokMissingBody {
+  error: {
+    type: 'byok_missing'
+    provider: ProviderId
+    message: string
+  }
+}
+
+export function isByokMissingBody(value: unknown): value is ByokMissingBody {
+  if (typeof value !== 'object' || value === null) return false
+  if (!('error' in value)) return false
+  const error = value.error
+  if (typeof error !== 'object' || error === null) return false
+  if (!('type' in error) || error.type !== 'byok_missing') return false
+  if (!('provider' in error) || typeof error.provider !== 'string') {
+    return false
+  }
+  if (!isProviderId(error.provider)) return false
+  if (!('message' in error) || typeof error.message !== 'string') return false
+  return true
+}
+
+export function byokMissing(provider: ProviderId | ByokProvider): Response {
+  const id = resolveProviderId(provider)
+  if (!isProviderId(id)) {
+    throw new Error(`Invalid BYOK provider id: ${id}`)
+  }
+  const body: ByokMissingBody = {
+    error: {
+      type: 'byok_missing',
+      provider: id,
+      message: `Missing ${id} API key`,
+    },
+  }
+  return new Response(JSON.stringify(body), {
+    status: 401,
+    headers: { 'content-type': 'application/json' },
+  })
+}

package/src/byok/providers.ts

@@ -0,0 +1,27 @@
+/**
+ * Provider ids are open slugs, not a closed catalog. `@tanstack/ai` does not
+ * list adapters. Any matching string is a valid id and becomes `x-byok-<id>`.
+ */
+export type ProviderId = string
+
+/** `[a-z][a-z0-9-]{0,63}` — lowercase, no underscores, max 64 chars. */
+export const BYOK_PROVIDER_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/
+
+export const BYOK_HEADER_PREFIX = 'x-byok-'
+
+export function isProviderId(value: unknown): value is ProviderId {
+  return typeof value === 'string' && BYOK_PROVIDER_ID_PATTERN.test(value)
+}
+
+export function resolveProviderId(
+  provider: string | { readonly id: string },
+): string {
+  return typeof provider === 'string' ? provider : provider.id
+}
+
+export function byokHeaderName(provider: string): string {
+  if (!isProviderId(provider)) {
+    throw new Error(`Invalid BYOK provider id: ${provider}`)
+  }
+  return `${BYOK_HEADER_PREFIX}${provider}`
+}

package/src/byok/scrub.ts

@@ -0,0 +1,16 @@
+export function maskKey(key: string): string {
+  if (key.length <= 4) return '••'
+  return key.slice(-4)
+}
+
+export function scrubSecrets(
+  input: string,
+  secrets: ReadonlyArray<string>,
+): string {
+  let next = input
+  for (const secret of secrets) {
+    if (secret.length === 0) continue
+    next = next.split(secret).join('[redacted]')
+  }
+  return next
+}

package/src/byok/server.ts

@@ -0,0 +1,3 @@
+export { getByokKey } from './get-key'
+export { byokMissing, isByokMissingBody } from './missing'
+export type { ByokMissingBody } from './missing'

package/src/byok.ts

@@ -0,0 +1,17 @@
+export {
+  BYOK_PROVIDER_ID_PATTERN,
+  BYOK_HEADER_PREFIX,
+  byokHeaderName,
+  isProviderId,
+} from './byok/providers'
+export type { ProviderId } from './byok/providers'
+export { defineByokProvider } from './byok/define-provider'
+export type { ByokProvider, ByokProviderInit } from './byok/define-provider'
+export { isByokMissingBody, byokMissing } from './byok/missing'
+export type { ByokMissingBody } from './byok/missing'
+export {
+  ByokMissingError,
+  ByokBlockedError,
+  ByokUnresolvedProviderError,
+} from './byok/errors'
+export { maskKey, scrubSecrets } from './byok/scrub'

package/src/interrupt-resume.ts

@@ -445,6 +445,20 @@ export async function validateInterruptResumeBatch(
       continue
     }
 
+    if (entry.status === 'cancelled') {
+      if (entry.payload !== undefined) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'invalid-payload',
+            `Cancelled interrupt ${record.interruptId} must not include a payload.`,
+          ),
+        )
+      }
+      continue
+    }
+
     const tool = runtimeTool(input.tools, binding.toolName)
     if (!tool) {
       errors.push(
@@ -511,19 +525,6 @@ export async function validateInterruptResumeBatch(
       }
     }
 
-    if (entry.status === 'cancelled') {
-      if (entry.payload !== undefined) {
-        errors.push(
-          interruptItemError(
-            input,
-            record.interruptId,
-            'invalid-payload',
-            `Cancelled interrupt ${record.interruptId} must not include a payload.`,
-          ),
-        )
-      }
-      continue
-    }
     if (schemaDrifted) continue
 
     if (binding.kind === 'client-tool-execution') {

package/src/types.ts

@@ -372,6 +372,10 @@ export interface ModelMessage<
   toolCalls?: Array<ToolCall>
   toolCallId?: string
   thinking?: Array<{ content: string; signature?: string }>
+  /** Error reported by an AG-UI tool message. */
+  error?: string
+  /** Optional AG-UI message metadata. TanStack-owned fields live under `tanstack`. */
+  metadata?: Record<string, any>
   /**
    * Completed structured output represented by this assistant message.
    * `content` remains the provider-facing JSON text; this field preserves the
@@ -435,10 +439,14 @@ export interface ToolCallPart<TMetadata = unknown> {
 
 export interface ToolResultPart {
   type: 'tool-result'
+  id?: string
+  name?: string
   toolCallId: string
   content: string | Array<ContentPart>
   state: ToolResultState
   error?: string // Error message if state is "error"
+  metadata?: Record<string, unknown>
+  createdAt?: Date
 }
 
 export interface ThinkingPart {
@@ -524,9 +532,17 @@ export interface TanStackMessageMetadata {
   signature?: string
   /** Per-tool-call provider metadata keyed by tool call id (e.g. Gemini thoughtSignature). */
   toolCallMetadata?: Record<string, unknown>
+  toolResult?: {
+    id?: string
+    createdAt?: string
+    content?: Array<ContentPart>
+  }
   structuredOutput?: {
     status?: 'streaming' | 'complete' | 'error'
+    partial?: unknown
+    data?: unknown
     raw?: string
+    reasoning?: string
     errorMessage?: string
   }
   uiResources?: Array<UIResourcePart>
@@ -562,6 +578,8 @@ export interface UIMessage<TData = unknown> {
   role: 'system' | 'user' | 'assistant'
   parts: Array<MessagePart<TData>>
   createdAt?: Date
+  /** Optional AG-UI sender name. Converters preserve it across wire and persist. */
+  name?: string
   /**
    * Optional AG-UI metadata bag. TanStack writes the `tanstack` key.
    * User keys stay at the top.