@ai-sdk/provider-utils 5.0.0-beta.30 → 5.0.0-beta.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "5.0.0-beta.30",
+  "version": "5.0.0-beta.49",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,12 +35,12 @@
     "@standard-schema/spec": "^1.1.0",
     "@workflow/serde": "4.1.0",
     "eventsource-parser": "^3.0.8",
-    "@ai-sdk/provider": "4.0.0-beta.14"
+    "@ai-sdk/provider": "4.0.0-beta.19"
   },
   "devDependencies": {
-    "@types/node": "20.17.24",
+    "@types/node": "22.19.19",
     "msw": "2.7.0",
-    "tsup": "^8",
+    "tsup": "^8.5.1",
     "typescript": "5.8.3",
     "zod": "3.25.76",
     "@vercel/ai-tsconfig": "0.0.0"
@@ -49,7 +49,7 @@
     "zod": "^3.25.76 || ^4.1.8"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public",

package/src/cancel-response-body.ts

@@ -0,0 +1,19 @@
+/**
+ * Cancels a response body to release the underlying connection.
+ *
+ * When a fetch Response is rejected without consuming its body (e.g. a failed
+ * status code, an open-redirect rejection, or a Content-Length that exceeds the
+ * size limit), the underlying TCP socket is not returned to the connection pool
+ * and may stay open until the process runs out of file descriptors. Cancelling
+ * the body avoids this leak.
+ *
+ * Errors thrown while cancelling are ignored: the body may already be locked,
+ * disturbed, or absent, none of which should mask the original rejection.
+ */
+export async function cancelResponseBody(response: Response): Promise<void> {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // Ignore cancel errors so the original rejection is preserved.
+  }
+}

package/src/download-blob.ts

@@ -1,9 +1,10 @@
+import { cancelResponseBody } from './cancel-response-body';
 import { DownloadError } from './download-error';
+import { fetchWithValidatedRedirects } from './fetch-with-validated-redirects';
 import {
   readResponseWithSizeLimit,
   DEFAULT_MAX_DOWNLOAD_SIZE,
 } from './read-response-with-size-limit';
-import { validateDownloadUrl } from './validate-download-url';
 
 /**
  * Download a file from a URL and return it as a Blob.
@@ -20,18 +21,16 @@ export async function downloadBlob(
   url: string,
   options?: { maxBytes?: number; abortSignal?: AbortSignal },
 ): Promise<Blob> {
-  validateDownloadUrl(url);
   try {
-    const response = await fetch(url, {
-      signal: options?.abortSignal,
+    const response = await fetchWithValidatedRedirects({
+      url,
+      abortSignal: options?.abortSignal,
     });
 
-    // Validate final URL after redirects to prevent SSRF via open redirect
-    if (response.redirected) {
-      validateDownloadUrl(response.url);
-    }
-
     if (!response.ok) {
+      // Release the connection before rejecting so an error status from an
+      // attacker-controlled origin cannot leak open sockets.
+      await cancelResponseBody(response);
       throw new DownloadError({
         url,
         statusCode: response.status,

package/src/extract-lines.ts

@@ -0,0 +1,31 @@
+/**
+ * Extracts a 1-based inclusive line range from `text`, auto-detecting the
+ * file's line ending (`\r\n`, `\n`, or `\r`, in that priority).
+ *
+ * Mixed line endings are not supported: detection picks one and uses it for
+ * both the split and the rejoin, so files that mix conventions will not slice
+ * cleanly. When neither `startLine` nor `endLine` is provided, the input is
+ * returned unchanged. `endLine` past EOF clamps to the last line.
+ */
+export function extractLines({
+  text,
+  startLine,
+  endLine,
+}: {
+  text: string;
+  startLine?: number;
+  endLine?: number;
+}): string {
+  if (startLine == null && endLine == null) return text;
+  const lineEnding = text.includes('\r\n')
+    ? '\r\n'
+    : text.includes('\n')
+      ? '\n'
+      : text.includes('\r')
+        ? '\r'
+        : '\n';
+  const lines = text.split(lineEnding);
+  const start = Math.max(1, startLine ?? 1) - 1;
+  const end = Math.min(lines.length, endLine ?? lines.length);
+  return lines.slice(start, end).join(lineEnding);
+}

package/src/fetch-with-validated-redirects.ts

