@tanstack/ai 0.43.1 → 0.44.1

package/src/activities/chat/messages.ts

@@ -184,8 +184,12 @@ function buildUserOrToolMessage(uiMessage: UIMessage): ModelMessage {
   }
 
   return {
+    id: uiMessage.id,
     role: uiMessage.role as 'user' | 'assistant' | 'tool',
     content: collapseContentParts(contentParts),
+    ...(uiMessage.createdAt !== undefined && {
+      createdAt: uiMessage.createdAt,
+    }),
   }
 }
 
@@ -228,6 +232,8 @@ function isToolCallIncluded(part: ToolCallPart): boolean {
  * result is emitted as a tool message.
  */
 function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
+  // A single UI message can fan out into several model messages. Keep the
+  // shared UI id on each one so persistence can retain the original identity.
   const messageList: Array<ModelMessage> = []
   let current = createSegment()
   let pendingThinking: Array<{ content: string; signature?: string }> = []
@@ -244,10 +250,14 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
 
     if (hasContent || hasToolCalls) {
       messageList.push({
+        id: uiMessage.id,
         role: 'assistant',
         content,
         ...(hasToolCalls && { toolCalls: current.toolCalls }),
         ...(pendingThinking.length > 0 && { thinking: pendingThinking }),
+        ...(uiMessage.createdAt !== undefined && {
+          createdAt: uiMessage.createdAt,
+        }),
       })
       pendingThinking = []
     }
@@ -288,9 +298,13 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
           !emittedToolResultIds.has(part.toolCallId)
         ) {
           messageList.push({
+            id: uiMessage.id,
             role: 'tool',
             content: part.content,
             toolCallId: part.toolCallId,
+            ...(uiMessage.createdAt !== undefined && {
+              createdAt: uiMessage.createdAt,
+            }),
           })
           emittedToolResultIds.add(part.toolCallId)
         }
@@ -347,9 +361,13 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
     // emit the concrete output regardless of approval metadata.
     if (part.output !== undefined && !emittedToolResultIds.has(part.id)) {
       messageList.push({
+        id: uiMessage.id,
         role: 'tool',
         content: normalizeToolResult(part.output),
         toolCallId: part.id,
+        ...(uiMessage.createdAt !== undefined && {
+          createdAt: uiMessage.createdAt,
+        }),
       })
       emittedToolResultIds.add(part.id)
     }
@@ -363,6 +381,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
     ) {
       const approved = part.approval.approved
       messageList.push({
+        id: uiMessage.id,
         role: 'tool',
         content: JSON.stringify({
           approved,
@@ -372,6 +391,9 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
             : 'User denied this action',
         }),
         toolCallId: part.id,
+        ...(uiMessage.createdAt !== undefined && {
+          createdAt: uiMessage.createdAt,
+        }),
       })
       emittedToolResultIds.add(part.id)
     }
@@ -380,8 +402,12 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
   // If no messages were produced (e.g., empty parts), emit a minimal assistant message
   if (messageList.length === 0) {
     messageList.push({
+      id: uiMessage.id,
       role: 'assistant',
       content: null,
+      ...(uiMessage.createdAt !== undefined && {
+        createdAt: uiMessage.createdAt,
+      }),
     })
   }
 
@@ -469,6 +495,9 @@ export function modelMessageToUIMessage(
     id: id || generateMessageId(),
     role: modelMessage.role === 'tool' ? 'assistant' : modelMessage.role,
     parts,
+    ...(modelMessage.createdAt !== undefined && {
+      createdAt: modelMessage.createdAt,
+    }),
   }
 }
 
@@ -659,7 +688,7 @@ export function normalizeToUIMessage(
     // ModelMessage - convert to UIMessage
     return {
       ...modelMessageToUIMessage(message, generateId()),
-      createdAt: new Date(),
+      createdAt: message.createdAt ?? new Date(),
     }
   }
 }

package/src/activities/embed/adapter.ts

