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

package/src/types/sandbox.ts

@@ -0,0 +1,217 @@
+/**
+ * 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.
+ */
+export 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`.
+ */
+export 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>;
+};

package/src/types/tool-approval-request.ts

@@ -20,4 +20,10 @@ export 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;
 };

package/src/types/tool-execute-function.ts

@@ -1,5 +1,6 @@
 import type { Context } from './context';
 import type { ModelMessage } from './model-message';
+import type { SandboxSession } from './sandbox';
 
 /**
  * Additional options that are sent into each tool execution.
@@ -35,6 +36,11 @@ export interface ToolExecutionOptions<
    * in `prepareStep` and update it there.
    */
   context: CONTEXT;
+
+  /**
+   * The sandbox environment that the tool is operating in.
+   */
+  experimental_sandbox?: SandboxSession;
 }
 
 /**

package/src/types/tool.ts

@@ -1,15 +1,16 @@
-import type { JSONValue, SharedV4ProviderMetadata } from '@ai-sdk/provider';
+import type { JSONValue, JSONObject } from '@ai-sdk/provider';
 import type { FlexibleSchema } from '../schema';
 import type { ToolResultOutput } from './content-part';
 import type { Context } from './context';
+import type { ExecutableTool } from './executable-tool';
 import type { NeverOptional } from './never-optional';
 import type { ProviderOptions } from './provider-options';
-import type { SensitiveContext } from './sensitive-context';
 import type {
   ToolExecuteFunction,
   ToolExecutionOptions,
 } from './tool-execute-function';
 import type { ToolNeedsApprovalFunction } from './tool-needs-approval-function';
+import type { SandboxSession } from './sandbox';
 
 /**
  * Helper type to determine the outputSchema and execute function properties of a tool.
@@ -59,6 +60,8 @@ type BaseTool<
 > = {
   /**
    * An optional title of the tool.
+   *
+   * @deprecated Use `providerMetadata` for source-specific tool display metadata.
    */
   title?: string;
 
@@ -74,11 +77,11 @@ type BaseTool<
    *
    * 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.
@@ -96,12 +99,6 @@ type BaseTool<
    */
   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.
    *
@@ -180,10 +177,21 @@ type BaseFunctionTool<
   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.
@@ -208,7 +216,7 @@ type BaseFunctionTool<
 };
 
 /**
- * Tool with user-defined input and output schemas.
+ * Tool with user-defined input and output schemas that is executed by the AI SDK.
  */
 export type FunctionTool<
   INPUT extends JSONValue | unknown | never = any,
@@ -219,8 +227,10 @@ export type FunctionTool<
 };
 
 /**
- * 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.
  */
 export type DynamicTool<
   INPUT extends JSONValue | unknown | never = any,
@@ -259,6 +269,8 @@ type BaseProviderTool<
 /**
  * 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.
  */
 export type ProviderDefinedTool<
   INPUT extends JSONValue | unknown | never = any,
@@ -277,6 +289,8 @@ export type ProviderDefinedTool<
 /**
  * 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.
  */
 export type ProviderExecutedTool<
   INPUT extends JSONValue | unknown | never = any,
@@ -325,8 +339,20 @@ export type Tool<
  * 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.
  */
-// Note: overload order is important for auto-completion
+// Note: overload order is important for auto-completion.
+// The "with execute" overload comes first so calls that include an
+// `execute` function get the narrowed return type. Calls without
+// `execute` fall through to the overloads below.
+export function tool<INPUT, OUTPUT, CONTEXT extends Context>(
+  tool: Tool<INPUT, OUTPUT, CONTEXT> & {
+    execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
+  },
+): ExecutableTool<Tool<INPUT, OUTPUT, CONTEXT>>;
 export function tool<INPUT, OUTPUT, CONTEXT extends Context>(
   tool: Tool<INPUT, OUTPUT, CONTEXT>,
 ): Tool<INPUT, OUTPUT, CONTEXT>;

package/src/validate-download-url.ts

@@ -4,6 +4,10 @@ import { DownloadError } from './download-error';
  * 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.
  */
@@ -31,7 +35,9 @@ export function validateDownloadUrl(url: string): void {
     });
   }
 
-  const hostname = parsed.hostname;
+  // Strip a trailing dot so a fully-qualified name like `localhost.` (which resolves
+  // identically to `localhost`) cannot bypass the hostname blocklist below.
+  const hostname = parsed.hostname.toLowerCase().replace(/\.+$/, '');
 
   // Block empty hostname
   if (!hostname) {
@@ -90,59 +96,135 @@ function isIPv4(hostname: string): boolean {
 
 function isPrivateIPv4(ip: string): boolean {
   const parts = ip.split('.').map(Number);
-  const [a, b] = parts;
+  const [a, b, c] = parts;
 
   // 0.0.0.0/8
   if (a === 0) return true;
   // 10.0.0.0/8
   if (a === 10) return true;
+  // 100.64.0.0/10 (CGNAT, used by some cloud providers for internal traffic)
+  if (a === 100 && b >= 64 && b <= 127) return true;
   // 127.0.0.0/8
   if (a === 127) return true;
   // 169.254.0.0/16
   if (a === 169 && b === 254) return true;
   // 172.16.0.0/12
   if (a === 172 && b >= 16 && b <= 31) return true;
+  // 192.0.0.0/24 (IETF protocol assignments)
+  if (a === 192 && b === 0 && c === 0) return true;
   // 192.168.0.0/16
   if (a === 192 && b === 168) return true;
+  // 198.18.0.0/15 (benchmarking)
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  // 240.0.0.0/4 (reserved, includes 255.255.255.255 broadcast)
+  if (a >= 240) return true;
 
   return false;
 }
 
-function isPrivateIPv6(ip: string): boolean {
-  const normalized = ip.toLowerCase();
-
-  // ::1 (loopback)
-  if (normalized === '::1') return true;
-  // :: (unspecified)
-  if (normalized === '::') return true;
-
-  // Check for IPv4-mapped addresses (::ffff:x.x.x.x or ::ffff:HHHH:HHHH)
-  if (normalized.startsWith('::ffff:')) {
-    const mappedPart = normalized.slice(7);
-    // Dotted-decimal form: ::ffff:127.0.0.1
-    if (isIPv4(mappedPart)) {
-      return isPrivateIPv4(mappedPart);
-    }
-    // Hex form: ::ffff:7f00:1 (URL parser normalizes to this)
-    const hexParts = mappedPart.split(':');
-    if (hexParts.length === 2) {
-      const high = parseInt(hexParts[0], 16);
-      const low = parseInt(hexParts[1], 16);
-      if (!isNaN(high) && !isNaN(low)) {
-        const a = (high >> 8) & 0xff;
-        const b = high & 0xff;
-        const c = (low >> 8) & 0xff;
-        const d = low & 0xff;
-        return isPrivateIPv4(`${a}.${b}.${c}.${d}`);
+/**
+ * Expands an IPv6 address string into its 8 16-bit groups, handling `::`
+ * compression and an optional dotted-decimal IPv4 tail (e.g. `::ffff:127.0.0.1`).
+ *
+ * @returns the 8 groups, or null if the input is not a parseable IPv6 address.
+ */
+function parseIPv6(ip: string): number[] | null {
+  // Strip an optional zone id (e.g. `fe80::1%eth0`).
+  let address = ip.toLowerCase();
+  const zoneIndex = address.indexOf('%');
+  if (zoneIndex !== -1) {
+    address = address.slice(0, zoneIndex);
+  }
+
+  // At most one `::` compression marker is allowed.
+  const halves = address.split('::');
+  if (halves.length > 2) return null;
+
+  const toGroups = (segment: string): number[] | null => {
+    if (segment === '') return [];
+    const groups: number[] = [];
+    const parts = segment.split(':');
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      // A dotted-decimal IPv4 tail is only valid as the final part.
+      if (part.includes('.')) {
+        if (i !== parts.length - 1 || !isIPv4(part)) return null;
+        const [a, b, c, d] = part.split('.').map(Number);
+        groups.push((a << 8) | b, (c << 8) | d);
+        continue;
       }
+      if (!/^[0-9a-f]{1,4}$/.test(part)) return null;
+      groups.push(parseInt(part, 16));
     }
+    return groups;
+  };
+
+  const head = toGroups(halves[0]);
+  if (head === null) return null;
+
+  if (halves.length === 2) {
+    const tail = toGroups(halves[1]);
+    if (tail === null) return null;
+    const fill = 8 - head.length - tail.length;
+    if (fill < 0) return null;
+    return [...head, ...new Array<number>(fill).fill(0), ...tail];
   }
 
-  // fc00::/7 (unique local addresses - fc00:: and fd00::)
-  if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true;
+  // No `::` compression: the address must contain exactly 8 groups.
+  return head.length === 8 ? head : null;
+}
+
+function isPrivateIPv6(ip: string): boolean {
+  const groups = parseIPv6(ip);
+
+  // Fail closed: if the address cannot be parsed, treat it as unsafe.
+  if (groups === null) return true;
+
+  const topZero = (count: number) =>
+    groups.slice(0, count).every(group => group === 0);
+
+  // ::1 (loopback) and :: (unspecified)
+  if (topZero(7) && (groups[7] === 0 || groups[7] === 1)) return true;
+
+  // fc00::/7 (unique local addresses)
+  if ((groups[0] & 0xfe00) === 0xfc00) return true;
 
   // fe80::/10 (link-local)
-  if (normalized.startsWith('fe80')) return true;
+  if ((groups[0] & 0xffc0) === 0xfe80) return true;
+
+  // fec0::/10 (site-local, deprecated but still routable internally)
+  if ((groups[0] & 0xffc0) === 0xfec0) return true;
+
+  // ff00::/8 (multicast)
+  if ((groups[0] & 0xff00) === 0xff00) return true;
+
+  // Addresses that embed an IPv4 address in their last 32 bits. For these we
+  // extract the embedded IPv4 and reuse the IPv4 private-range checks, so that
+  // e.g. ::ffff:127.0.0.1 or 64:ff9b::169.254.169.254 are blocked.
+  const embedsIPv4 =
+    // ::/96 — IPv4-compatible (deprecated)
+    topZero(6) ||
+    // ::ffff:0:0/96 — IPv4-mapped (ffff in group 5)
+    (topZero(5) && groups[5] === 0xffff) ||
+    // ::ffff:0:0/96 — IPv4-translated form (ffff in group 4, group 5 zero)
+    (topZero(4) && groups[4] === 0xffff && groups[5] === 0) ||
+    // 64:ff9b::/96 — NAT64 well-known prefix
+    (groups[0] === 0x0064 &&
+      groups[1] === 0xff9b &&
+      groups[2] === 0 &&
+      groups[3] === 0 &&
+      groups[4] === 0 &&
+      groups[5] === 0) ||
+    // 64:ff9b:1::/48 — NAT64 local-use prefix
+    (groups[0] === 0x0064 && groups[1] === 0xff9b && groups[2] === 0x0001);
+
+  if (embedsIPv4) {
+    const a = (groups[6] >> 8) & 0xff;
+    const b = groups[6] & 0xff;
+    const c = (groups[7] >> 8) & 0xff;
+    const d = groups[7] & 0xff;
+    return isPrivateIPv4(`${a}.${b}.${c}.${d}`);
+  }
 
   return false;
 }

package/src/types/sensitive-context.ts

@@ -1,9 +0,0 @@
-import type { Context } from './context';
-
-/**
- * Top-level context properties that contain sensitive data and should be
- * excluded from telemetry.
- */
-export type SensitiveContext<CONTEXT extends Context | unknown | never> =
-  | { [KEY in keyof CONTEXT]?: boolean }
-  | undefined;