@@ -0,0 +1,87 @@
+import { cancelResponseBody } from './cancel-response-body';
+import { DownloadError } from './download-error';
+import { isBrowserRuntime } from './is-browser-runtime';
+import { validateDownloadUrl } from './validate-download-url';
+
+const MAX_DOWNLOAD_REDIRECTS = 10;
+
+/**
+ * Fetches a URL while enforcing the SSRF download guard on every hop.
+ *
+ * Redirects are followed manually (`redirect: 'manual'`) so each hop is
+ * validated with {@link validateDownloadUrl} *before* it is requested. Relying
+ * on the default `redirect: 'follow'` would issue the request to a redirect
+ * target (e.g. an internal address) before we ever see its URL, defeating the
+ * SSRF guard.
+ *
+ * A `redirect: 'manual'` request yields an unreadable opaque response in the
+ * browser (and in other spec-compliant fetch implementations), so the redirect
+ * target cannot be validated here. In a real browser this is safe to follow
+ * natively because SSRF is not reachable (fetch is constrained by CORS and
+ * cannot reach a server's internal network or cloud-metadata). On any other
+ * runtime we cannot validate the hop, so we fail closed rather than follow it
+ * blindly and bypass the SSRF guard.
+ *
+ * The returned response is the final (non-redirect) response. The caller is
+ * responsible for checking `response.ok` and reading the body.
+ *
+ * @throws DownloadError if a hop is unsafe, the redirect limit is exceeded, or
+ * a redirect cannot be validated on a non-browser runtime.
+ */
+export async function fetchWithValidatedRedirects({
+  url,
+  headers,
+  abortSignal,
+  maxRedirects = MAX_DOWNLOAD_REDIRECTS,
+}: {
+  url: string;
+  headers?: HeadersInit;
+  abortSignal?: AbortSignal;
+  maxRedirects?: number;
+}): Promise<Response> {
+  // Per-hop request options. Only the `redirect` mode varies between hops, so
+  // the rest is assembled once. `headers` is omitted entirely when not provided
+  // so callers that send none issue a bare request.
+  const baseInit: RequestInit = { signal: abortSignal };
+  if (headers !== undefined) {
+    baseInit.headers = headers;
+  }
+
+  let currentUrl = url;
+  // The bound also acts as a backstop against an unterminated redirect chain.
+  for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
+    validateDownloadUrl(currentUrl);
+
+    const response = await fetch(currentUrl, {
+      ...baseInit,
+      redirect: 'manual',
+    });
+
+    if (response.type === 'opaqueredirect') {
+      if (!isBrowserRuntime()) {
+        throw new DownloadError({
+          url,
+          message: `Redirect from ${currentUrl} could not be validated and was blocked`,
+        });
+      }
+      return await fetch(currentUrl, { ...baseInit, redirect: 'follow' });
+    }
+
+    const location = response.headers.get('location');
+    if (response.status >= 300 && response.status < 400 && location) {
+      // Release the redirect response's connection before moving to the next
+      // hop. Whether that hop is followed or rejected by the SSRF guard, an
+      // unconsumed 3xx body would leak the underlying socket.
+      await cancelResponseBody(response);
+      currentUrl = new URL(location, currentUrl).toString();
+      continue;
+    }
+
+    return response;
+  }
+
+  throw new DownloadError({
+    url,
+    message: `Too many redirects (max ${maxRedirects})`,
+  });
+}

package/src/index.ts

@@ -18,6 +18,8 @@ export {
 } from './detect-media-type';
 export { downloadBlob } from './download-blob';
 export { DownloadError } from './download-error';
+export { fetchWithValidatedRedirects } from './fetch-with-validated-redirects';
+export { extractLines } from './extract-lines';
 export * from './extract-response-headers';
 export * from './fetch-function';
 export { filterNullable } from './filter-nullable';
