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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SharedV4FileDataUrl, SharedV4FileDataReference, SharedV4FileDataText, SharedV4ProviderOptions, SharedV4ProviderReference, JSONValue, ImageModelV4File, LanguageModelV4FunctionTool, LanguageModelV4ProviderTool, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, APICallError, LanguageModelV4Prompt, LanguageModelV4CallOptions, SharedV4Warning, SharedV4ProviderMetadata, LanguageModelV4FilePart, JSONObject, LanguageModelV4StreamPart, TypeValidationContext } from '@ai-sdk/provider';
+import { SharedV4FileDataUrl, SharedV4FileDataReference, SharedV4FileDataText, SharedV4ProviderOptions, SharedV4ProviderReference, JSONValue, ImageModelV4File, LanguageModelV4FunctionTool, LanguageModelV4ProviderTool, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, APICallError, LanguageModelV4Prompt, LanguageModelV4CallOptions, SharedV4Warning, JSONObject, LanguageModelV4FilePart, LanguageModelV4StreamPart, SharedV4ProviderMetadata, TypeValidationContext } from '@ai-sdk/provider';
 export { getErrorMessage } from '@ai-sdk/provider';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 export * from '@standard-schema/spec';
@@ -348,6 +348,45 @@ 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';
         /**
          * Base-64 encoded media data.
@@ -367,6 +406,10 @@ 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';
         /**
          * URL of the file.
@@ -383,7 +426,8 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * @deprecated Use file-reference instead.
+         * @deprecated Use 'file' with tagged data instead:
+         * `{ type: 'file', mediaType, data: { type: 'reference', reference } }`.
          */
         type: 'file-id';
         /**
@@ -400,6 +444,10 @@ type ToolResultOutput = {
          */
         providerOptions?: ProviderOptions;
     } | {
+        /**
+         * @deprecated Use 'file' with tagged data instead:
+         * `{ type: 'file', mediaType, data: { type: 'reference', reference } }`.
+         */
         type: 'file-reference';
         /**
          * Provider-specific references for the file.
@@ -412,7 +460,9 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * @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';
         /**
@@ -430,7 +480,9 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * @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';
         /**
@@ -443,7 +495,9 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * @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';
         /**
@@ -461,7 +515,9 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * @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';
         /**
@@ -682,6 +738,51 @@ declare class DownloadError extends AISDKError {
     static isInstance(error: unknown): error is DownloadError;
 }
 
+/**
+ * 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.
+ */
+declare function fetchWithValidatedRedirects({ url, headers, abortSignal, maxRedirects, }: {
+    url: string;
+    headers?: HeadersInit;
+    abortSignal?: AbortSignal;
+    maxRedirects?: number;
+}): Promise<Response>;
+
+/**
+ * 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.
+ */
+declare function extractLines({ text, startLine, endLine, }: {
+    text: string;
+    startLine?: number;
+    endLine?: number;
+}): string;
+
 /**
  * Extracts the headers from a response object and returns them as a key-value object.
  *
@@ -900,6 +1001,16 @@ declare function injectJsonInstructionIntoMessages({ messages, schema, schemaPre
 
 declare function isAbortError(error: unknown): error is Error;
 
+/**
+ * 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`.
+ */
+declare function isBrowserRuntime(globalThisAny?: any): boolean;
+
 /**
  * Type-guard for Node.js `Buffer` instances.
  *
@@ -908,6 +1019,20 @@ declare function isAbortError(error: unknown): error is Error;
  */
 declare function isBuffer(value: unknown): value is Buffer;
 
+/**
+ * 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).
+ */
+declare function isSameOrigin(url: string, baseUrl: string): boolean;
+
 /**
  * Type guard that checks whether a value is not `null` or `undefined`.
  *
@@ -1100,15 +1225,18 @@ declare const postToApi: <T>({ url, headers, body, successfulResponseHandler, fa
  */
 type Context = Record<string, unknown>;
 
-type NeverOptional<N, T> = 0 extends 1 & N ? Partial<T> : [N] extends [never] ? Partial<Record<keyof T, undefined>> : T;
-
 /**
- * Top-level context properties that contain sensitive data and should be
- * excluded from telemetry.
+ * A tool that is guaranteed to expose an execute function.
+ */
+type ExecutableTool<TOOL extends Tool = Tool> = TOOL & {
+    execute: NonNullable<TOOL['execute']>;
+};
+/**
+ * Checks whether a tool exposes an execute function.
  */
-type SensitiveContext<CONTEXT extends Context | unknown | never> = {
-    [KEY in keyof CONTEXT]?: boolean;
-} | undefined;
+declare function isExecutableTool<TOOL extends Tool>(tool: TOOL | undefined): tool is ExecutableTool<TOOL>;
+
+type NeverOptional<N, T> = 0 extends 1 & N ? Partial<T> : [N] extends [never] ? Partial<Record<keyof T, undefined>> : T;
 
 /**
  * Tool approval request prompt part.
@@ -1129,6 +1257,11 @@ type ToolApprovalRequest = {
      * @default false
      */
     isAutomatic?: boolean;
+    /**
+     * HMAC-SHA256 signature binding this approval to its tool call.
+     * Present only when `experimental_toolApprovalSecret` is configured.
+     */
+    signature?: string;
 };
 
 /**
@@ -1234,6 +1367,186 @@ type UserContent = string | Array<TextPart | ImagePart | FilePart>;
  */
 type ModelMessage = SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage;
 
