@tanstack/ai 0.43.0 → 0.44.0

package/src/types.ts

@@ -376,6 +376,11 @@ export interface ModelMessage<
    * resume the SAME message bubble in place (see `@tanstack/ai-persistence`).
    */
   id?: string
+  /**
+   * Optional message creation timestamp. When present, message converters
+   * preserve it across persist → hydrate round-trips.
+   */
+  createdAt?: Date
 }
 
 /**
@@ -1992,6 +1997,12 @@ export interface SummarizationOptions<
    * call logger.request() before the SDK call and logger.errors() in catch blocks.
    */
   logger: InternalLogger
+  /**
+   * Effective abort signal composed by the activity from caller `abortSignal`
+   * and/or `timeout`. Adapters should forward this to the provider SDK when
+   * supported. Request-specific — never store on a global client config.
+   */
+  abortSignal?: AbortSignal
 }
 
 export interface SummarizationResult {
@@ -2001,6 +2012,71 @@ export interface SummarizationResult {
   usage: TokenUsage
 }
 
+// ============================================================================
+// Rerank Types
+// ============================================================================
+
+/**
+ * Options passed to a {@link RerankAdapter}. Documents reach the adapter
+ * already serialized to strings — the `rerank()` activity stringifies object
+ * documents and maps results back to the original elements, so adapters never
+ * deal with the caller's document type.
+ */
+export interface RerankOptions<
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  model: string
+  /** The search query documents are scored against. */
+  query: string
+  /** Documents to rerank, pre-serialized to strings by the activity. */
+  documents: Array<string>
+  /** Return only the top N results. Passed through to the provider. */
+  topN?: number
+  /** Provider-specific options forwarded by the rerank() activity. */
+  modelOptions?: TProviderOptions
+  /** Forwarded to the provider request for cancellation. */
+  abortSignal?: AbortSignal
+  /**
+   * Internal logger threaded from the rerank() entry point. Adapters must call
+   * logger.request() before the provider call and logger.errors() in catch
+   * blocks.
+   */
+  logger: InternalLogger
+}
+
+/**
+ * Provider-level rerank result. Adapters return scored indices into the
+ * (serialized) `documents` array plus usage — never the documents themselves.
+ * The activity attaches the original documents.
+ */
+export interface RerankAdapterResult {
+  id: string
+  /** Scored results, highest relevance first, as indices into `documents`. */
+  ranking: Array<{ index: number; score: number }>
+  usage: TokenUsage
+}
+
+/**
+ * Public result of the `rerank()` activity, generic over the caller's document
+ * element type so `document` / `rerankedDocuments` carry the original values
+ * (strings or objects), not their serialized form.
+ */
+export interface RerankResult<TDocument = string> {
+  id: string
+  model: string
+  /** Scored results, highest relevance first. */
+  ranking: Array<{ index: number; score: number; document: TDocument }>
+  /** The documents reordered by relevance — `ranking.map(r => r.document)`. */
+  rerankedDocuments: Array<TDocument>
+  /**
+   * Usage for the request. Rerank typically bills in provider-defined "search
+   * units" (`usage.unitsBilled`) rather than tokens. Some providers (e.g.
+   * OpenRouter) may also report `totalTokens` and `cost`; Cohere reports only
+   * search units and leaves the token counts at 0.
+   */
+  usage: TokenUsage
+}
+
 // ============================================================================
 // Image Generation Types
 // ============================================================================
@@ -2129,6 +2205,12 @@ export interface ImageGenerationOptions<
    * call logger.request() before the SDK call and logger.errors() in catch blocks.
    */
   logger: InternalLogger
+  /**
+   * Effective abort signal composed by the activity from caller `abortSignal`
+   * and/or `timeout`. Adapters should forward this to the provider SDK when
+   * supported. Request-specific — never store on a global client config.
+   */
+  abortSignal?: AbortSignal
 }
 
 /**
@@ -2242,6 +2324,12 @@ export interface AudioGenerationOptions<
    * catch blocks.
    */
   logger: InternalLogger
+  /**
+   * Effective abort signal composed by the activity from caller `abortSignal`
+   * and/or `timeout`. Adapters should forward this to the provider SDK when
+   * supported. Request-specific — never store on a global client config.
+   */
+  abortSignal?: AbortSignal
 }
 
 /**
@@ -2311,6 +2399,12 @@ export interface VideoGenerationOptions<
    * call logger.request() before the SDK call and logger.errors() in catch blocks.
    */
   logger: InternalLogger
+  /**
+   * Effective abort signal composed by the activity from caller `abortSignal`
+   * and/or `timeout`. Adapters should forward this to the provider SDK when
+   * supported. Request-specific — never store on a global client config.
+   */
+  abortSignal?: AbortSignal
 }
 
 /**
@@ -2396,6 +2490,12 @@ export interface TTSOptions<TProviderOptions extends object = object> {
    * catch blocks.
    */
   logger: InternalLogger