@@ -28,7 +30,9 @@ export { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-a
 export type { HasRequiredKey } from './has-required-key';
 export { injectJsonInstructionIntoMessages } from './inject-json-instruction';
 export * from './is-abort-error';
+export { isBrowserRuntime } from './is-browser-runtime';
 export { isBuffer } from './is-buffer';
+export { isSameOrigin } from './is-same-origin';
 export { isNonNullable } from './is-non-nullable';
 export { isProviderReference } from './is-provider-reference';
 export { isUrlSupported } from './is-url-supported';
@@ -57,6 +61,7 @@ export {
   createProviderExecutedToolFactory,
   type ProviderExecutedToolFactory,
 } from './provider-executed-tool-factory';
+export { cancelResponseBody } from './cancel-response-body';
 export {
   DEFAULT_MAX_DOWNLOAD_SIZE,
   readResponseWithSizeLimit,

package/src/is-browser-runtime.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns `true` when running in a browser.
+ *
+ * Detection keys on the presence of a global `window`, matching the browser
+ * check used elsewhere in this package (see `getRuntimeEnvironmentUserAgent`)
+ * so the SDK has a single, consistent definition of "browser". Server runtimes
+ * (Node.js, Deno, Bun, edge/workers) do not define `window`.
+ */
+export function isBrowserRuntime(
+  globalThisAny: any = globalThis as any,
+): boolean {
+  return globalThisAny.window != null;
+}

package/src/is-same-origin.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns true when `url` has the same origin (scheme + host + port) as
+ * `baseUrl`.
+ *
+ * Used to decide whether provider credentials may be attached to a request to a
+ * URL taken from a provider response (e.g. a polling or media-download URL).
+ * Credentials must only be sent to the provider's own origin; a response that
+ * names a foreign host (a CDN, or an attacker-controlled host if the response
+ * is tampered with) must not receive the API key.
+ *
+ * Returns false if either value is not a valid absolute URL (fail-closed).
+ */
+export function isSameOrigin(url: string, baseUrl: string): boolean {
+  try {
+    return new URL(url).origin === new URL(baseUrl).origin;
+  } catch {
+    return false;
+  }
+}

package/src/read-response-with-size-limit.ts

@@ -1,3 +1,4 @@
+import { cancelResponseBody } from './cancel-response-body';
 import { DownloadError } from './download-error';
 
 /**
@@ -40,6 +41,9 @@ export async function readResponseWithSizeLimit({
   if (contentLength != null) {
     const length = parseInt(contentLength, 10);
     if (!isNaN(length) && length > maxBytes) {
+      // Cancel the body so the underlying connection is released back to the
+      // pool instead of being left open until the socket is exhausted.
+      await cancelResponseBody(response);
       throw new DownloadError({
         url,
         message: `Download of ${url} exceeded maximum size of ${maxBytes} bytes (Content-Length: ${length}).`,

package/src/schema.ts

@@ -136,7 +136,11 @@ export function asSchema<OBJECT>(
   schema: FlexibleSchema<OBJECT> | undefined,
 ): Schema<OBJECT> {
   return schema == null
-    ? jsonSchema({ properties: {}, additionalProperties: false })
+    ? jsonSchema({
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      })
     : isSchema(schema)
       ? schema
       : '~standard' in schema

package/src/to-json-schema/zod3-to-json-schema/parsers/pipeline.ts

@@ -14,16 +14,18 @@ export const parsePipelineDef = (
     return parseDef(def.out._def, refs);
   }
 
-  const a = parseDef(def.in._def, {
+  const inputSchema = parseDef(def.in._def, {
     ...refs,
     currentPath: [...refs.currentPath, 'allOf', '0'],
   });
-  const b = parseDef(def.out._def, {
+  const outputSchema = parseDef(def.out._def, {
     ...refs,
-    currentPath: [...refs.currentPath, 'allOf', a ? '1' : '0'],
+    currentPath: [...refs.currentPath, 'allOf', inputSchema ? '1' : '0'],
   });
 
   return {
-    allOf: [a, b].filter((x): x is JsonSchema7Type => x !== undefined),
+    allOf: [inputSchema, outputSchema].filter(
+      (schema): schema is JsonSchema7Type => schema !== undefined,
+    ),
   };
 };

package/src/types/content-part.ts

@@ -317,6 +317,50 @@ export type ToolResultOutput =
             providerOptions?: ProviderOptions;
           }
         | {
+            type: 'file';
+
+            /**
+             * File data as a tagged discriminated union:
+             *
+             * - `{ type: 'data', data }`: raw bytes
+             *   (base64 string, Uint8Array, ArrayBuffer, Buffer)
+             * - `{ type: 'url', url }`: a URL that points to the file
+             * - `{ type: 'reference', reference }`: a provider reference
+             *   from `uploadFile`
+             * - `{ type: 'text', text }`: inline text content (e.g. an inline
+             *   text document)
+             */
+            data: FileData;
+
+            /**
+             * Either a full IANA media type (`type/subtype`, e.g. `image/png`) or just
+             * the top-level IANA segment (e.g. `image`, `audio`, `video`, `text`).
+             *
+             * `*`-subtype wildcards (e.g. `image/*`) are normalized as equivalent to the
+             * top-level segment alone (e.g. `image`). Providers can use the helpers in
+             * `@ai-sdk/provider-utils` (`isFullMediaType`, `getTopLevelMediaType`,
+             * `detectMediaType`) to resolve the field according to their API
+             * requirements.
+             *
+             * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+             */
+            mediaType: string;
+
+            /**
+             * Optional filename of the file.
+             */
+            filename?: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * @deprecated Use 'file' with mediaType + tagged data instead:
+             * `{ type: 'file', mediaType, data: { type: 'data', data } }`.
+             */
             type: 'file-data';
 
             /**
@@ -341,6 +385,10 @@ export type ToolResultOutput =
             providerOptions?: ProviderOptions;
           }
         | {
+            /**
+             * @deprecated Use 'file' with mediaType and tagged data instead:
+             * `{ type: 'file', mediaType, data: { type: 'url', url: new URL(url) } }`.
+             */
             type: 'file-url';
 
             /**
@@ -352,7 +400,7 @@ export type ToolResultOutput =
              * IANA media type.
              * @see https://www.iana.org/assignments/media-types/media-types.xhtml
              */
-            mediaType?: string; // Temporarily optional. TODO: make required in v8, after migration period.
+            mediaType?: string;
 
             /**
              * Provider-specific options.
@@ -361,7 +409,8 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * @deprecated Use file-reference instead.
+             * @deprecated Use 'file' with tagged data instead:
+             * `{ type: 'file', mediaType, data: { type: 'reference', reference } }`.
              */
             type: 'file-id';
 
@@ -381,6 +430,10 @@ export type ToolResultOutput =
             providerOptions?: ProviderOptions;
           }
         | {
+            /**
+             * @deprecated Use 'file' with tagged data instead:
+             * `{ type: 'file', mediaType, data: { type: 'reference', reference } }`.
+             */
             type: 'file-reference';
 
             /**
@@ -396,7 +449,9 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * @deprecated Use file-data instead.
+             * @deprecated Use 'file' with mediaType (e.g. 'image' or a specific
+             * `image/*` subtype) and tagged data instead:
+             * `{ type: 'file', mediaType: 'image', data: { type: 'data', data } }`.
              */
             type: 'image-data';
 
@@ -418,7 +473,9 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * @deprecated Use file-url instead.
+             * @deprecated Use 'file' with `mediaType: 'image'` (or a specific
+             * `image/*` subtype) and tagged data instead:
+             * `{ type: 'file', mediaType: 'image', data: { type: 'url', url: new URL(url) } }`.
              */
             type: 'image-url';
 
@@ -434,7 +491,9 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * @deprecated Use file-reference instead.
+             * @deprecated Use 'file' with `mediaType: 'image'` (or a specific
+             * `image/*` subtype) and tagged data instead:
+             * `{ type: 'file', mediaType: 'image', data: { type: 'reference', reference } }`.
              */
             type: 'image-file-id';
 
@@ -455,7 +514,9 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * @deprecated Use file-reference instead.
+             * @deprecated Use 'file' with `mediaType: 'image'` (or a specific
+             * `image/*` subtype) and tagged data instead:
+             * `{ type: 'file', mediaType: 'image', data: { type: 'reference', reference } }`.
              */
             type: 'image-file-reference';
 

package/src/types/index.ts

@@ -15,6 +15,7 @@ export type {
 } from './content-part';
 export type { Context } from './context';
 export type { DataContent } from './data-content';
+export { isExecutableTool, type ExecutableTool } from './executable-tool';
 export { executeTool } from './execute-tool';
 export type {
   FileData,
@@ -23,7 +24,6 @@ export type {
   FileDataText,
   FileDataUrl,
 } from './file-data';
-export { isExecutableTool, type ExecutableTool } from './executable-tool';
 export type { InferToolContext } from './infer-tool-context';
 export type { InferToolInput } from './infer-tool-input';
 export type { InferToolOutput } from './infer-tool-output';
@@ -31,7 +31,10 @@ export type { InferToolSetContext } from './infer-tool-set-context';
 export type { ModelMessage } from './model-message';
 export type { ProviderOptions } from './provider-options';
 export type { ProviderReference } from './provider-reference';
-export type { SensitiveContext } from './sensitive-context';
+export type {
+  SandboxSession as Experimental_SandboxSession,
+  SandboxProcess as Experimental_SandboxProcess,
+} from './sandbox';
 export type { SystemModelMessage } from './system-model-message';
 export {
   dynamicTool,
@@ -42,15 +45,15 @@ export {
   type ProviderExecutedTool,
   type Tool,
 } from './tool';
+export type { ToolApprovalRequest } from './tool-approval-request';
+export type { ToolApprovalResponse } from './tool-approval-response';
+export type { ToolCall } from './tool-call';
 export type {
   ToolExecuteFunction,
   ToolExecutionOptions,
 } from './tool-execute-function';
-export type { ToolNeedsApprovalFunction } from './tool-needs-approval-function';
-export type { ToolSet } from './tool-set';
-export type { ToolApprovalRequest } from './tool-approval-request';
-export type { ToolApprovalResponse } from './tool-approval-response';
-export type { ToolCall } from './tool-call';
 export type { ToolContent, ToolModelMessage } from './tool-model-message';
+export type { ToolNeedsApprovalFunction } from './tool-needs-approval-function';
 export type { ToolResult } from './tool-result';
+export type { ToolSet } from './tool-set';
 export type { UserContent, UserModelMessage } from './user-model-message';

package/src/types/infer-tool-context.ts

@@ -1,12 +1,41 @@
-import type { HasRequiredKey } from '../has-required-key';
+import type { Context } from './context';
 import type { Tool } from './tool';
 
+/**
+ * Detects the `any` type so untyped tools can be treated as having no explicit
+ * context type.
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * Detects exact empty object contexts, including `{}` combined with
+ * `undefined`, which do not provide tool-specific context properties.
+ */
+type IsEmptyObject<T> = keyof NonNullable<T> extends never ? true : false;
+
+/**
+ * Detects context types that come from omitted or broad context declarations
+ * rather than a concrete tool context schema.
+ */
+type IsUntypedContext<CONTEXT> =
+  IsAny<CONTEXT> extends true
+    ? true
+    : unknown extends CONTEXT
+      ? true
+      : IsEmptyObject<CONTEXT> extends true
+        ? true
+        : string extends keyof CONTEXT
+          ? CONTEXT extends Context
+            ? true
+            : false
+          : false;
+
 /**
  * Infer the context type of a tool.
  */
 export type InferToolContext<TOOL extends Tool> =
   TOOL extends Tool<any, any, infer CONTEXT>
-    ? HasRequiredKey<CONTEXT> extends true
-      ? CONTEXT
-      : never
+    ? IsUntypedContext<CONTEXT> extends true
+      ? never
+      : CONTEXT
     : never;

package/src/types/infer-tool-set-context.ts

@@ -2,14 +2,43 @@ import type { InferToolContext } from './infer-tool-context';
 import type { ToolSet } from './tool-set';
 
 /**
- * Infer the context type for a tool set.
- *
- * The inferred type maps each tool name to its required context type.
- *
- * Tools without required context properties are omitted from the result.
+ * Builds the required portion of the tool context map for tools whose context
+ * type does not include `undefined`.
+ */
+type RequiredToolSetContext<TOOLS extends ToolSet> = {
+  [K in keyof TOOLS as InferToolContext<NoInfer<TOOLS[K]>> extends never
+    ? never
+    : undefined extends InferToolContext<NoInfer<TOOLS[K]>>
+      ? never
+      : K]: InferToolContext<NoInfer<TOOLS[K]>>;
+};
+
+/**
+ * Builds the optional portion of the tool context map for tools whose context
+ * object itself may be `undefined`.
  */
-export type InferToolSetContext<TOOLS extends ToolSet> = {
+type OptionalToolSetContext<TOOLS extends ToolSet> = {
   [K in keyof TOOLS as InferToolContext<NoInfer<TOOLS[K]>> extends never
     ? never
-    : K]: InferToolContext<NoInfer<TOOLS[K]>>;
+    : undefined extends InferToolContext<NoInfer<TOOLS[K]>>
+      ? K
+      : never]?: InferToolContext<NoInfer<TOOLS[K]>>;
 };
+
+/**
+ * Flattens intersected mapped types so type equality assertions and editor
+ * hovers show the resulting object shape.
+ */
+type Normalize<OBJECT> = { [KEY in keyof OBJECT]: OBJECT[KEY] };
+
+/**
+ * Infer the context type for a tool set.
+ *
+ * The inferred type maps each contextual tool name to its context type.
+ *
+ * Tools without concrete context are omitted. Tool contexts that include
+ * `undefined` are represented as optional properties.
+ */
+export type InferToolSetContext<TOOLS extends ToolSet> = Normalize<
+  RequiredToolSetContext<TOOLS> & OptionalToolSetContext<TOOLS>
+>;