@tanstack/ai 0.43.0 → 0.44.0

package/dist/esm/types.d.ts

@@ -259,6 +259,11 @@ export interface ModelMessage<TContent extends string | null | Array<ContentPart
      * 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;
 }
 /**
  * Message parts - building blocks of UIMessage
@@ -1656,6 +1661,12 @@ export interface SummarizationOptions<TProviderOptions extends object = Record<s
      * 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 {
     id: string;
@@ -1663,6 +1674,69 @@ export interface SummarizationResult {
     summary: string;
     usage: TokenUsage;
 }
+/**
+ * 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;
+}
 /**
  * Optional role hint on a media input part (image / video / audio). Adapters
  * read `metadata.role` to route the part to the provider-specific request
@@ -1761,6 +1835,12 @@ export interface ImageGenerationOptions<TProviderOptions extends object = object
      * 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;
 }
 /**
  * Source of a generated media asset. Exactly one of `url` or `b64Json` is
@@ -1854,6 +1934,12 @@ export interface AudioGenerationOptions<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;
 }
 /**
  * A single generated audio output
@@ -1912,6 +1998,12 @@ export interface VideoGenerationOptions<TProviderOptions extends object = object
      * 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;
 }
 /**
  * Result of creating a video generation job.
@@ -1989,6 +2081,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;
 }
 /**
  * Result of text-to-speech generation.
@@ -2035,6 +2133,12 @@ export interface TranscriptionOptions<TProviderOptions extends object = object>
      * 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;
 }
 /**
  * A single segment of transcribed audio with timing information.
@@ -2087,6 +2191,97 @@ export interface TranscriptionResult {
     /** Persisted artifact references for generated assets, when available */
     artifacts?: Array<PersistedArtifactRef>;
 }
+/**
+ * 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/dist/esm/utilities/activity-abort.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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`.
+ */
+/**
+ * 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 declare function combineAbortSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined;
+/** Normalize an abort reason into an Error the activity can reject with. */
+export declare function toAbortError(reason: unknown): Error;
+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 declare function createActivityAbortControls(options: {
+    abortSignal?: AbortSignal;
+    timeout?: number;
+}): ActivityAbortControls;
+/**
+ * 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 declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+/**
+ * Whether a thrown value (and optional effective signal) should route to
+ * middleware `onAbort` instead of `onError`.
+ */
+export declare function isActivityAbortError(error: unknown, signal?: AbortSignal): boolean;
+/** Best-effort string reason for {@link GenerationAbortInfo}. */
+export declare function abortReasonMessage(error: unknown, signal?: AbortSignal): string | undefined;

package/dist/esm/utilities/activity-abort.js

