@ai-sdk/provider-utils 5.0.0-canary.40 → 5.0.0-canary.43

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @ai-sdk/provider-utils
 
+## 5.0.0-canary.43
+
+### Patch Changes
+
+- 7fc6bd6: Raise minimum supported Node.js version to 22. Supported versions: 22, 24, and 26.
+- Updated dependencies [7fc6bd6]
+  - @ai-sdk/provider@4.0.0-canary.17
+
+## 5.0.0-canary.42
+
+### Patch Changes
+
+- a6617c5: feat(provider-utils): add `readFile` and `writeFile` plus convenience wrappers to `Experimental_Sandbox` abstraction
+
+## 5.0.0-canary.41
+
+### Patch Changes
+
+- 28dfa06: fix: support tools with optional context
+- e93fa91: rename Sandbox.executeCommand to Sandbox.runCommand
+
 ## 5.0.0-canary.40
 
 ### Patch Changes

package/dist/index.d.ts

@@ -738,6 +738,21 @@ declare class DownloadError extends AISDKError {
     static isInstance(error: unknown): error is DownloadError;
 }
 
+/**
+ * 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.
  *
@@ -1283,7 +1298,7 @@ type UserContent = string | Array<TextPart | ImagePart | FilePart>;
 type ModelMessage = SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage;
 
 /**
- * Sandbox environment that can execute commands.
+ * Sandbox environment that can execute commands and read/write files.
  */
 type Experimental_Sandbox = {
     /**
@@ -1293,9 +1308,9 @@ type Experimental_Sandbox = {
      */
     readonly description: string;
     /**
-     * Execute a command in the sandbox.
+     * Run a command in the sandbox.
      */
-    readonly executeCommand: (options: {
+    readonly runCommand: (options: {
         /**
          * Command to execute in the sandbox.
          */
@@ -1322,6 +1337,130 @@ type Experimental_Sandbox = {
          */
         stderr: 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: {
+        /**
+         * Path of the file to read.
+         */
+        path: string;
+        /**
+         * Signal that can be used to abort the read.
+         */
+        abortSignal?: AbortSignal;
+    }) => 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: {
+        /**
+         * Path of the file to read.
+         */
+        path: string;
+        /**
+         * Signal that can be used to abort the read.
+         */
+        abortSignal?: AbortSignal;
+    }) => 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: {
+        /**
+         * Path of the file to read.
+         */
+        path: string;
+        /**
+         * 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;
+        /**
+         * Signal that can be used to abort the read.
+         */
+        abortSignal?: AbortSignal;
+    }) => 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: {
+        /**
+         * Path of the file to write.
+         */
+        path: string;
+        /**
+         * Stream of bytes to write.
+         */
+        content: ReadableStream<Uint8Array>;
+        /**
+         * Signal that can be used to abort the write.
+         */
+        abortSignal?: AbortSignal;
+    }) => PromiseLike<void>;
+    /**
+     * Write one file to the sandbox from raw bytes. Creates parent directories
+     * recursively and overwrites any existing file.
+     */
+    readonly writeBinaryFile: (options: {
+        /**
+         * Path of the file to write.
+         */
+        path: string;
+        /**
+         * Raw bytes to write.
+         */
+        content: Uint8Array;
+        /**
+         * Signal that can be used to abort the write.
+         */
+        abortSignal?: AbortSignal;
+    }) => 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: {
+        /**
+         * Path of the file to write.
+         */
+        path: string;
+        /**
+         * Text content to write.
+         */
+        content: string;
+        /**
+         * Text encoding used to encode the string to bytes. Defaults to `"utf-8"`.
+         */
+        encoding?: string;
+        /**
+         * Signal that can be used to abort the write.
+         */
+        abortSignal?: AbortSignal;
+    }) => PromiseLike<void>;
 };
 
 /**
@@ -1971,10 +2110,25 @@ type ExecutableTool<TOOL extends Tool = Tool> = TOOL & {
  */
 declare function isExecutableTool<TOOL extends Tool>(tool: TOOL | undefined): tool is ExecutableTool<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.
  */
-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.
@@ -2017,16 +2171,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.
@@ -2087,4 +2261,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 Experimental_Sandbox, 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, 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 Experimental_Sandbox, 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, 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, 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 };

package/dist/index.js

@@ -701,6 +701,20 @@ async function downloadBlob(url, options) {
   }
 }
 
+// src/extract-lines.ts
+function extractLines({
+  text,
+  startLine,
+  endLine
+}) {
+  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 != null ? startLine : 1) - 1;
+  const end = Math.min(lines.length, endLine != null ? endLine : lines.length);
+  return lines.slice(start, end).join(lineEnding);
+}
+
 // src/extract-response-headers.ts
 function extractResponseHeaders(response) {
   return Object.fromEntries([...response.headers]);
@@ -862,7 +876,7 @@ function withUserAgentSuffix(headers, ...userAgentSuffixParts) {
 }
 
 // src/version.ts
-var VERSION = true ? "5.0.0-canary.40" : "0.0.0-test";
+var VERSION = true ? "5.0.0-canary.43" : "0.0.0-test";
 
 // src/get-from-api.ts
 var getOriginalFetch = () => globalThis.fetch;
@@ -3349,6 +3363,7 @@ export {
   downloadBlob,
   dynamicTool,
   executeTool,
+  extractLines,
   extractResponseHeaders,
   filterNullable,
   generateId,