+  /**
+   * Effective abort signal composed by the activity from caller `abortSignal`
+   * and/or `timeout`. Adapters should forward this to the provider SDK when
+   * supported. Request-specific — never store on a global client config.
+   */
+  abortSignal?: AbortSignal
 }
 
 /**
@@ -2456,6 +2556,12 @@ export interface TranscriptionOptions<
    * in catch blocks.
    */
   logger: InternalLogger
+  /**
+   * Effective abort signal composed by the activity from caller `abortSignal`
+   * and/or `timeout`. Adapters should forward this to the provider SDK when
+   * supported. Request-specific — never store on a global client config.
+   */
+  abortSignal?: AbortSignal
 }
 
 /**
@@ -2512,6 +2618,119 @@ export interface TranscriptionResult {
   artifacts?: Array<PersistedArtifactRef>
 }
 
+// ============================================================================
+// Embedding Types
+// ============================================================================
+
+/**
+ * Input modalities an embedding model can accept. Unlike
+ * {@link MediaPromptModality}, `'text'` is listed explicitly because
+ * text-only embedding models are the common case and the modality list
+ * drives compile-time narrowing of {@link EmbeddingInputItem}.
+ */
+export type EmbeddingModality = 'text' | 'image'
+
+/**
+ * Per-model map from model name to the input modalities it accepts, used as
+ * an adapter type parameter (`TModelInputModalitiesByName`). Models absent
+ * from the map fall back to the unconstrained {@link EmbeddingInputItem}.
+ */
+export type EmbeddingModelInputModalitiesByName = Record<
+  string,
+  ReadonlyArray<EmbeddingModality>
+>
+
+/**
+ * A fused multi-part embedding item: all parts are embedded together into a
+ * single vector (e.g. a product photo plus its caption). Written as a nested
+ * array of content parts — the same `Array<ContentPart>` convention chat
+ * messages use — so a fused item is visually distinct from the top-level
+ * `input` list, where each element produces its own vector. Supported by
+ * multimodal embedding models such as Cohere embed-v4 and Amazon Titan
+ * Multimodal.
+ */
+export type EmbeddingContentParts = Array<TextPart | ImagePart>
+
+/**
+ * One embeddable item, producing exactly one vector. A bare string is
+ * shorthand for a text part; a nested {@link EmbeddingContentParts} array
+ * fuses its parts into a single vector. Note that a bare array at the top
+ * level of `input` is the *list of items* (one vector each) — fuse by
+ * nesting, e.g. `input: [[textPart, imagePart]]`.
+ */
+export type EmbeddingInputItem =
+  | string
+  | TextPart
+  | ImagePart
+  | EmbeddingContentParts
+
+/** Maps an embedding modality to the item types it admits. @internal */
+interface EmbeddingItemByModality {
+  text: TextPart
+  image: ImagePart | EmbeddingContentParts
+}
+
+/**
+ * Embedding item type narrowed to the modalities a specific model supports.
+ * `EmbeddingInputItemFor<'text'>` (a text-only model) is `string | TextPart`;
+ * `'text' | 'image'` additionally admits image parts and fused
+ * {@link EmbeddingContentParts} arrays. Used by the activity option types
+ * together with the adapter's per-model modality map so unsupported inputs
+ * fail at compile time.
+ */
+export type EmbeddingInputItemFor<
+  TModalities extends EmbeddingModality = EmbeddingModality,
+> = string | TextPart | EmbeddingItemByModality[TModalities]
+
+/**
+ * Options for embedding generation, as received by adapters. The `embed()`
+ * entry point normalizes a single input item to an array before calling the
+ * adapter, so `input` is always an array here.
+ */
+export interface EmbeddingOptions<TProviderOptions extends object = object> {
+  /** The model to use for embedding generation */
+  model: string
+  /** The items to embed — one vector per item */
+  input: Array<EmbeddingInputItem>
+  /**
+   * Requested output dimensionality. Adapters for models with fixed
+   * dimensions throw a clear runtime error when this is set.
+   */
+  dimensions?: number
+  /** Model-specific options for embedding generation */
+  modelOptions?: TProviderOptions
+  /**
+   * Internal logger threaded from the embed() entry point. Adapters must
+   * call logger.request() before the SDK call and logger.errors() in catch
+   * blocks.
+   */
+  logger: InternalLogger
+}
+
+/**
+ * A single embedding vector.
+ */
+export interface Embedding {
+  /** The embedding vector */
+  vector: Array<number>
+  /** Position of the source item in the (normalized) input array */
+  index: number
+}
+
+/**
+ * Result of embedding generation.
+ */
+export interface EmbeddingResult {
+  /** Unique identifier for the generation */
+  id: string
+  /** Model used for generation */
+  model: string
+  /** One embedding per input item, in input order */
+  embeddings: Array<Embedding>
+  /** Token usage information (if provided by the adapter) */
+  usage?: TokenUsage
+}
+
 /**
  * Default metadata type for adapters that don't define custom metadata.
  * Uses unknown for all modalities.

package/src/utilities/activity-abort.ts

@@ -0,0 +1,197 @@
+/**
+ * Shared abort/timeout composition for media (and summarize) activities.
+ *
+ * Callers pass optional `timeout` and/or `abortSignal` on activity options.
+ * Core composes them into one effective signal, races the adapter call so a
+ * hung provider still rejects, clears timeout resources on settle, and
+ * classifies aborts so lifecycle middleware gets `onAbort` rather than
+ * `onError`.
+ */
+
+const ABORT_ERROR_NAMES = new Set([
+  'AbortError',
+  'TimeoutError',
+  'APIUserAbortError',
+  'RequestAbortedError',
+])
+
+/**
+ * Combine two optional AbortSignals into one that aborts when either does.
+ * Returns the other signal directly when one is absent or already aborted.
+ * First abort wins and preserves its reason.
+ *
+ * Manual implementation — `AbortSignal.any` requires Node >= 20.3.
+ */
+export function combineAbortSignals(
+  a: AbortSignal | undefined,
+  b: AbortSignal | undefined,
+): AbortSignal | undefined {
+  if (!a) return b
+  if (!b) return a
+  if (a.aborted) return a
+  if (b.aborted) return b
+  const controller = new AbortController()
+  const onAbort = (source: AbortSignal) => () => {
+    controller.abort(source.reason)
+  }
+  a.addEventListener('abort', onAbort(a), { once: true })
+  b.addEventListener('abort', onAbort(b), { once: true })
+  return controller.signal
+}
+
+function createTimeoutReason(ms: number): Error {
+  if (typeof DOMException !== 'undefined') {
+    return new DOMException(`Activity timed out after ${ms}ms`, 'TimeoutError')
+  }
+  const err = new Error(`Activity timed out after ${ms}ms`)
+  err.name = 'TimeoutError'
+  return err
+}
+
+/** Normalize an abort reason into an Error the activity can reject with. */
+export function toAbortError(reason: unknown): Error {
+  if (reason instanceof Error) return reason
+  if (typeof reason === 'string' && reason.length > 0) {
+    const err = new Error(reason)
+    err.name = 'AbortError'
+    return err
+  }
+  const err = new Error('The operation was aborted')
+  err.name = 'AbortError'
+  return err
+}
+
+export interface ActivityAbortControls {
+  /** Effective signal, or `undefined` when neither timeout nor caller signal. */
+  signal: AbortSignal | undefined
+  /** Clear the timeout timer if one was set. Idempotent. */
+  clear: () => void
+}
+
+/**
+ * Compose an activity-level timeout with a caller AbortSignal.
+ *
+ * - No SDK-wide default timeout; omit both for unlimited wait.
+ * - First of caller cancellation or timeout wins and keeps its reason.
+ * - Call `clear()` when the activity settles (success or failure) so timers
+ *   do not leak.
+ */
+export function createActivityAbortControls(options: {
+  abortSignal?: AbortSignal
+  timeout?: number
+}): ActivityAbortControls {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined
+  let timeoutSignal: AbortSignal | undefined
+
+  if (options.timeout !== undefined) {
+    if (!Number.isFinite(options.timeout) || options.timeout < 0) {
+      throw new Error(
+        `Invalid activity timeout: expected a non-negative finite number, got ${String(options.timeout)}`,
+      )
+    }
+    const controller = new AbortController()
+    timeoutSignal = controller.signal
+    const ms = options.timeout
+    timeoutId = setTimeout(() => {
+      controller.abort(createTimeoutReason(ms))
+    }, ms)
+  }
+
+  const signal = combineAbortSignals(options.abortSignal, timeoutSignal)
+
+  return {
+    signal,
+    clear: () => {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId)
+        timeoutId = undefined
+      }
+    },
+  }
+}
+
+/**
+ * Reject when `signal` aborts, even if the underlying promise ignores it.
+ * Ensures activity-level timeouts work for adapters that do not yet forward
+ * the signal to the provider SDK.
+ *
+ * When the signal wins, the adapter promise is observed with an empty handler
+ * so a later settle cannot surface as an unhandled rejection.
+ */
+export function raceWithAbort<T>(
+  promise: Promise<T>,
+  signal: AbortSignal | undefined,
+): Promise<T> {
+  if (!signal) return promise
+
+  const swallow = () => {
+    // Observe the adapter promise without acting on its outcome so a late
+    // reject after we already aborted cannot become an unhandled rejection.
+    promise.then(
+      () => undefined,
+      () => undefined,
+    )
+  }
+
+  if (signal.aborted) {
+    swallow()
+    return Promise.reject(toAbortError(signal.reason))
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false
+    const onAbort = () => {
+      if (settled) return
+      settled = true
+      cleanup()
+      swallow()
+      reject(toAbortError(signal.reason))
+    }
+    const cleanup = () => {
+      signal.removeEventListener('abort', onAbort)
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (value) => {
+        if (settled) return
+        settled = true
+        cleanup()
+        resolve(value)
+      },
+      (error: unknown) => {
+        if (settled) return
+        settled = true
+        cleanup()
+        reject(error)
+      },
+    )
+  })
+}
+
+/**
+ * Whether a thrown value (and optional effective signal) should route to
+ * middleware `onAbort` instead of `onError`.
+ */
+export function isActivityAbortError(
+  error: unknown,
+  signal?: AbortSignal,
+): boolean {
+  if (signal?.aborted) return true
+  if (!error || typeof error !== 'object') return false
+  const name = (error as { name?: unknown }).name
+  return typeof name === 'string' && ABORT_ERROR_NAMES.has(name)
+}
+
+/** Best-effort string reason for {@link GenerationAbortInfo}. */
+export function abortReasonMessage(
+  error: unknown,
+  signal?: AbortSignal,
+): string | undefined {
+  if (signal?.reason !== undefined) {
+    if (typeof signal.reason === 'string') return signal.reason
+    if (signal.reason instanceof Error) return signal.reason.message
+  }
+  if (error instanceof Error) return error.message
+  if (typeof error === 'string') return error
+  return undefined
+}

