ai 6.0.220 → 6.0.222

package/dist/internal/index.js

@@ -152,7 +152,7 @@ function detectMediaType({
 var import_provider_utils2 = require("@ai-sdk/provider-utils");
 
 // src/version.ts
-var VERSION = true ? "6.0.220" : "0.0.0-test";
+var VERSION = true ? "6.0.222" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/dist/internal/index.mjs

@@ -132,7 +132,7 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/version.ts
-var VERSION = true ? "6.0.220" : "0.0.0-test";
+var VERSION = true ? "6.0.222" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/docs/02-foundations/02-providers-and-models.mdx

@@ -111,10 +111,15 @@ Here are the capabilities of popular models:
 
 | Provider                                           | Model                                       | Image Input         | Object Generation   | Tool Usage          | Tool Streaming      |
 | -------------------------------------------------- | ------------------------------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| [xAI Grok](/providers/ai-sdk-providers/xai)        | `grok-4.5`                                  | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | [xAI Grok](/providers/ai-sdk-providers/xai)        | `grok-4`                                    | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | [xAI Grok](/providers/ai-sdk-providers/xai)        | `grok-3`                                    | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | [xAI Grok](/providers/ai-sdk-providers/xai)        | `grok-3-mini`                               | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | [Vercel](/providers/ai-sdk-providers/vercel)       | `v0-1.0-md`                                 | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.6`                                   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.6-luna`                              | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.6-sol`                               | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.6-terra`                             | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.5`                                   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.4-pro`                               | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.4`                                   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |

package/docs/03-ai-sdk-core/38-video-generation.mdx

@@ -37,7 +37,7 @@ const uint8Array = video.uint8Array; // Uint8Array video data
 The aspect ratio is specified as a string in the format `{width}:{height}`.
 Models only support a few aspect ratios, and the supported aspect ratios are different for each model and provider.
 
-```tsx highlight={"7"}
+```tsx highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -53,7 +53,7 @@ const { video } = await generateVideo({
 The resolution is specified as a string in the format `{width}x{height}`.
 Models only support specific resolutions, and the supported resolutions are different for each model and provider.
 
-```tsx highlight={"7"}
+```tsx highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -68,7 +68,7 @@ const { video } = await generateVideo({
 
 Some video models support specifying the duration of the generated video in seconds.
 
-```tsx highlight={"7"}
+```tsx highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -83,7 +83,7 @@ const { video } = await generateVideo({
 
 Some video models allow you to specify the frames per second for the generated video.
 
-```tsx highlight={"7"}
+```tsx highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -98,7 +98,7 @@ const { video } = await generateVideo({
 
 Some video models can generate audio alongside the video. Use the `generateAudio` option to control this:
 
-```tsx highlight={"7"}
+```tsx highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -113,7 +113,7 @@ const { video } = await generateVideo({
 
 `experimental_generateVideo` supports generating multiple videos at once:
 
-```tsx highlight={"7"}
+```tsx highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -146,7 +146,7 @@ const { videos } = await generateVideo({
 
 Some video models support generating videos from an input image. You can provide an image using the prompt object:
 
-```tsx highlight={"7-10"}
+```tsx highlight={"5-7"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -177,7 +177,7 @@ Some video models support first-last-frame generation, where you provide the
 starting and/or ending frames of the video. Use the `frameImages` option to pass
 role-tagged images in a provider-agnostic way:
 
-```tsx highlight={"5-16"}
+```tsx highlight={"4-13"}
 const { video } = await generateVideo({
   model: __VIDEO_MODEL__,
   prompt: 'The cat walks across the scene and transforms into a dog by the end',
@@ -194,13 +194,13 @@ const { video } = await generateVideo({
 });
 ```
 
-### Reference Images
+### Reference Inputs
 
 Some video models support reference-to-video generation, where you provide one or
-more reference images that the model incorporates into the generated video. Use the `inputReferences` option to pass
-these images in a provider-agnostic way:
+more reference images or videos that the model incorporates into the generated video. Use the `inputReferences` option to pass
+these inputs in a provider-agnostic way:
 
-```tsx highlight={"5-8"}
+```tsx highlight={"4-7"}
 const { video } = await generateVideo({
   model: __VIDEO_MODEL__,
   prompt: 'The two characters meet in a bustling market',
@@ -211,12 +211,31 @@ const { video } = await generateVideo({
 });
 ```
 
+For URL-based video references, use the object form with an explicit `mediaType`:
+
+```tsx highlight={"4-9"}
+const { video } = await generateVideo({
+  model: __VIDEO_MODEL__,
+  prompt: 'Match the motion in the reference clip',
+  inputReferences: [
+    {
+      data: 'https://example.com/reference.mp4',
+      mediaType: 'video/mp4',
+    },
+  ],
+});
+```
+
+Providers route each reference by its media type (image vs. video) and emit a
+warning when a reference kind is unsupported (for example, providers that accept
+only image references warn and ignore a video reference).
+
 ### Providing a Seed
 
 You can provide a seed to the `experimental_generateVideo` function to control the output of the video generation process.
 If supported by the model, the same seed will always produce the same video.
 
-```tsx highlight={"7"}
+```tsx highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -254,7 +273,7 @@ const { video } = await generateVideo({
 type [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
 that you can use to abort the video generation process or set a timeout.
 
-```ts highlight={"7"}
+```ts highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 
@@ -276,7 +295,7 @@ Video generation is an asynchronous process that can take several minutes to com
 
 You can configure the polling timeout using provider-specific options. Each provider exports a type for its options that you can use with `satisfies` for type safety:
 
-```tsx highlight={"10-12"}
+```tsx highlight={"9-11"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 import { fal, type FalVideoModelOptions } from '@ai-sdk/fal';
 
@@ -303,7 +322,7 @@ const { video } = await generateVideo({
 `experimental_generateVideo` accepts an optional `headers` parameter of type `Record<string, string>`
 that you can use to add custom headers to the video generation request.
 
-```ts highlight={"7"}
+```ts highlight={"6"}
 import { experimental_generateVideo as generateVideo } from 'ai';
 __PROVIDER_IMPORT__;
 

package/docs/07-reference/01-ai-sdk-core/13-generate-video.mdx

@@ -118,9 +118,10 @@ console.log(videos);
     },
     {
       name: 'inputReferences',
-      type: 'Array<DataContent>',
+      type: 'Array<DataContent | { data: DataContent; mediaType?: string }>',
       isOptional: true,
-      description: 'Reference image inputs for reference-to-video generation.',
+      description:
+        'Reference image or video inputs for reference-to-video generation. Use the object form with an explicit mediaType for URL-based video references. Providers route each reference by its media type and warn when a reference kind is unsupported.',
     },
     {
       name: 'generateAudio',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "6.0.220",
+  "version": "6.0.222",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -45,9 +45,9 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@ai-sdk/gateway": "3.0.144",
-    "@ai-sdk/provider": "3.0.13",
-    "@ai-sdk/provider-utils": "4.0.36"
+    "@ai-sdk/gateway": "3.0.146",
+    "@ai-sdk/provider": "3.0.14",
+    "@ai-sdk/provider-utils": "4.0.38"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",

package/src/generate-text/generate-text.ts

@@ -52,6 +52,7 @@ import { asArray } from '../util/as-array';
 import type { DownloadFunction } from '../util/download/download-function';
 import { mergeObjects } from '../util/merge-objects';
 import { prepareRetries } from '../util/prepare-retries';
+import { setAbortTimeout } from '../util/set-abort-timeout';
 import { VERSION } from '../version';
 import type {
   OnFinishEvent,
@@ -684,10 +685,11 @@ export async function generateText<
 
         do {
           // Set up step timeout if configured
-          const stepTimeoutId =
-            stepTimeoutMs != null
-              ? setTimeout(() => stepAbortController!.abort(), stepTimeoutMs)
-              : undefined;
+          const stepTimeoutId = setAbortTimeout({
+            abortController: stepAbortController,
+            label: 'Step',
+            timeoutMs: stepTimeoutMs,
+          });
 
           try {
             const stepInputMessages = [...initialMessages, ...responseMessages];

package/src/generate-text/output.ts

@@ -278,6 +278,7 @@ export const array = <ELEMENT>({
         });
       }
 
+      const validatedElements: Array<ELEMENT> = [];
       for (const element of outerValue.elements) {
         const validationResult = await safeValidateTypes({
           value: element,
@@ -294,9 +295,11 @@ export const array = <ELEMENT>({
             finishReason: context.finishReason,
           });
         }
+
+        validatedElements.push(validationResult.value);
       }
 
-      return outerValue.elements as Array<ELEMENT>;
+      return validatedElements;
     },
 
     async parsePartialOutput({ text }: { text: string }) {

package/src/generate-text/run-tools-transformation.ts

@@ -171,10 +171,8 @@ export function runToolsTransformation<TOOLS extends ToolSet>({
   // keep track of outstanding tool results for stream closing:
   const outstandingToolResults = new Set<string>();
 
-  // keep track of tool inputs for provider-side tool results
-  const toolInputs = new Map<string, unknown>();
-
   // keep track of parsed tool calls so provider-emitted approval requests can reference them
+  // keep track of tool inputs for provider-side tool results
   const toolCallsByToolCallId = new Map<string, TypedToolCall<TOOLS>>();
 
   let canClose = false;
@@ -349,8 +347,6 @@ export function runToolsTransformation<TOOLS extends ToolSet>({
               break;
             }
 
-            toolInputs.set(toolCall.toolCallId, toolCall.input);
-
             // Only execute tools that are not provider-executed:
             if (tool.execute != null && toolCall.providerExecuted !== true) {
               const toolExecutionId = generateId(); // use our own id to guarantee uniqueness
@@ -405,7 +401,7 @@ export function runToolsTransformation<TOOLS extends ToolSet>({
               type: 'tool-error',
               toolCallId: chunk.toolCallId,
               toolName,
-              input: toolInputs.get(chunk.toolCallId),
+              input: toolCall?.input,
               providerExecuted: true,
               error: chunk.result,
               dynamic: chunk.dynamic,
@@ -421,7 +417,7 @@ export function runToolsTransformation<TOOLS extends ToolSet>({
               type: 'tool-result',
               toolCallId: chunk.toolCallId,
               toolName,
-              input: toolInputs.get(chunk.toolCallId),
+              input: toolCall?.input,
               output: chunk.result,
               providerExecuted: true,
               dynamic: chunk.dynamic,

package/src/generate-text/stream-text.ts

@@ -82,6 +82,7 @@ import { mergeAbortSignals } from '../util/merge-abort-signals';
 import { mergeObjects } from '../util/merge-objects';
 import { now as originalNow } from '../util/now';
 import { prepareRetries } from '../util/prepare-retries';
+import { setAbortTimeout } from '../util/set-abort-timeout';
 import { collectToolApprovals } from './collect-tool-approvals';
 import { validateApprovedToolApprovals } from './validate-tool-approvals';
 import type {
@@ -1567,25 +1568,25 @@ class DefaultStreamTextResult<
           const includeRawChunks = self.includeRawChunks;
 
           // Set up step timeout if configured
-          const stepTimeoutId =
-            stepTimeoutMs != null
-              ? setTimeout(() => stepAbortController!.abort(), stepTimeoutMs)
-              : undefined;
+          const stepTimeoutId = setAbortTimeout({
+            abortController: stepAbortController,
+            label: 'Step',
+            timeoutMs: stepTimeoutMs,
+          });
 
           // Set up chunk timeout tracking (will be reset on each chunk)
           let chunkTimeoutId: ReturnType<typeof setTimeout> | undefined =
             undefined;
 
           function resetChunkTimeout() {
-            if (chunkTimeoutMs != null) {
-              if (chunkTimeoutId != null) {
-                clearTimeout(chunkTimeoutId);
-              }
-              chunkTimeoutId = setTimeout(
-                () => chunkAbortController!.abort(),
-                chunkTimeoutMs,
-              );
+            if (chunkTimeoutId != null) {
+              clearTimeout(chunkTimeoutId);
             }
+            chunkTimeoutId = setAbortTimeout({
+              abortController: chunkAbortController,
+              label: 'Chunk',
+              timeoutMs: chunkTimeoutMs,
+            });
           }
 
           function clearChunkTimeout() {
@@ -1601,6 +1602,13 @@ class DefaultStreamTextResult<
             }
           }
 
+          // The step's stream is registered lazily and consumed long after this
+          // function returns, so the step timer must stay armed past setup. When
+          // the merged abort signal fires (any step/chunk/total timeout or caller
+          // abort), drop both step-scoped timers so neither outlives the step.
+          abortSignal?.addEventListener('abort', clearStepTimeout);
+          abortSignal?.addEventListener('abort', clearChunkTimeout);
+
           try {
             stepFinish = new DelayedPromise<void>();
 
@@ -2244,9 +2252,12 @@ class DefaultStreamTextResult<
                 }),
               ),
             );
-          } finally {
+          } catch (error) {
+            // Setup failed before the stream was registered, so neither the
+            // stream's flush nor an abort will clear the timers — clear them here.
             clearStepTimeout();
             clearChunkTimeout();
+            throw error;
           }
         }
 

package/src/generate-video/generate-video.ts

@@ -32,7 +32,6 @@ import { prepareRetries } from '../util/prepare-retries';
 import { VERSION } from '../version';
 import type { GenerateVideoResult } from './generate-video-result';
 import { splitDataUrl } from '../prompt/split-data-url';
-import { convertDataContentToUint8Array } from '../prompt/data-content';
 
 export type GenerateVideoPrompt =
   | string
@@ -53,7 +52,7 @@ export type GenerateVideoPrompt =
  * @param fps - Frames per second for the video.
  * @param seed - Seed for the video generation.
  * @param frameImages - Role-tagged image inputs for image-to-video and first-last-frame generation.
- * @param inputReferences - Reference image inputs for reference-to-video generation.
+ * @param inputReferences - Reference image or video inputs for reference-to-video generation.
  * @param generateAudio - Whether the model should generate audio alongside the video.
  * @param providerOptions - Additional provider-specific options that are passed through to the provider
  * as body parameters.
@@ -145,9 +144,26 @@ export async function experimental_generateVideo({
   }>;
 
   /**
-   * Reference image inputs for reference-to-video generation.
+   * Reference inputs for reference-to-video generation.
+   *
+   * Each entry may be a plain image/video ({@link DataContent}), or an object
+   * form that carries an explicit `mediaType`.
    */
-  inputReferences?: Array<DataContent>;
+  inputReferences?: Array<
+    | DataContent
+    | {
+        /**
+         * The reference image or video.
+         */
+        data: DataContent;
+
+        /**
+         * The media type of the reference (e.g. 'image/png',
+         * 'video/mp4').
+         */
+        mediaType?: string;
+      }
+  >;
 
   /**
    * Whether the model should generate audio alongside the video.
@@ -205,16 +221,19 @@ export async function experimental_generateVideo({
 
   const normalizedFrameImages:
     | Array<Experimental_VideoModelV3FrameImage>
-    | undefined = frameImages?.map(frame => ({
-    image: normalizeImageData(frame.image),
-    frameType: frame.frameType,
-  }));
+    | undefined = frameImages?.flatMap(frame => {
+    const normalizedImage = normalizeImageData(frame.image);
+    return normalizedImage != null
+      ? [{ image: normalizedImage, frameType: frame.frameType }]
+      : [];
+  });
 
   const normalizedInputReferences:
     | Array<Experimental_VideoModelV3File>
-    | undefined = inputReferences?.map(reference =>
-    normalizeImageData(reference),
-  );
+    | undefined = inputReferences?.flatMap(reference => {
+    const normalized = normalizeReferenceData(reference);
+    return normalized != null ? [normalized] : [];
+  });
 
   const effectiveInputReferences =
     normalizedFrameImages != null && normalizedFrameImages.length > 0
@@ -430,13 +449,25 @@ function normalizePrompt(promptArg: GenerateVideoPrompt): {
   };
 }
 
+function detectFileMediaType(
+  data: Uint8Array,
+  restrictToImages: boolean,
+): string {
+  const detected = restrictToImages
+    ? detectMediaType({ data, signatures: imageMediaTypeSignatures })
+    : (detectMediaType({ data, signatures: imageMediaTypeSignatures }) ??
+      detectMediaType({ data, signatures: videoMediaTypeSignatures }));
+  return detected ?? 'image/png';
+}
+
 /**
  * Normalizes a {@link DataContent} image into a {@link Experimental_VideoModelV3File}.
  * Accepts a URL string, a data URL, a base64 string, or binary image data.
  */
 function normalizeImageData(
   dataContent: DataContent,
-): Experimental_VideoModelV3File {
+  { restrictToImages = true }: { restrictToImages?: boolean } = {},
+): Experimental_VideoModelV3File | undefined {
   if (typeof dataContent === 'string') {
     if (
       dataContent.startsWith('http://') ||
@@ -450,32 +481,73 @@ function normalizeImageData(
 
     if (dataContent.startsWith('data:')) {
       const { mediaType, base64Content } = splitDataUrl(dataContent);
+      const data = convertBase64ToUint8Array(base64Content ?? '');
       return {
         type: 'file',
-        mediaType: mediaType ?? 'image/png',
-        data: convertBase64ToUint8Array(base64Content ?? ''),
+        mediaType: mediaType ?? detectFileMediaType(data, restrictToImages),
+        data,
       };
     }
 
     const bytes = convertBase64ToUint8Array(dataContent);
     return {
       type: 'file',
-      mediaType:
-        detectMediaType({
-          data: bytes,
-          signatures: imageMediaTypeSignatures,
-        }) ?? 'image/png',
+      mediaType: detectFileMediaType(bytes, restrictToImages),
       data: bytes,
     };
   }
 
-  const bytes = convertDataContentToUint8Array(dataContent);
+  if (dataContent instanceof Uint8Array || dataContent instanceof ArrayBuffer) {
+    const bytes =
+      dataContent instanceof Uint8Array
+        ? dataContent
+        : new Uint8Array(dataContent);
+    return {
+      type: 'file',
+      mediaType: detectFileMediaType(bytes, restrictToImages),
+      data: bytes,
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Normalizes a reference input into a {@link Experimental_VideoModelV3File},
+ * accepting either a plain {@link DataContent} or the object form that carries
+ * an explicit `mediaType`.
+ */
+function normalizeReferenceData(
+  reference:
+    | DataContent
+    | {
+        data: DataContent;
+        mediaType?: string;
+      },
+): Experimental_VideoModelV3File | undefined {
+  const isObjectForm =
+    typeof reference === 'object' &&
+    reference != null &&
+    !(reference instanceof Uint8Array) &&
+    !(reference instanceof ArrayBuffer) &&
+    'data' in reference;
+
+  if (!isObjectForm) {
+    return normalizeImageData(reference as DataContent, {
+      restrictToImages: false,
+    });
+  }
+
+  const normalized = normalizeImageData(reference.data, {
+    restrictToImages: false,
+  });
+  if (normalized == null) {
+    return normalized;
+  }
+
   return {
-    type: 'file',
-    mediaType:
-      detectMediaType({ data: bytes, signatures: imageMediaTypeSignatures }) ??
-      'image/png',
-    data: bytes,
+    ...normalized,
+    ...(reference.mediaType != null ? { mediaType: reference.mediaType } : {}),
   };
 }
 

package/src/ui/chat.ts

@@ -494,7 +494,7 @@ export abstract class AbstractChat<UI_MESSAGE extends UIMessage> {
           ? {
               ...part,
               state: 'approval-responded',
-              approval: { id, approved, reason },
+              approval: { ...part.approval, id, approved, reason },
             }
           : part;
 

package/src/ui/convert-to-model-messages.ts

@@ -246,10 +246,12 @@ export async function convertToModelMessages<UI_MESSAGE extends UIMessage>(
               }
             }
 
-            modelMessages.push({
-              role: 'assistant',
-              content,
-            });
+            if (content.length > 0) {
+              modelMessages.push({
+                role: 'assistant',
+                content,
+              });
+            }
 
             // check if there are tool invocations with results in the block
             // Include non-provider-executed tools, OR provider-executed tools with approval responses
@@ -297,7 +299,7 @@ export async function convertToModelMessages<UI_MESSAGE extends UIMessage>(
                           type: 'error-text' as const,
                           value:
                             toolPart.approval?.reason ??
-                            'Tool execution denied.',
+                            'Tool call execution denied.',
                         },
                         ...(toolPart.callProviderMetadata != null
                           ? { providerOptions: toolPart.callProviderMetadata }

package/src/ui/index.ts

@@ -37,6 +37,7 @@ export {
   getToolName,
   getToolOrDynamicToolName,
   isDataUIPart,
+  isDynamicToolUIPart,
   isFileUIPart,
   isReasoningUIPart,
   isStaticToolUIPart,

package/src/util/set-abort-timeout.ts

@@ -0,0 +1,37 @@
+/**
+ * Schedules a timeout that aborts the given controller with a `TimeoutError`
+ * `DOMException`, matching the reason produced by `AbortSignal.timeout(ms)`.
+ *
+ * @param abortController - The controller to abort when the timeout elapses.
+ * If undefined, no timeout is scheduled.
+ * @param label - Human-readable label included in the error message
+ * (e.g. "Step", "Chunk").
+ * @param timeoutMs - Duration in milliseconds before the controller is aborted.
+ * If undefined, no timeout is scheduled.
+ * @returns The timeout id (suitable for passing to `clearTimeout`), or
+ * `undefined` if no timeout was scheduled.
+ */
+export function setAbortTimeout({
+  abortController,
+  label,
+  timeoutMs,
+}: {
+  abortController: AbortController | undefined;
+  label: string;
+  timeoutMs: number | undefined;
+}): ReturnType<typeof setTimeout> | undefined {
+  if (abortController == null || timeoutMs == null) {
+    return undefined;
+  }
+
+  return setTimeout(
+    () =>
+      abortController.abort(
+        new DOMException(
+          `${label} timeout of ${timeoutMs}ms exceeded`,
+          'TimeoutError',
+        ),
+      ),
+    timeoutMs,
+  );
+}