@tanstack/ai 0.43.1 → 0.44.1

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.1",
   "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/skills/ai-core/media-generation/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Image, audio, video, speech (TTS), and transcription generation using
   activity-specific adapters: generateImage() with openaiImage/geminiImage/byteplusImage,
   generateAudio() with geminiAudio/falAudio, generateVideo() with async
-  polling (openaiVideo/geminiVideo/grokVideo/falVideo/byteplusVideo, per-model typed
-  durations), generateSpeech() with openaiSpeech/byteplusSpeech, generateTranscription()
-  with openaiTranscription/byteplusTranscription. React hooks: useGenerateImage, useGenerateAudio,
+  polling (openaiVideo/geminiVideo/grokVideo/falVideo/byteplusVideo/openRouterVideo,
+  per-model typed durations), generateSpeech() with openaiSpeech/byteplusSpeech,
+  generateTranscription() with openaiTranscription/byteplusTranscription. React hooks:
+  useGenerateImage, useGenerateAudio,
   useGenerateSpeech, useTranscription, useGenerateVideo.
   TanStack Start server function integration with toServerSentEventsResponse.
 type: sub-skill
@@ -251,7 +252,8 @@ await generateImage({
   ],
 })
 
-// Image-to-video (OpenAI Sora: single input_reference; fal: image_url + optional end_image_url)
+// Image-to-video (OpenAI Sora: single input_reference; fal: image_url + optional
+// end_image_url; OpenRouter: frame_images + input_references)
 import { generateVideo } from '@tanstack/ai'
 import { falVideo } from '@tanstack/ai-fal'
 
@@ -282,25 +284,25 @@ with `allowUrlFetch: true` on the adapter config
 
 **Role hints** (`metadata.role`):
 
