@tanstack/ai 0.43.1 → 0.44.0

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.1",
+  "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"

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)}`
+  }
+}