package/src/utilities/embedding-input.ts

@@ -0,0 +1,83 @@
+import type { EmbeddingInputItem, ImagePart } from '../types'
+
+/**
+ * One embedding input item resolved into its text and image constituents.
+ * Produced by {@link resolveEmbeddingInput}; adapters map each entry onto
+ * one provider-native input (one vector per entry).
+ */
+export interface ResolvedEmbeddingItem {
+  /** Text contents of the item, in order (empty for image-only items) */
+  texts: Array<string>
+  /** Image parts of the item, in order (empty for text-only items) */
+  images: Array<ImagePart>
+}
+
+function resolveItem(item: EmbeddingInputItem): ResolvedEmbeddingItem {
+  if (typeof item === 'string') {
+    return { texts: [item], images: [] }
+  }
+  // A nested array is a fused item: its parts embed together into one vector.
+  if (Array.isArray(item)) {
+    const resolved: ResolvedEmbeddingItem = { texts: [], images: [] }
+    for (const part of item) {
+      if (part.type === 'text') {
+        resolved.texts.push(part.content)
+      } else {
+        resolved.images.push(part)
+      }
+    }
+    return resolved
+  }
+  if (item.type === 'text') {
+    return { texts: [item.content], images: [] }
+  }
+  return { texts: [], images: [item] }
+}
+
+/**
+ * Resolve each embedding input item into its text and image constituents,
+ * preserving input order (result[i] corresponds to input[i] and to the
+ * vector at index i).
+ */
+export function resolveEmbeddingInput(
+  input: Array<EmbeddingInputItem>,
+): Array<ResolvedEmbeddingItem> {
+  return input.map(resolveItem)
+}
+
+/**
+ * Extract plain text inputs for a text-only embedding model, throwing a
+ * uniform error if any item carries an image. The per-model modality typing
+ * rejects these at compile time; this guard covers untyped/dynamic callers.
+ */
+export function requireTextOnlyEmbeddingInput(
+  input: Array<EmbeddingInputItem>,
+  provider: string,
+  model: string,
+): Array<string> {
+  return resolveEmbeddingInput(input).map((item, index) => {
+    if (item.images.length > 0) {
+      throw new Error(
+        `${provider} model "${model}" only supports text embedding inputs; ` +
+          `input item at index ${index} contains an image part`,
+      )
+    }
+    return item.texts.join('\n')
+  })
+}
+
+/**
+ * Count text-only and image-carrying items for observability events. Never
+ * exposes input content.
+ */
+export function countEmbeddingInputModalities(
+  input: Array<EmbeddingInputItem>,
+): { textInputCount: number; imageInputCount: number } {
+  let textInputCount = 0
+  let imageInputCount = 0
+  for (const item of resolveEmbeddingInput(input)) {
+    if (item.images.length > 0) imageInputCount++
+    else textInputCount++
+  }
+  return { textInputCount, imageInputCount }
+}