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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @ai-sdk/provider-utils
 
+## 5.0.0-canary.44
+
+### Patch Changes
+
+- 6c93e36: feat(provider-utils): add `spawnCommand` method to `Experimental_Sandbox` to allow for detached command execution
+- f617ac2: feat(provider-utils): narrow `tool()` return type to `ExecutableTool<...>` when `execute` is provided
+
 ## 5.0.0-canary.43
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1171,6 +1171,17 @@ declare const postToApi: <T>({ url, headers, body, successfulResponseHandler, fa
  */
 type Context = Record<string, unknown>;
 
+/**
+ * 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.
+ */
+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;
 
 /**
@@ -1310,7 +1321,7 @@ type Experimental_Sandbox = {
     /**
      * Run a command in the sandbox.
      */
-    readonly runCommand: (options: {
+    readonly run: (options: {
         /**
          * Command to execute in the sandbox.
          */
@@ -1461,6 +1472,55 @@ type Experimental_Sandbox = {
          */
         abortSignal?: AbortSignal;
     }) => 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: {
+        /**
+         * Command to execute in the sandbox.
+         */
+        command: string;
+        /**
+         * Working directory to execute the command in.
+         */
+        workingDirectory?: string;
+        /**
+         * Signal that can be used to abort the process. When aborted, the process
+         * is killed and `wait()` rejects with the abort reason.
+         */
+        abortSignal?: AbortSignal;
+    }) => PromiseLike<Experimental_SandboxProcess>;
+};
+/**
+ * Handle to a long-running process started via `Experimental_Sandbox.spawn`.
+ */
+type Experimental_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>;
 };
 
 /**
@@ -1768,7 +1828,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>;
@@ -2099,17 +2166,6 @@ 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.
- */
-type ExecutableTool<TOOL extends Tool = Tool> = TOOL & {
-    execute: NonNullable<TOOL['execute']>;
-};
-/**
- * Checks whether a tool exposes an execute function.
- */
-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.
@@ -2261,4 +2317,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, 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 };
+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 Experimental_SandboxProcess, 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

@@ -876,7 +876,7 @@ function withUserAgentSuffix(headers, ...userAgentSuffixParts) {
 }
 
 // src/version.ts
-var VERSION = true ? "5.0.0-canary.43" : "0.0.0-test";
+var VERSION = true ? "5.0.0-canary.44" : "0.0.0-test";
 
 // src/get-from-api.ts
 var getOriginalFetch = () => globalThis.fetch;