+/**
+ * Options for executing a command in the sandbox via `run` or `spawn`.
+ */
+type SandboxProcessOptions = {
+    /**
+     * Command to execute in the sandbox.
+     */
+    command: string;
+    /**
+     * Working directory to execute the command in.
+     */
+    workingDirectory?: string;
+    /**
+     * Environment variables to set for this command. Merged with the
+     * sandbox's default environment; values here take precedence.
+     * Supporting environment variables as an option is preferable from a
+     * security perspective, e.g. to avoid them leaking in logs.
+     */
+    env?: Record<string, string>;
+    /**
+     * Signal that can be used to abort the command. When aborted, the running
+     * process is killed; for `spawn`, `wait()` rejects with the abort reason.
+     */
+    abortSignal?: AbortSignal;
+};
+/**
+ * Options for reading a file from the sandbox.
+ */
+type ReadFileOptions = {
+    /**
+     * Path of the file to read.
+     */
+    path: string;
+    /**
+     * Signal that can be used to abort the read.
+     */
+    abortSignal?: AbortSignal;
+};
+/**
+ * Options for writing a file to the sandbox. `CONTENT` is the payload written
+ * to the file: a byte stream, raw bytes, or a string.
+ */
+type WriteFileOptions<CONTENT> = {
+    /**
+     * Path of the file to write.
+     */
+    path: string;
+    /**
+     * Content to write to the file.
+     */
+    content: CONTENT;
+    /**
+     * Signal that can be used to abort the write.
+     */
+    abortSignal?: AbortSignal;
+};
+/**
+ * Sandbox session that can execute commands and read/write files.
+ */
+type SandboxSession = {
+    /**
+     * Description of the sandbox environment that can be added to the agent's instructions
+     * so that the agent knows about relevant details such as the root directory, exposed
+     * ports, the public hostname, etc.
+     */
+    readonly description: string;
+    /**
+     * Read one file from the sandbox as a stream of bytes. Resolves to `null`
+     * when the file does not exist.
+     *
+     * Relative path handling is implementation-defined. This is the lowest-level
+     * read primitive; prefer `readBinaryFile` or `readTextFile` unless you need
+     * to stream bytes.
+     */
+    readonly readFile: (options: ReadFileOptions) => PromiseLike<ReadableStream<Uint8Array> | null>;
+    /**
+     * Read one file from the sandbox as raw bytes. Resolves to `null` when the
+     * file does not exist.
+     */
+    readonly readBinaryFile: (options: ReadFileOptions) => PromiseLike<Uint8Array | null>;
+    /**
+     * Read one text file from the sandbox, decoded using the requested encoding.
+     * Resolves to `null` when the file does not exist.
+     *
+     * Line ranges are 1-based and inclusive. When `endLine` is past EOF the read
+     * returns through EOF without error.
+     */
+    readonly readTextFile: (options: ReadFileOptions & {
+        /**
+         * Text encoding used to decode the file bytes. Defaults to `"utf-8"`.
+         */
+        encoding?: string;
+        /**
+         * 1-based inclusive start line. Defaults to 1.
+         */
+        startLine?: number;
+        /**
+         * 1-based inclusive end line. When past the file's line count, the read
+         * returns through EOF without error.
+         */
+        endLine?: number;
+    }) => PromiseLike<string | null>;
+    /**
+     * Write one file to the sandbox from a stream of bytes. Creates parent
+     * directories recursively and overwrites any existing file.
+     *
+     * This is the lowest-level write primitive; prefer `writeBinaryFile` or
+     * `writeTextFile` when the full content is already materialized in memory.
+     */
+    readonly writeFile: (options: WriteFileOptions<ReadableStream<Uint8Array>>) => PromiseLike<void>;
+    /**
+     * Write one file to the sandbox from raw bytes. Creates parent directories
+     * recursively and overwrites any existing file.
+     */
+    readonly writeBinaryFile: (options: WriteFileOptions<Uint8Array>) => PromiseLike<void>;
+    /**
+     * Write one file to the sandbox from a string, encoded using the requested
+     * encoding. Creates parent directories recursively and overwrites any
+     * existing file.
+     */
+    readonly writeTextFile: (options: WriteFileOptions<string> & {
+        /**
+         * Text encoding used to encode the string to bytes. Defaults to `"utf-8"`.
+         */
+        encoding?: string;
+    }) => PromiseLike<void>;
+    /**
+     * Spawn a long-running process in the sandbox. Returns immediately with a
+     * handle that streams stdout/stderr, can be waited on, and can be killed.
+     *
+     * `run` is conceptually a thin wrapper over this primitive: spawn,
+     * collect both streams to strings, await `wait()`, return the result.
+     */
+    readonly spawn: (options: SandboxProcessOptions) => PromiseLike<SandboxProcess>;
+    /**
+     * Run a command in the sandbox.
+     */
+    readonly run: (options: SandboxProcessOptions) => PromiseLike<{
+        /**
+         * Exit code returned by the command.
+         */
+        exitCode: number;
+        /**
+         * Standard output produced by the command.
+         */
+        stdout: string;
+        /**
+         * Standard error produced by the command.
+         */
+        stderr: string;
+    }>;
+};
+/**
+ * Handle to a long-running process started via `SandboxSession.spawn`.
+ */
+type SandboxProcess = {
+    /**
+     * Process identifier, if the sandbox implementation exposes one.
+     */
+    readonly pid?: number;
+    /**
+     * Stream of bytes written by the process to standard output.
+     */
+    readonly stdout: ReadableStream<Uint8Array>;
+    /**
+     * Stream of bytes written by the process to standard error.
+     */
+    readonly stderr: ReadableStream<Uint8Array>;
+    /**
+     * Resolve when the process exits, yielding its exit code.
+     */
+    wait(): PromiseLike<{
+        exitCode: number;
+    }>;
+    /**
+     * Terminate the process. Idempotent.
+     */
+    kill(): PromiseLike<void>;
+};
+
 /**
  * Additional options that are sent into each tool execution.
  */