@@ -0,0 +1,112 @@
+import type {
+  EmbeddingModelInputModalitiesByName,
+  EmbeddingOptions,
+  EmbeddingResult,
+} from '../../types'
+
+/**
+ * Configuration for embedding adapter instances
+ */
+export interface EmbeddingAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Embedding adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'text-embedding-3-small')
+ * - TProviderOptions: Base provider-specific options (already resolved)
+ * - TModelProviderOptionsByName: Map from model name to its specific provider options
+ * - TModelInputModalitiesByName: Map from model name to the input modalities it
+ *   accepts (constrains the `input` item types at compile time)
+ */
+export interface EmbeddingAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
+  TModelInputModalitiesByName extends EmbeddingModelInputModalitiesByName =
+    EmbeddingModelInputModalitiesByName,
+> {
+  /** Discriminator for adapter kind */
+  readonly kind: 'embedding'
+  /** Adapter name identifier */
+  readonly name: string
+  /** The model this adapter is configured for */
+  readonly model: TModel
+
+  /**
+   * @internal Type-only properties for inference. Not assigned at runtime.
+   */
+  '~types': {
+    providerOptions: TProviderOptions
+    modelProviderOptionsByName: TModelProviderOptionsByName
+    modelInputModalitiesByName: TModelInputModalitiesByName
+  }
+
+  /**
+   * Generate embeddings for the input items (one vector per item)
+   */
+  createEmbeddings: (
+    options: EmbeddingOptions<TProviderOptions>,
+  ) => Promise<EmbeddingResult>
+}
+
+/**
+ * An EmbeddingAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyEmbeddingAdapter = EmbeddingAdapter<any, any, any, any>
+
+/**
+ * Abstract base class for embedding adapters.
+ * Extend this class to implement an embedding adapter for a specific provider.
+ *
+ * Generic parameters match EmbeddingAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseEmbeddingAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
+  TModelInputModalitiesByName extends EmbeddingModelInputModalitiesByName =
+    EmbeddingModelInputModalitiesByName,
+> implements EmbeddingAdapter<
+  TModel,
+  TProviderOptions,
+  TModelProviderOptionsByName,
+  TModelInputModalitiesByName
+> {
+  readonly kind = 'embedding' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+    modelProviderOptionsByName: TModelProviderOptionsByName
+    modelInputModalitiesByName: TModelInputModalitiesByName
+  }
+
+  protected config: EmbeddingAdapterConfig
+
+  constructor(model: TModel, config: EmbeddingAdapterConfig = {}) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract createEmbeddings(
+    options: EmbeddingOptions<TProviderOptions>,
+  ): Promise<EmbeddingResult>
+
+  protected generateId(prefix?: string): string {
+    const p = prefix ?? this.name
+    return `${p}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+  }
+}

package/src/activities/embed/index.ts

@@ -0,0 +1,318 @@
+/**
+ * Embed Activity
+ *
+ * Generates embedding vectors from text and (for multimodal models) image
+ * inputs. This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import { aiEventClient } from '@tanstack/ai-event-client'
+import { resolveDebugOption } from '../../logger/resolve'
+import {
+  createGenerationContext,
+  runGenerationError,
+  runGenerationFinish,
+  runGenerationStart,
+  runGenerationUsage,
+} from '../middleware/run'
+import { countEmbeddingInputModalities } from '../../utilities/embedding-input'
+import type { InternalLogger } from '../../logger/internal-logger'
+import type { DebugOption } from '../../logger/types'
+import type { GenerationMiddleware } from '../middleware/types'
+import type { EmbeddingAdapter } from './adapter'
+import type {
+  EmbeddingInputItem,
+  EmbeddingInputItemFor,
+  EmbeddingResult,
+} from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'embedding' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/**
+ * Extract model-specific provider options from an EmbeddingAdapter via ~types.
+ * If the model has specific options defined in ModelProviderOptions (and not just via index signature),
+ * use those; otherwise fall back to base provider options.
+ */
+export type EmbedProviderOptionsForModel<TAdapter, TModel extends string> =
+  TAdapter extends EmbeddingAdapter<
+    any,
+    infer BaseOptions,
+    infer ModelOptions,
+    any
+  >
+    ? string extends keyof ModelOptions
+      ? // ModelOptions is Record<string, unknown> or has index signature - use BaseOptions
+        BaseOptions
+      : // ModelOptions has explicit keys - check if TModel is one of them
+        TModel extends keyof ModelOptions
+        ? ModelOptions[TModel]
+        : BaseOptions
+    : object
+
+/**
+ * Extract the input type a model accepts from an EmbeddingAdapter via ~types.
+ * Adapters declare a per-model input-modality map; models in the map get an
+ * `input` narrowed to their supported item types (text-only models accept
+ * `string | TextPart`), so unsupported items fail at compile time. Adapters
+ * without a map fall back to the full EmbeddingInputItem union.
+ */
+export type EmbeddingInputForModel<TAdapter, TModel extends string> =
+  TAdapter extends EmbeddingAdapter<any, any, any, infer ModsByName>
+    ? string extends keyof ModsByName
+      ? // No explicit map - accept the full union
+          EmbeddingInputItem | Array<EmbeddingInputItem>
+      : TModel extends keyof ModsByName
+        ?
+            | EmbeddingInputItemFor<ModsByName[TModel][number]>
+            | Array<EmbeddingInputItemFor<ModsByName[TModel][number]>>
+        : EmbeddingInputItem | Array<EmbeddingInputItem>
+    : EmbeddingInputItem | Array<EmbeddingInputItem>
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the embed activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The embedding adapter type
+ */
+export type EmbedOptions<
+  TAdapter extends EmbeddingAdapter<string, any, any, any>,
+> = {
+  /** The embedding adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+  /**
+   * What to embed: a single item or an array of items. Each item in the array
+   * produces exactly one vector. An item is a plain string, a text part, an
+   * image part, or — for models that embed text and image together — a fused
+   * item written as a nested array of parts (`[textPart, imagePart]`), the
+   * same `Array<ContentPart>` shape chat messages use. The accepted item types
+   * are narrowed per model via the adapter's input-modality map.
+   */
+  input: EmbeddingInputForModel<TAdapter, TAdapter['model']>
+  /**
+   * Requested output dimensionality. Supported by models with Matryoshka /
+   * configurable dimensions; adapters for fixed-dimension models throw a
+   * clear runtime error when this is set.
+   */
+  dimensions?: number
+  /**
+   * Enable debug logging. Pass `true` to enable all categories, `false` to
+   * silence everything including errors, or a `DebugConfig` object for granular
+   * control and/or a custom `Logger`.
+   */
+  debug?: DebugOption
+  /**
+   * Observe-only middleware notified on start, usage, success, and error. Pass
+   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
+   * `GenerationMiddleware` contract for a custom backend.
+   */
+  middleware?: Array<GenerationMiddleware>
+} & ({} extends EmbedProviderOptionsForModel<TAdapter, TAdapter['model']>
+  ? {
+      /** Provider-specific options for embedding generation */ modelOptions?: EmbedProviderOptionsForModel<
+        TAdapter,
+        TAdapter['model']
+      >
+    }
+  : {
+      /** Provider-specific options for embedding generation */ modelOptions: EmbedProviderOptionsForModel<
+        TAdapter,
+        TAdapter['model']
+      >
+    })
+
+function createId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * Embed activity - generates embedding vectors from text and image inputs.
+ *
+ * Accepts a single item or an array of items; the result always carries an
+ * `embeddings` array with one vector per input item, in input order.
+ *
+ * @example Embed a single text
+ * ```ts
+ * import { embed } from '@tanstack/ai'
+ * import { openaiEmbedding } from '@tanstack/ai-openai'
+ *
+ * const result = await embed({
+ *   adapter: openaiEmbedding('text-embedding-3-small'),
+ *   input: 'a red guitar',
+ * })
+ *
+ * console.log(result.embeddings[0].vector)
+ * ```
+ *
+ * @example Batch with requested dimensions
+ * ```ts
+ * const result = await embed({
+ *   adapter: openaiEmbedding('text-embedding-3-large'),
+ *   input: ['a red guitar', 'a blue drum kit'],
+ *   dimensions: 1024,
+ * })
+ * ```
+ *
+ * @example Multimodal embedding (text + image fused into one vector)
+ * ```ts
+ * import { cohereEmbedding } from '@tanstack/ai-cohere'
+ *
+ * // A nested array of parts fuses them into a single vector. The outer array
+ * // is the item list, so this embeds one fused item into one vector.
+ * const result = await embed({
+ *   adapter: cohereEmbedding('embed-v4.0'),
+ *   input: [
+ *     [
+ *       { type: 'text', content: 'product photo' },
+ *       { type: 'image', source: { type: 'data', value: base64, mimeType: 'image/png' } },
+ *     ],
+ *   ],
+ *   modelOptions: { inputType: 'search_document' },
+ * })
+ * ```
+ */
+export async function embed<
+  TAdapter extends EmbeddingAdapter<string, any, any, any>,
+>(options: EmbedOptions<TAdapter>): Promise<EmbeddingResult> {
+  const { adapter, middleware } = options
+  const model = adapter.model
+  const requestId = createId('embedding')
+  const startTime = Date.now()
+  const logger: InternalLogger = resolveDebugOption(options.debug)
+  const modelOptions = (options as { modelOptions?: Record<string, unknown> })
+    .modelOptions
+
+  // Normalize once: adapters always receive an array of items.
+  const inputItems: Array<EmbeddingInputItem> = Array.isArray(options.input)
+    ? options.input
+    : [options.input]
+  const { textInputCount, imageInputCount } =
+    countEmbeddingInputModalities(inputItems)
+
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: 'embedding',
+    provider: adapter.name,
+    model,
+    modelOptions,
+    createId,
+  })
+
+  await runGenerationStart(middleware, mwCtx)
+
+  aiEventClient.emit('embedding:request:started', {
+    requestId,
+    provider: adapter.name,
+    model,
+    inputCount: inputItems.length,
+    textInputCount,
+    imageInputCount,
+    dimensions: options.dimensions,
+    modelOptions,
+    timestamp: startTime,
+  })
+
+  logger.request(`activity=embed provider=${adapter.name} model=${model}`, {
+    provider: adapter.name,
+    model,
+  })
+
+  try {
+    const result = await adapter.createEmbeddings({
+      model,
+      input: inputItems,
+      dimensions: options.dimensions,
+      modelOptions,
+      logger,
+    })
+    const duration = Date.now() - startTime
+
+    aiEventClient.emit('embedding:request:completed', {
+      requestId,
+      provider: adapter.name,
+      model,
+      embeddingCount: result.embeddings.length,
+      dimensions: result.embeddings[0]?.vector.length,
+      duration,
+      modelOptions,
+      timestamp: Date.now(),
+    })
+
+    logger.output(`activity=embed count=${result.embeddings.length}`, {
+      embeddingCount: result.embeddings.length,
+    })
+
+    if (result.usage) {
+      aiEventClient.emit('embedding:usage', {
+        requestId,
+        model,
+        usage: result.usage,
+        timestamp: Date.now(),
+      })
+      await runGenerationUsage(middleware, mwCtx, result.usage)
+    }
+    await runGenerationFinish(middleware, mwCtx, {
+      duration,
+      usage: result.usage,
+    })
+
+    return result
+  } catch (error) {
+    const duration = Date.now() - startTime
+    const err = error as Error
+    aiEventClient.emit('embedding:request:error', {
+      requestId,
+      provider: adapter.name,
+      model,
+      error: { message: err.message, name: err.name },
+      duration,
+      modelOptions,
+      timestamp: Date.now(),
+    })
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration,
+    })
+    logger.errors('embed activity failed', {
+      error,
+      source: 'embed',
+    })
+    throw error
+  }
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the embed() function without executing.
+ */
+export function createEmbedOptions<
+  TAdapter extends EmbeddingAdapter<string, any, any, any>,
+>(options: EmbedOptions<TAdapter>): EmbedOptions<TAdapter> {
+  return options
+}
+
+// Re-export adapter types
+export type {
+  EmbeddingAdapter,
+  EmbeddingAdapterConfig,
+  AnyEmbeddingAdapter,
+} from './adapter'
+export { BaseEmbeddingAdapter } from './adapter'