-| Role            | Maps to                                                                                               |
-| --------------- | ----------------------------------------------------------------------------------------------------- |
-| `'reference'`   | fal `reference_image_urls`; Gemini multimodal part; positional otherwise                              |
-| `'character'`   | Same as `'reference'`; Veo `referenceImages` slot (planned — no Veo adapter yet)                      |
-| `'mask'`        | OpenAI `mask` (gpt-image-2, gpt-image-1, dall-e-2); fal `mask_url`                                    |
-| `'control'`     | fal `control_image_url` (ControlNet / depth / pose)                                                   |
-| `'start_frame'` | fal `start_image_url` (or the endpoint's field, e.g. `image_url` on Kling i2v); Veo `image` (planned) |
-| `'end_frame'`   | fal `end_image_url` (or e.g. `tail_image_url` / `last_frame_url`); Veo `lastFrame` (planned)          |
+| Role            | Maps to                                                                                                                                |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `'reference'`   | fal `reference_image_urls`; OpenRouter video `input_references[]`; Gemini multimodal part; positional otherwise                        |
+| `'character'`   | Same as `'reference'`; Veo `referenceImages`; OpenRouter `input_references[]`                                                          |
+| `'mask'`        | OpenAI `mask` (gpt-image-2, gpt-image-1, dall-e-2); fal `mask_url`                                                                     |
+| `'control'`     | fal `control_image_url` (ControlNet / depth / pose)                                                                                    |
+| `'start_frame'` | fal `start_image_url` (or the endpoint's field, e.g. `image_url` on Kling i2v); OpenRouter `frame_images[]` `first_frame`; Veo `image` |
+| `'end_frame'`   | fal `end_image_url` (or e.g. `tail_image_url` / `last_frame_url`); OpenRouter `frame_images[]` `last_frame`; Veo `lastFrame`           |
 
 **Provider support matrix:**
 
-| Provider   | `generateImage` image parts                                                                                                                                                                              | `generateVideo` image parts                                                                                                                                                                        |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| OpenAI     | gpt-image-2 / gpt-image-1 / -mini → `images.edit()` (up to 16). dall-e-2 → edit (1). dall-e-3 throws.                                                                                                    | Sora-2 / -pro → `input_reference` (single). Throws if >1.                                                                                                                                          |
-| Gemini     | Native (gemini-\*-flash-image, "nano-banana") → multimodal `contents`. Imagen throws.                                                                                                                    | No native Veo adapter yet — deferred to a follow-up.                                                                                                                                               |
-| fal        | Per-endpoint field names from a generated map (`pnpm generate:fal-image-fields`). Defaults: 1 input → `image_url`; >1 → `image_urls`; roles → `mask_url` / `control_image_url` / `reference_image_urls`. | Per-endpoint map (e.g. Kling i2v start frame → `image_url`). Defaults: 1 input → `image_url`; `start_frame`/`end_frame` → `start_image_url`/`end_image_url`; `reference` → `reference_image_urls`. |
-| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw). grok-2-image-1212 throws.                              | n/a                                                                                                                                                                                                |
-| OpenRouter | Prompt parts map 1:1 onto multimodal `text` / `image_url` content parts, preserving interleaved order.                                                                                                   | n/a                                                                                                                                                                                                |
-| Anthropic  | n/a (no image generation API).                                                                                                                                                                           | n/a                                                                                                                                                                                                |
+| Provider   | `generateImage` image parts                                                                                                                                                                              | `generateVideo` image parts                                                                                                                                                                                                                                                                    |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI     | gpt-image-2 / gpt-image-1 / -mini → `images.edit()` (up to 16). dall-e-2 → edit (1). dall-e-3 throws.                                                                                                    | Sora-2 / -pro → `input_reference` (single). Throws if >1.                                                                                                                                                                                                                                      |
+| Gemini     | Native (gemini-\*-flash-image, "nano-banana") → multimodal `contents`. Imagen throws.                                                                                                                    | Veo → first un-roled / `'start_frame'` image is the input image; `'end_frame'` → `lastFrame`; `'reference'` / `'character'` → `referenceImages`. Omni Flash sends image/video parts as interaction content blocks (no role routing).                                                           |
+| fal        | Per-endpoint field names from a generated map (`pnpm generate:fal-image-fields`). Defaults: 1 input → `image_url`; >1 → `image_urls`; roles → `mask_url` / `control_image_url` / `reference_image_urls`. | Per-endpoint map (e.g. Kling i2v start frame → `image_url`). Defaults: 1 input → `image_url`; `start_frame`/`end_frame` → `start_image_url`/`end_image_url`; `reference` → `reference_image_urls`.                                                                                             |
+| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw). grok-2-image-1212 throws.                              | n/a                                                                                                                                                                                                                                                                                            |
+| OpenRouter | Prompt parts map 1:1 onto multimodal `text` / `image_url` content parts, preserving interleaved order.                                                                                                   | Dedicated async API (`openRouterVideo`): `start_frame`/`end_frame` → `frame_images[]` (`first_frame`/`last_frame`); `reference`/`character` → `input_references[]`; an unroled image defaults to the start frame. Frame roles validated against the model's `supported_frame_images` metadata. |
+| Anthropic  | n/a (no image generation API).                                                                                                                                                                           | n/a                                                                                                                                                                                                                                                                                            |
 
 Video and audio prompt parts follow the same `metadata.role` convention
 for video-to-video and lipsync flows on fal; other providers throw when