@@ -1263,6 +1576,10 @@ interface ToolExecutionOptions<CONTEXT extends Context | unknown | never> {
      * in `prepareStep` and update it there.
      */
     context: CONTEXT;
+    /**
+     * The sandbox environment that the tool is operating in.
+     */
+    experimental_sandbox?: SandboxSession;
 }
 /**
  * Function that executes the tool and returns either a single result or a stream of results.
@@ -1331,6 +1648,8 @@ type ToolOutputProperties<INPUT, OUTPUT, CONTEXT extends Context | unknown | nev
 type BaseTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any, CONTEXT extends Context | unknown | never = any> = {
     /**
      * An optional title of the tool.
+     *
+     * @deprecated Use `providerMetadata` for source-specific tool display metadata.
      */
     title?: string;
     /**
@@ -1344,11 +1663,11 @@ type BaseTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JS
      *
      * Unlike `providerOptions`, this metadata is not sent to the language
      * model. Instead, it is propagated onto the resulting tool call's
-     * `providerMetadata` so consumers can read it from tool call / result
-     * parts and UI message parts. This is useful for sources of dynamic
-     * tools (e.g. an MCP server) to identify themselves.
+     * `toolMetadata` so consumers can read it from tool call / result parts
+     * and UI message parts. This is useful for sources of dynamic tools (e.g.
+     * an MCP server) to identify themselves.
      */