package/src/activities/error-payload.ts

@@ -18,6 +18,21 @@ const ABORT_ERROR_NAMES = new Set([
   'RequestAbortedError',
 ])
 
+/**
+ * True when a thrown value is an abort-shaped error (DOM `AbortError`, OpenAI
+ * `APIUserAbortError`, OpenRouter `RequestAbortedError`) — i.e. user-initiated
+ * cancellation rather than a genuine failure. Matches on the error `name` so
+ * callers can discriminate aborts without depending on a signal's state or on
+ * provider-specific message strings.
+ */
+export function isAbortShapedError(error: unknown): boolean {
+  if (error && typeof error === 'object') {
+    const name = (error as { name?: unknown }).name
+    return typeof name === 'string' && ABORT_ERROR_NAMES.has(name)
+  }
+  return false
+}
+
 // HTTP status codes carried as numbers (e.g. `error.status = 429`) are a
 // common variant on SDK error classes; coerce so the resulting `code` field
 // is stable as a string for downstream consumers.
@@ -29,32 +44,49 @@ function normalizeCode(codeField: unknown): string | undefined {
   return undefined
 }
 
+// SDK error classes disagree on where they carry the HTTP status. Most expose a
+// `code` (OpenAI/Anthropic error bodies), but some report it only as a numeric
+// `status` — Google's `@google/genai` `ApiError` sets `status: number` and no
+// `code` at all. Without this fallback such errors reach downstream consumers
+// with `code: undefined`, so a 401/403/404/429 is indistinguishable from an
+// unknown failure and cannot be classified.
+//
+// Only a *numeric* `status` is used: a string `status` is commonly an HTTP
+// reason phrase ("Forbidden") or a symbolic status ("PERMISSION_DENIED"), not
+// the numeric code consumers key on, so forwarding it would be misleading.
+function extractCode(source: {
+  code?: unknown
+  status?: unknown
+}): string | undefined {
+  const fromCode = normalizeCode(source.code)
+  if (fromCode !== undefined) return fromCode
+  if (typeof source.status === 'number' && Number.isFinite(source.status)) {
+    return String(source.status)
+  }
+  return undefined
+}
+
 export function toRunErrorPayload(
   error: unknown,
   fallbackMessage = 'Unknown error occurred',
 ): { message: string; code: string | undefined } {
-  if (error && typeof error === 'object') {
-    const name = (error as { name?: unknown }).name
-    if (typeof name === 'string' && ABORT_ERROR_NAMES.has(name)) {
-      return { message: 'Request aborted', code: 'aborted' }
-    }
+  if (isAbortShapedError(error)) {
+    return { message: 'Request aborted', code: 'aborted' }
   }
   if (error instanceof Error) {
-    const codeField = (error as Error & { code?: unknown }).code
     return {
       message: error.message || fallbackMessage,
-      code: normalizeCode(codeField),
+      code: extractCode(error as Error & { code?: unknown; status?: unknown }),
     }
   }
   if (typeof error === 'object' && error !== null) {
     const messageField = (error as { message?: unknown }).message
-    const codeField = (error as { code?: unknown }).code
     return {
       message:
         typeof messageField === 'string' && messageField.length > 0
           ? messageField
           : fallbackMessage,
-      code: normalizeCode(codeField),
+      code: extractCode(error as { code?: unknown; status?: unknown }),
     }
   }
   if (typeof error === 'string' && error.length > 0) {