@@ -0,0 +1,150 @@
+//#region src/utilities/activity-abort.ts
+/**
+* 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`.
+*/
+var ABORT_ERROR_NAMES = /* @__PURE__ */ 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.
+*/
+function combineAbortSignals(a, b) {
+	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) => () => {
+		controller.abort(source.reason);
+	};
+	a.addEventListener("abort", onAbort(a), { once: true });
+	b.addEventListener("abort", onAbort(b), { once: true });
+	return controller.signal;
+}
+function createTimeoutReason(ms) {
+	if (typeof DOMException !== "undefined") return new DOMException(`Activity timed out after ${ms}ms`, "TimeoutError");
+	const err = /* @__PURE__ */ 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. */
+function toAbortError(reason) {
+	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 = /* @__PURE__ */ new Error("The operation was aborted");
+	err.name = "AbortError";
+	return err;
+}
+/**
+* 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.
+*/
+function createActivityAbortControls(options) {
+	let timeoutId;
+	let timeoutSignal;
+	if (options.timeout !== void 0) {
+		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);
+	}
+	return {
+		signal: combineAbortSignals(options.abortSignal, timeoutSignal),
+		clear: () => {
+			if (timeoutId !== void 0) {
+				clearTimeout(timeoutId);
+				timeoutId = void 0;
+			}
+		}
+	};
+}
+/**
+* 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.
+*/
+function raceWithAbort(promise, signal) {
+	if (!signal) return promise;
+	const swallow = () => {
+		promise.then(() => void 0, () => void 0);
+	};
+	if (signal.aborted) {
+		swallow();
+		return Promise.reject(toAbortError(signal.reason));
+	}
+	return new Promise((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) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
+		});
+	});
+}
+/**
+* Whether a thrown value (and optional effective signal) should route to
+* middleware `onAbort` instead of `onError`.
+*/
+function isActivityAbortError(error, signal) {
+	if (signal?.aborted) return true;
+	if (!error || typeof error !== "object") return false;
+	const name = error.name;
+	return typeof name === "string" && ABORT_ERROR_NAMES.has(name);
+}
+/** Best-effort string reason for {@link GenerationAbortInfo}. */
+function abortReasonMessage(error, signal) {
+	if (signal?.reason !== void 0) {
+		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;
+}
+//#endregion
+export { abortReasonMessage, combineAbortSignals, createActivityAbortControls, isActivityAbortError, raceWithAbort, toAbortError };
+
+//# sourceMappingURL=activity-abort.js.map

package/dist/esm/utilities/activity-abort.js.map

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

package/dist/esm/utilities/embedding-input.d.ts

@@ -0,0 +1,32 @@
+import { EmbeddingInputItem, ImagePart } from '../types.js';
+/**
+ * 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>;
+}
+/**
+ * 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 declare function resolveEmbeddingInput(input: Array<EmbeddingInputItem>): Array<ResolvedEmbeddingItem>;
+/**
+ * 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 declare function requireTextOnlyEmbeddingInput(input: Array<EmbeddingInputItem>, provider: string, model: string): Array<string>;
+/**
+ * Count text-only and image-carrying items for observability events. Never
+ * exposes input content.
+ */
+export declare function countEmbeddingInputModalities(input: Array<EmbeddingInputItem>): {
+    textInputCount: number;
+    imageInputCount: number;
+};

package/dist/esm/utilities/embedding-input.js

@@ -0,0 +1,61 @@
+//#region src/utilities/embedding-input.ts
+function resolveItem(item) {
+	if (typeof item === "string") return {
+		texts: [item],
+		images: []
+	};
+	if (Array.isArray(item)) {
+		const resolved = {
+			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).
+*/
+function resolveEmbeddingInput(input) {
+	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.
+*/
+function requireTextOnlyEmbeddingInput(input, provider, model) {
+	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.
+*/
+function countEmbeddingInputModalities(input) {
+	let textInputCount = 0;
+	let imageInputCount = 0;
+	for (const item of resolveEmbeddingInput(input)) if (item.images.length > 0) imageInputCount++;
+	else textInputCount++;
+	return {
+		textInputCount,
+		imageInputCount
+	};
+}
+//#endregion
+export { countEmbeddingInputModalities, requireTextOnlyEmbeddingInput, resolveEmbeddingInput };
+
+//# sourceMappingURL=embedding-input.js.map

package/dist/esm/utilities/embedding-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-input.js","names":[],"sources":["../../../src/utilities/embedding-input.ts"],"sourcesContent":["import type { EmbeddingInputItem, ImagePart } from '../types'\n\n/**\n * One embedding input item resolved into its text and image constituents.\n * Produced by {@link resolveEmbeddingInput}; adapters map each entry onto\n * one provider-native input (one vector per entry).\n */\nexport interface ResolvedEmbeddingItem {\n  /** Text contents of the item, in order (empty for image-only items) */\n  texts: Array<string>\n  /** Image parts of the item, in order (empty for text-only items) */\n  images: Array<ImagePart>\n}\n\nfunction resolveItem(item: EmbeddingInputItem): ResolvedEmbeddingItem {\n  if (typeof item === 'string') {\n    return { texts: [item], images: [] }\n  }\n  // A nested array is a fused item: its parts embed together into one vector.\n  if (Array.isArray(item)) {\n    const resolved: ResolvedEmbeddingItem = { texts: [], images: [] }\n    for (const part of item) {\n      if (part.type === 'text') {\n        resolved.texts.push(part.content)\n      } else {\n        resolved.images.push(part)\n      }\n    }\n    return resolved\n  }\n  if (item.type === 'text') {\n    return { texts: [item.content], images: [] }\n  }\n  return { texts: [], images: [item] }\n}\n\n/**\n * Resolve each embedding input item into its text and image constituents,\n * preserving input order (result[i] corresponds to input[i] and to the\n * vector at index i).\n */\nexport function resolveEmbeddingInput(\n  input: Array<EmbeddingInputItem>,\n): Array<ResolvedEmbeddingItem> {\n  return input.map(resolveItem)\n}\n\n/**\n * Extract plain text inputs for a text-only embedding model, throwing a\n * uniform error if any item carries an image. The per-model modality typing\n * rejects these at compile time; this guard covers untyped/dynamic callers.\n */\nexport function requireTextOnlyEmbeddingInput(\n  input: Array<EmbeddingInputItem>,\n  provider: string,\n  model: string,\n): Array<string> {\n  return resolveEmbeddingInput(input).map((item, index) => {\n    if (item.images.length > 0) {\n      throw new Error(\n        `${provider} model \"${model}\" only supports text embedding inputs; ` +\n          `input item at index ${index} contains an image part`,\n      )\n    }\n    return item.texts.join('\\n')\n  })\n}\n\n/**\n * Count text-only and image-carrying items for observability events. Never\n * exposes input content.\n */\nexport function countEmbeddingInputModalities(\n  input: Array<EmbeddingInputItem>,\n): { textInputCount: number; imageInputCount: number } {\n  let textInputCount = 0\n  let imageInputCount = 0\n  for (const item of resolveEmbeddingInput(input)) {\n    if (item.images.length > 0) imageInputCount++\n    else textInputCount++\n  }\n  return { textInputCount, imageInputCount }\n}\n"],"mappings":";AAcA,SAAS,YAAY,MAAiD;CACpE,IAAI,OAAO,SAAS,UAClB,OAAO;EAAE,OAAO,CAAC,IAAI;EAAG,QAAQ,CAAC;CAAE;CAGrC,IAAI,MAAM,QAAQ,IAAI,GAAG;EACvB,MAAM,WAAkC;GAAE,OAAO,CAAC;GAAG,QAAQ,CAAC;EAAE;EAChE,KAAK,MAAM,QAAQ,MACjB,IAAI,KAAK,SAAS,QAChB,SAAS,MAAM,KAAK,KAAK,OAAO;OAEhC,SAAS,OAAO,KAAK,IAAI;EAG7B,OAAO;CACT;CACA,IAAI,KAAK,SAAS,QAChB,OAAO;EAAE,OAAO,CAAC,KAAK,OAAO;EAAG,QAAQ,CAAC;CAAE;CAE7C,OAAO;EAAE,OAAO,CAAC;EAAG,QAAQ,CAAC,IAAI;CAAE;AACrC;;;;;;AAOA,SAAgB,sBACd,OAC8B;CAC9B,OAAO,MAAM,IAAI,WAAW;AAC9B;;;;;;AAOA,SAAgB,8BACd,OACA,UACA,OACe;CACf,OAAO,sBAAsB,KAAK,CAAC,CAAC,KAAK,MAAM,UAAU;EACvD,IAAI,KAAK,OAAO,SAAS,GACvB,MAAM,IAAI,MACR,GAAG,SAAS,UAAU,MAAM,6DACH,MAAM,wBACjC;EAEF,OAAO,KAAK,MAAM,KAAK,IAAI;CAC7B,CAAC;AACH;;;;;AAMA,SAAgB,8BACd,OACqD;CACrD,IAAI,iBAAiB;CACrB,IAAI,kBAAkB;CACtB,KAAK,MAAM,QAAQ,sBAAsB,KAAK,GAC5C,IAAI,KAAK,OAAO,SAAS,GAAG;MACvB;CAEP,OAAO;EAAE;EAAgB;CAAgB;AAC3C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -80,8 +80,8 @@
     "@ag-ui/core": "0.1.1-canary.beta.0",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.7.0",
-    "@tanstack/ai-utils": "0.4.0"
+    "@tanstack/ai-event-client": "^0.8.0",
+    "@tanstack/ai-utils": "^0.4.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"