-    providerMetadata?: SharedV4ProviderMetadata;
+    metadata?: JSONObject;
     /**
      * The schema of the input that the tool expects.
      * The language model will use this to generate the input.
@@ -1363,11 +1682,6 @@ type BaseTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JS
      * The context is passed to execute function as part of the execution options.
      */
     contextSchema?: FlexibleSchema<CONTEXT>;
-    /**
-     * Marks top-level context properties that contain sensitive data and should be excluded from telemetry.
-     * Properties marked as `true` are omitted from telemetry integrations.
-     */
-    sensitiveContext?: SensitiveContext<CONTEXT>;
     /**
      * Whether the tool needs approval before it can be executed.
      *
@@ -1422,10 +1736,19 @@ type BaseTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JS
  */
 type BaseFunctionTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any, CONTEXT extends Context | unknown | never = any> = BaseTool<INPUT, OUTPUT, CONTEXT> & {
     /**
-     * An optional description of what the tool does.
-     * Will be used by the language model to decide whether to use the tool.
+     * Optional description of what the tool does.
+     *
+     * Included in the tool definition sent to the language model so it can
+     * decide when and how to call the tool.
+     *
+     * Provide a string for a fixed description, or a function that returns a
+     * string from the current `context` (and optional `experimental_sandbox`) when the
+     * description should vary per call.
      */
-    description?: string;
+    description?: string | ((options: {
+        context: NoInfer<CONTEXT>;
+        experimental_sandbox?: SandboxSession;
+    }) => string);
     /**
      * Strict mode setting for the tool.
      *
@@ -1447,14 +1770,16 @@ type BaseFunctionTool<INPUT extends JSONValue | unknown | never = any, OUTPUT ex
     supportsDeferredResults?: never;
 };
 /**
- * Tool with user-defined input and output schemas.
+ * Tool with user-defined input and output schemas that is executed by the AI SDK.
  */
 type FunctionTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any, CONTEXT extends Context | unknown | never = any> = BaseFunctionTool<INPUT, OUTPUT, CONTEXT> & {
     type?: undefined | 'function';
 };
 /**
- * Tool that is defined at runtime (e.g. an MCP tool).
+ * Tool that is defined at runtime.
  * The types of input and output are not known at development time.
+ *
+ * For example, MCP tools that are not known at development time.
  */
 type DynamicTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any, CONTEXT extends Context | unknown | never = any> = BaseFunctionTool<INPUT, OUTPUT, CONTEXT> & {
     type: 'dynamic';
@@ -1479,6 +1804,8 @@ type BaseProviderTool<INPUT extends JSONValue | unknown | never = any, OUTPUT ex
 /**
  * Tool with provider-defined input and output schemas that is executed by the
  * user.
+ *
+ * For example, shell tools that are executed in a local shell, but have provider-defined input and output schemas.
  */
 type ProviderDefinedTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any, CONTEXT extends Context | unknown | never = any> = BaseProviderTool<INPUT, OUTPUT, CONTEXT> & {
     /**
@@ -1490,6 +1817,8 @@ type ProviderDefinedTool<INPUT extends JSONValue | unknown | never = any, OUTPUT
 /**
  * Tool with provider-defined input and output schemas that is executed by the
  * provider.
+ *
+ * For example, web search tools and code execution tools that are executed by the provider itself.
  */
 type ProviderExecutedTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any, CONTEXT extends Context | unknown | never = any> = BaseProviderTool<INPUT, OUTPUT, CONTEXT> & {
     /**
@@ -1523,7 +1852,14 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
  * Infer the tool type from a tool object.
  *
  * This is useful for type inference when working with tool objects.
+ *
+ * When the input has an `execute` function, the return type narrows to
+ * `ExecutableTool<Tool<...>>` so that `.execute` is non-nullable without
+ * needing `isExecutableTool` or a `!` assertion at the call site.
  */
+declare function tool<INPUT, OUTPUT, CONTEXT extends Context>(tool: Tool<INPUT, OUTPUT, CONTEXT> & {
+    execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
+}): ExecutableTool<Tool<INPUT, OUTPUT, CONTEXT>>;
 declare function tool<INPUT, OUTPUT, CONTEXT extends Context>(tool: Tool<INPUT, OUTPUT, CONTEXT>): Tool<INPUT, OUTPUT, CONTEXT>;
 declare function tool<INPUT, CONTEXT extends Context>(tool: Tool<INPUT, never, CONTEXT>): Tool<INPUT, never, CONTEXT>;
 declare function tool<OUTPUT, CONTEXT extends Context>(tool: Tool<never, OUTPUT, CONTEXT>): Tool<never, OUTPUT, CONTEXT>;
@@ -1588,6 +1924,20 @@ declare function createProviderExecutedToolFactory<INPUT, OUTPUT, ARGS extends o
     supportsDeferredResults?: boolean;
 }): ProviderExecutedToolFactory<INPUT, OUTPUT, ARGS, CONTEXT>;
 
+/**
+ * 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.
+ */
+declare function cancelResponseBody(response: Response): Promise<void>;
+
 /**
  * Default maximum download size: 2 GiB.
  *
@@ -1794,6 +2144,10 @@ declare function convertToBase64(value: string | Uint8Array): string;
  * Validates that a URL is safe to download from, blocking private/internal addresses
  * to prevent SSRF attacks.
  *
+ * Note: this performs string/literal-IP checks only. It does not resolve DNS, so a
+ * hostname that resolves to a private address is not blocked here (see callers, which
+ * should additionally constrain egress at the network layer when handling untrusted URLs).
+ *
  * @param url - The URL string to validate.
  * @throws DownloadError if the URL is unsafe.
  */
@@ -1855,20 +2209,24 @@ declare function withUserAgentSuffix(headers: HeadersInit | Record<string, strin
 declare function withoutTrailingSlash(url: string | undefined): string | undefined;
 
 /**
- * A tool that is guaranteed to expose an execute function.
+ * Detects the `any` type so untyped tools can be treated as having no explicit
+ * context type.
  */
-type ExecutableTool<TOOL extends Tool = Tool> = TOOL & {
-    execute: NonNullable<TOOL['execute']>;
-};
+type IsAny<T> = 0 extends 1 & T ? true : false;
 /**
- * Checks whether a tool exposes an execute function.
+ * Detects exact empty object contexts, including `{}` combined with
+ * `undefined`, which do not provide tool-specific context properties.
  */
-declare function isExecutableTool<TOOL extends Tool>(tool: TOOL | undefined): tool is ExecutableTool<TOOL>;
-
+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.
  */
-type InferToolContext<TOOL extends Tool> = TOOL extends Tool<any, any, infer CONTEXT> ? HasRequiredKey<CONTEXT> extends true ? CONTEXT : never : never;
+type InferToolContext<TOOL extends Tool> = TOOL extends Tool<any, any, infer CONTEXT> ? IsUntypedContext<CONTEXT> extends true ? never : CONTEXT : never;
 
 /**
  * Infer the input type of a tool.
@@ -1911,16 +2269,36 @@ declare function executeTool<TOOL extends Tool>({ tool, input, options, }: {
  */
 type ToolSet = Record<string, (Tool<never, never, any> | Tool<any, any, any> | Tool<any, never, any> | Tool<never, any, any>) & Pick<Tool<any, any, any>, 'execute' | 'onInputAvailable' | 'onInputStart' | 'onInputDelta' | 'needsApproval'>>;
 
+/**
+ * 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`.
+ */
+type OptionalToolSetContext<TOOLS extends ToolSet> = {
+    [K in keyof TOOLS as InferToolContext<NoInfer<TOOLS[K]>> extends never ? never : 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 tool name to its required context type.
+ * The inferred type maps each contextual tool name to its context type.
  *
- * Tools without required context properties are omitted from the result.
+ * Tools without concrete context are omitted. Tool contexts that include
+ * `undefined` are represented as optional properties.
  */
-type InferToolSetContext<TOOLS extends ToolSet> = {
-    [K in keyof TOOLS as InferToolContext<NoInfer<TOOLS[K]>> extends never ? never : K]: InferToolContext<NoInfer<TOOLS[K]>>;
-};
+type InferToolSetContext<TOOLS extends ToolSet> = Normalize<RequiredToolSetContext<TOOLS> & OptionalToolSetContext<TOOLS>>;
 
 /**
  * Typed tool call that is returned by generateText and streamText.
@@ -1981,4 +2359,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-export { type Arrayable, type AssistantContent, type AssistantModelMessage, type Context, type CustomPart, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type DynamicTool, type ExecutableTool, type FetchFunction, type FileData, type FileDataData, type FileDataReference, type FileDataText, type FileDataUrl, type FilePart, type FlexibleSchema, type FunctionTool, type HasRequiredKey, type IdGenerator, type ImagePart, type InferSchema, type InferToolContext, type InferToolInput, type InferToolOutput, type InferToolSetContext, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderDefinedTool, type ProviderDefinedToolFactory, type ProviderDefinedToolFactoryWithOutputSchema, type ProviderExecutedTool, type ProviderExecutedToolFactory, type ProviderOptions, type ProviderReference, type ReasoningFilePart, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SensitiveContext, type StreamingToolCallDelta, StreamingToolCallTracker, type StreamingToolCallTrackerOptions, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type ToolSet, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asArray, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertInlineFileDataToUint8Array, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderDefinedToolFactory, createProviderDefinedToolFactoryWithOutputSchema, createProviderExecutedToolFactory, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, detectMediaType, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, filterNullable, generateId, getFromApi, getRuntimeEnvironmentUserAgent, getTopLevelMediaType, injectJsonInstructionIntoMessages, isAbortError, isBuffer, isCustomReasoning, isExecutableTool, isFullMediaType, isNonNullable, isParsableJson, isProviderReference, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, resolveFullMediaType, resolveProviderReference, safeParseJSON, safeValidateTypes, serializeModelOptions, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+export { type Arrayable, type AssistantContent, type AssistantModelMessage, type Context, type CustomPart, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type DynamicTool, type ExecutableTool, type SandboxProcess as Experimental_SandboxProcess, type SandboxSession as Experimental_SandboxSession, type FetchFunction, type FileData, type FileDataData, type FileDataReference, type FileDataText, type FileDataUrl, type FilePart, type FlexibleSchema, type FunctionTool, type HasRequiredKey, type IdGenerator, type ImagePart, type InferSchema, type InferToolContext, type InferToolInput, type InferToolOutput, type InferToolSetContext, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderDefinedTool, type ProviderDefinedToolFactory, type ProviderDefinedToolFactoryWithOutputSchema, type ProviderExecutedTool, type ProviderExecutedToolFactory, type ProviderOptions, type ProviderReference, type ReasoningFilePart, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type StreamingToolCallDelta, StreamingToolCallTracker, type StreamingToolCallTrackerOptions, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type ToolSet, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asArray, asSchema, cancelResponseBody, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertInlineFileDataToUint8Array, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderDefinedToolFactory, createProviderDefinedToolFactoryWithOutputSchema, createProviderExecutedToolFactory, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, detectMediaType, downloadBlob, dynamicTool, executeTool, extractLines, extractResponseHeaders, fetchWithValidatedRedirects, filterNullable, generateId, getFromApi, getRuntimeEnvironmentUserAgent, getTopLevelMediaType, injectJsonInstructionIntoMessages, isAbortError, isBrowserRuntime, isBuffer, isCustomReasoning, isExecutableTool, isFullMediaType, isNonNullable, isParsableJson, isProviderReference, isSameOrigin, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, resolveFullMediaType, resolveProviderReference, safeParseJSON, safeValidateTypes, serializeModelOptions, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };