ai 7.0.150 → 7.0.151

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ai
 
+## 7.0.151
+
+### Patch Changes
+
+- Updated dependencies [1bf6d85]
+  - @ai-sdk/gateway@4.0.124
+
 ## 7.0.150
 
 ### Patch Changes

package/dist/index.js

@@ -1175,7 +1175,7 @@ function cloneValue(value) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "7.0.150";
+const VERSION = "7.0.151";
 //#endregion
 //#region src/util/download/download.ts
 /**

package/dist/internal/index.js

@@ -111,7 +111,7 @@ function asAsyncIterableStream(stream) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "7.0.150";
+const VERSION = "7.0.151";
 //#endregion
 //#region src/util/download/download.ts
 /**

package/docs/03-ai-sdk-core/18-tools.mdx

@@ -28,9 +28,7 @@ The tool has no direct dependency on either runtime.
 Install the tool and the sandbox adapter you want to use. The following examples
 use just-bash:
 
-```sh
-pnpm add ai @ai-sdk/tool-bash @ai-sdk/sandbox-just-bash
-```
+<InstallPackages packages="ai @ai-sdk/tool-bash @ai-sdk/sandbox-just-bash" />
 
 Requires Node.js 22.13 or newer.
 
@@ -102,12 +100,36 @@ Raw runtime instances need their respective adapters; a custom
 
 `experimental_createBashTool()` requires an options object:
 
-| Option             | Type                          | Description                                                                                                                   |
-| ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `sandbox`          | `Experimental_SandboxSession` | Required session for command execution and file operations.                                                                   |
-| `workingDirectory` | `string`                      | Optional absolute starting directory for each command, created if needed. When omitted, uses the sandbox's default directory. |
-| `maxOutputLength`  | `number`                      | Positive integer limiting characters retained from each output stream before a truncation notice. Defaults to `30000`.        |
-| `timeout`          | `number`                      | Optional timeout per command execution, in milliseconds (integer from `1` to `2147483647`). No tool-level timeout by default. |
+<PropertiesTable
+  content={[
+    {
+      name: 'sandbox',
+      type: 'Experimental_SandboxSession',
+      description: 'Session for command execution and file operations.',
+    },
+    {
+      name: 'workingDirectory',
+      type: 'string',
+      isOptional: true,
+      description:
+        "Absolute starting directory for each command, created if needed. When omitted, uses the sandbox's default directory.",
+    },
+    {
+      name: 'maxOutputLength',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Positive integer limiting characters retained from each output stream before a truncation notice. Defaults to `30000`.',
+    },
+    {
+      name: 'timeout',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Timeout per command execution, in milliseconds (integer from `1` to `2147483647`). No tool-level timeout by default.',
+    },
+  ]}
+/>
 
 The model calls the tool with `{ command: string }` and receives
 `{ stdout, stderr, exitCode }`. Nonzero exit codes are returned so the model can
@@ -154,3 +176,153 @@ it returns `null` if the file is missing. Relative read paths depend on the
 sandbox adapter; just-bash resolves them against its default directory. With an
 explicit working directory, use absolute paths to read files from that directory.
 The same session provides other file operations.
+
+## Web Fetch Tool
+
+`experimental_createWebFetchTool` lets agents read web pages and documents by URL.
+
+### Installation
+
+<InstallPackages packages="ai @ai-sdk/tool-web-fetch" />
+
+Requires Node.js 22.13 or newer.
+
+### Usage
+
+```ts
+import { experimental_createWebFetchTool as createWebFetchTool } from '@ai-sdk/tool-web-fetch';
+import { generateText, isStepCount } from 'ai';
+
+const result = await generateText({
+  model, // Your configured model with function calling support.
+  tools: { webFetch: createWebFetchTool() },
+  stopWhen: isStepCount(5),
+  prompt: 'Summarize https://ai-sdk.dev/docs/introduction.',
+});
+```
+
+### Options
+
+`experimental_createWebFetchTool()` accepts an optional options object:
+
+<PropertiesTable
+  content={[
+    {
+      name: 'allowedDomains',
+      type: 'string[]',
+      isOptional: true,
+      description:
+        "Only fetch from these domains and their subdomains, e.g. `['example.com']`. List a subdomain such as `docs.example.com` to allow only that subdomain. Also applies to redirects. Cannot be combined with `blockedDomains`.",
+    },
+    {
+      name: 'blockedDomains',
+      type: 'string[]',
+      isOptional: true,
+      description:
+        'Never fetch from these domains or their subdomains. Also applies to redirects.',
+    },
+    {
+      name: 'requireUrlInUserMessage',
+      type: 'boolean',
+      isOptional: true,
+      description:
+        'Only fetch URLs that appear in user messages. URLs in instructions, system messages, assistant messages, and tool results are not included. Defaults to `false`.',
+    },
+    {
+      name: 'maxLength',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum characters returned per call. Longer content can be read with `offset`. Defaults to `50000`.',
+    },
+    {
+      name: 'maxBytes',
+      type: 'number',
+      isOptional: true,
+      description: 'Maximum response size in bytes. Defaults to 10 MiB.',
+    },
+    {
+      name: 'timeout',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Timeout in milliseconds for fetching each URL, including redirects. Defaults to `30000`.',
+    },
+    {
+      name: 'fetch',
+      type: 'FetchFunction',
+      isOptional: true,
+      description:
+        'Custom fetch implementation, for example to route requests through a proxy. It must validate resolved addresses itself.',
+    },
+    {
+      name: 'defuddleOptions',
+      type: 'DefuddleOptions',
+      isOptional: true,
+      description:
+        'Options for the [defuddle](https://github.com/kepano/defuddle) HTML content extractor, such as `contentSelector`.',
+    },
+  ]}
+/>
+
+The model calls the tool with `{ url: string, offset?: number }` and receives
+one of the following results:
+
+- `{ type: 'document', url, finalUrl, contentType, title?, content, offset, totalLength, nextOffset? }`
+  for HTML and text.
+- `{ type: 'error', url, errorCode, message, statusCode? }` when fetching fails.
+
+Errors are returned so the model can recover, for example by trying another URL.
+The model receives documents as text with the URL, title, and content type,
+followed by the content. AI SDK cancellation aborts the request.
+
+`experimental_createWebFetchTool()` returns the tool directly, ready to use as `tools: { webFetch }`.
+
+### Content handling
+
+Requests prefer markdown using the `Accept: text/markdown` header, which many
+documentation sites support. Otherwise, HTML pages are converted to markdown
+with [defuddle](https://github.com/kepano/defuddle), which removes navigation,
+footers, and other boilerplate. Text formats such as plain text, JSON, XML, and
+CSV are returned as is. PDFs, images, audio, video, and other binary formats
+are not supported.
+
+JavaScript is not executed. Pages that render their content in the browser may
+return little or no content, in which case the model is told that the page may
+require JavaScript.
+
+The extractor sometimes selects the wrong part of a page. If you fetch pages
+with a known structure, set `defuddleOptions.contentSelector` to choose the main
+content element:
+
+```ts
+const webFetch = createWebFetchTool({
+  defuddleOptions: { contentSelector: 'article' },
+});
+```
+
+Content longer than `maxLength` is truncated. The model is told to call the tool
+again with `offset` to continue reading. Converted documents are cached for a
+few minutes per tool instance, so reading at an offset does not fetch the page
+again.
+
+### Security
+
+The tool makes GET requests without cookies or credentials, and rejects URLs
+that contain credentials. Each request and redirect is validated against
+private and reserved addresses such as `localhost` and cloud metadata
+endpoints. On Node.js, resolved DNS addresses are validated at connect time to
+prevent DNS rebinding. On other runtimes, only the URL is validated, so restrict
+network egress at the platform level. A custom `fetch` must provide equivalent
+validation. See [Secure URL Fetching](/docs/advanced/secure-url-fetching).
+
+Fetched content is untrusted and can contain prompt injections. When an agent
+has access to private data, a model could also be instructed to send that data
+to another site, for example in a URL query string. Restrict fetching with
+`allowedDomains`, enable `requireUrlInUserMessage` so only URLs from user
+messages can be fetched, or require [tool approval](/docs/ai-sdk-core/tools-and-tool-calling#tool-execution-approval).
+
+`requireUrlInUserMessage` ignores URLs in tool results because the model can
+place arbitrary text there, for example through tool inputs that are reflected
+in outputs. As a result, the model cannot follow links from search results or
+fetched pages in this mode.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.150",
+  "version": "7.0.151",
   "type": "module",
   "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",
@@ -42,7 +42,7 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.123",
+    "@ai-sdk/gateway": "4.0.124",
     "@ai-sdk/provider": "4.0.33",
     "@ai-sdk/provider-utils": "5.0.67"
   },