@@ -445,7 +447,13 @@ const { generate, result, isLoading } = useTranscription({
 ### 5. Video Generation (Experimental -- async polling)
 
 Video generation uses a jobs/polling architecture. The server creates a job,
-polls for status, and streams updates to the client.
+polls for status, and streams updates to the client. Adapters: `openaiVideo`
+(Sora), `geminiVideo` (Veo / Omni Flash), `grokVideo`, `byteplusVideo`
+(Seedance), `falVideo` (Kling, MiniMax, Hunyuan, …), and `openRouterVideo`
+(OpenRouter's dedicated `POST /api/v1/videos` gateway — Seedance, Veo, Wan,
+Kling, Sora 2 Pro and others through one API key; `getVideoJobStatus()`
+returns the video as a `data:` URL since OpenRouter's download URLs require
+the API key, and surfaces the gateway-reported cost as `usage.cost`).
 
 ```typescript
 import {
@@ -541,8 +549,9 @@ image-to-video only — needs an `image` prompt part as the starting frame, text
 aspect-ratio size template like `'16:9_720p'`, integer durations 1-15s, reports
 `usage.unitsBilled` seconds and exact `usage.cost`), `byteplusVideo(...)` (Seedance —
 aspect-ratio size template like `'16:9_720p'`, durations 4-15s on the 2.0 family,
-4-12s on 1.5-pro, 2-12s on the 1.0-pro models; reads `ARK_API_KEY`), and
-`falVideo(...)` (hosted models, see cost tracking below).
+4-12s on 1.5-pro, 2-12s on the 1.0-pro models; reads `ARK_API_KEY`),
+`openRouterVideo(...)` (OpenRouter's dedicated `POST /api/v1/videos` gateway),
+and `falVideo(...)` (hosted models, see cost tracking below).
 
 > **Seedance option applicability is per model and enforced server-side** —
 > Ark returns a 400 for an inapplicable field rather than ignoring it.
@@ -554,6 +563,29 @@ aspect-ratio size template like `'16:9_720p'`, durations 4-15s on the 2.0 family
 > days). Seedance is also reachable via `falVideo` — `byteplusVideo` is the
 > direct-to-BytePlus path.
 
+OpenRouter (`@tanstack/ai-openrouter`, `openRouterVideo`) runs the dedicated
+async video API (`POST /api/v1/videos`) and shares the same typed-duration
+contract — `duration`, `size`, and provider options are narrowed per model
+from OpenRouter's published metadata, with the same `availableDurations()` /
+`snapDuration()` helpers:
+
+```typescript
+import { openRouterVideo } from '@tanstack/ai-openrouter'
+
+const adapter = openRouterVideo('bytedance/seedance-2.0')
+adapter.availableDurations()
+// { kind: 'discrete', values: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] }
+adapter.snapDuration(7.4) // 7
+
+const sliderSeconds = 7 // raw seconds from a UI control
+const { jobId } = await generateVideo({
+  adapter,
+  prompt: 'A timelapse of clouds',
+  duration: adapter.snapDuration(sliderSeconds),
+})
+// Completed url is a data: URL; usage.cost carries the real billed cost.
+```
+
 Client hook with job tracking:
 
 ```tsx

package/src/activities/chat/index.ts

@@ -729,6 +729,8 @@ class TextEngine<
   private streamStartTime = 0
   private totalChunkCount = 0
   private currentMessageId: string | null = null
+  private currentMessageCreatedAt: Date | null = null
+  private streamIdentityCaptured = false
   private accumulatedContent = ''
   private accumulatedThinking: Array<{ content: string; signature?: string }> =
     []
@@ -1268,6 +1270,8 @@ class TextEngine<
 
   private async beginIteration(): Promise<void> {
     this.currentMessageId = this.createId('msg')
+    this.currentMessageCreatedAt = new Date()
+    this.streamIdentityCaptured = false
     this.accumulatedContent = ''
     this.accumulatedThinking = []
     this.currentThinkingContent = ''
@@ -1455,6 +1459,11 @@ class TextEngine<
     // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType enum members vs string-literal case labels; default branch handles untraced events.
     switch (chunk.type) {
       // AG-UI Events
+      case 'TEXT_MESSAGE_START':
+        if (typeof chunk.messageId === 'string' && chunk.messageId !== '') {
+          this.captureStreamMessageIdentity(chunk.messageId)
+        }
+        break
       case 'TEXT_MESSAGE_CONTENT':
         this.handleTextMessageContentEvent(chunk)
         break
@@ -1493,8 +1502,7 @@ class TextEngine<
         break
 
       default:
-        // RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_END,
-        // STATE_SNAPSHOT, STATE_DELTA, CUSTOM
+        // RUN_STARTED, TEXT_MESSAGE_END, STATE_SNAPSHOT, STATE_DELTA, CUSTOM
         // - no special handling needed in chat activity
         break
     }
@@ -1513,7 +1521,22 @@ class TextEngine<
     this.middlewareCtx.accumulatedContent = this.accumulatedContent
   }
 
+  private captureStreamMessageIdentity(messageId: string): void {
+    this.currentMessageId = messageId
+    this.middlewareCtx.currentMessageId = messageId
+    if (!this.streamIdentityCaptured) {
+      this.currentMessageCreatedAt = new Date()
+      this.streamIdentityCaptured = true
+    }
+  }
+
   private handleToolCallStartEvent(chunk: ToolCallStartEvent): void {
+    if (
+      typeof chunk.parentMessageId === 'string' &&
+      chunk.parentMessageId !== ''
+    ) {
+      this.captureStreamMessageIdentity(chunk.parentMessageId)
+    }
     this.toolCallManager.addToolCallStartEvent(chunk)
   }
 
@@ -1954,6 +1977,8 @@ class TextEngine<
         role: 'assistant',
         content: this.accumulatedContent || null,
         toolCalls,
+        id: this.currentMessageId ?? undefined,
+        createdAt: this.currentMessageCreatedAt ?? undefined,
         ...(this.accumulatedThinking.length > 0 && {
           thinking: this.accumulatedThinking,
         }),