refactoring: restructure Tool types (#14849)

lgrammel · web-flow · commit b6783dafbfbc · 2026-04-30T18:41:34.000+02:00
## Background

Different types of tools can have different available options. Currently
we expose options on tool types that do not support it, e.g. execute on
provider executed tools.

## Summary

Refactor the `Tool` type into a union of `FunctionTool`, `DynamicTool`,
`ProviderDefinedTool`, and `ProviderExecutedTool`. Expose the new types.
Add type tests.

The goal is to create a foundation for further refactoring and option
restrictions.

## Future Work

* restrict options available on specific tool types more
diff --git a/.changeset/stupid-lamps-brush.md b/.changeset/stupid-lamps-brush.md
@@ -0,0 +1,5 @@
+---
+"@ai-sdk/provider-utils": patch
+---
+
+refactoring: restructure Tool types
diff --git a/packages/openai/src/tool/local-shell.test-d.ts b/packages/openai/src/tool/local-shell.test-d.ts
@@ -5,11 +5,12 @@ import {
   type localShellInputSchema,
   type localShellOutputSchema,
 } from './local-shell';
+
 describe('local-shell tool type', () => {
   it('should have Tool type', () => {
     const localShellTool = localShell({});
 
-    expectTypeOf(localShellTool).toEqualTypeOf<
+    expectTypeOf(localShellTool).toExtend<
       Tool<
         InferSchema<typeof localShellInputSchema>,
         InferSchema<typeof localShellOutputSchema>,
diff --git a/packages/openai/src/tool/web-search.test-d.ts b/packages/openai/src/tool/web-search.test-d.ts
@@ -1,11 +1,12 @@
 import type { InferSchema, Tool } from '@ai-sdk/provider-utils';
 import { describe, expectTypeOf, it } from 'vitest';
 import { webSearch, type webSearchOutputSchema } from './web-search';
+
 describe('web-search tool type', () => {
   it('should have Tool type', () => {
     const webSearchTool = webSearch();
 
-    expectTypeOf(webSearchTool).toEqualTypeOf<
+    expectTypeOf(webSearchTool).toExtend<
       Tool<{}, InferSchema<typeof webSearchOutputSchema>, {}>
     >();
   });
diff --git a/packages/provider-utils/src/provider-defined-tool-factory.ts b/packages/provider-utils/src/provider-defined-tool-factory.ts
@@ -1,6 +1,7 @@
-import { tool, type Tool, type ToolExecuteFunction } from './types/tool';
+import { tool, type ProviderDefinedTool, type Tool } from './types/tool';
 import type { FlexibleSchema } from './schema';
 import type { Context } from './types/context';
+import type { ToolExecuteFunction } from './types/tool-execute-function';
 /**
  * A provider-defined tool is a tool for which the provider defines the input
  * and output schemas, but does not execute the tool.
@@ -18,7 +19,7 @@ export type ProviderDefinedToolFactory<
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
   },
-) => Tool<INPUT, OUTPUT, CONTEXT>;
+) => ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>;
 
 export function createProviderDefinedToolFactory<
   INPUT,
@@ -48,7 +49,7 @@ export function createProviderDefinedToolFactory<
     onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
-  }): Tool<INPUT, OUTPUT, CONTEXT> =>
+  }): ProviderDefinedTool<INPUT, OUTPUT, CONTEXT> =>
     tool({
       type: 'provider',
       isProviderExecuted: false,
@@ -62,7 +63,7 @@ export function createProviderDefinedToolFactory<
       onInputStart,
       onInputDelta,
       onInputAvailable,
-    });
+    }) as ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>;
 }
 
 export type ProviderDefinedToolFactoryWithOutputSchema<
@@ -79,7 +80,7 @@ export type ProviderDefinedToolFactoryWithOutputSchema<
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
   },
-) => Tool<INPUT, OUTPUT, CONTEXT>;
+) => ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>;
 
 export function createProviderDefinedToolFactoryWithOutputSchema<
   INPUT,
@@ -110,7 +111,7 @@ export function createProviderDefinedToolFactoryWithOutputSchema<
     onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
-  }): Tool<INPUT, OUTPUT, CONTEXT> =>
+  }): ProviderDefinedTool<INPUT, OUTPUT, CONTEXT> =>
     tool({
       type: 'provider',
       isProviderExecuted: false,
@@ -124,5 +125,5 @@ export function createProviderDefinedToolFactoryWithOutputSchema<
       onInputStart,
       onInputDelta,
       onInputAvailable,
-    });
+    }) as ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>;
 }
diff --git a/packages/provider-utils/src/provider-executed-tool-factory.ts b/packages/provider-utils/src/provider-executed-tool-factory.ts
@@ -1,6 +1,6 @@
 import type { FlexibleSchema } from './schema';
 import type { Context } from './types/context';
-import { tool, type Tool } from './types/tool';
+import { tool, type ProviderExecutedTool, type Tool } from './types/tool';
 /**
  * A provider-executed tool is a tool for which the provider executes the tool.
  */
@@ -15,7 +15,7 @@ export type ProviderExecutedToolFactory<
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
   },
-) => Tool<INPUT, OUTPUT, CONTEXT>;
+) => ProviderExecutedTool<INPUT, OUTPUT, CONTEXT>;
 
 export function createProviderExecutedToolFactory<
   INPUT,
@@ -53,7 +53,7 @@ export function createProviderExecutedToolFactory<
     onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
-  }): Tool<INPUT, OUTPUT, CONTEXT> =>
+  }): ProviderExecutedTool<INPUT, OUTPUT, CONTEXT> =>
     tool({
       type: 'provider',
       isProviderExecuted: true,
@@ -65,5 +65,5 @@ export function createProviderExecutedToolFactory<
       onInputDelta,
       onInputAvailable,
       supportsDeferredResults,
-    });
+    }) as ProviderExecutedTool<INPUT, OUTPUT, CONTEXT>;
 }
diff --git a/packages/provider-utils/src/types/execute-tool.test.ts b/packages/provider-utils/src/types/execute-tool.test.ts
@@ -2,7 +2,8 @@ import { describe, expect, it } from 'vitest';
 import { z } from 'zod/v4';
 import { executeTool } from './execute-tool';
 import type { ExecutableTool } from './executable-tool';
-import { tool, type ToolExecutionOptions } from './tool';
+import { tool } from './tool';
+import type { ToolExecutionOptions } from './tool-execute-function';
 describe('executeTool', () => {
   it('yields a single final output for non-streaming tools', async () => {
     const weatherTool = tool({
diff --git a/packages/provider-utils/src/types/execute-tool.ts b/packages/provider-utils/src/types/execute-tool.ts
@@ -3,7 +3,8 @@ import type { ExecutableTool } from './executable-tool';
 import type { InferToolContext } from './infer-tool-context';
 import type { InferToolInput } from './infer-tool-input';
 import type { InferToolOutput } from './infer-tool-output';
-import type { Tool, ToolExecutionOptions } from './tool';
+import type { Tool } from './tool';
+import type { ToolExecutionOptions } from './tool-execute-function';
 
 /**
  * Executes a tool function and normalizes its results into a stream of outputs.
diff --git a/packages/provider-utils/src/types/index.ts b/packages/provider-utils/src/types/index.ts
@@ -36,11 +36,17 @@ export type { SystemModelMessage } from './system-model-message';
 export {
   dynamicTool,
   tool,
+  type DynamicTool,
+  type FunctionTool,
+  type ProviderDefinedTool,
+  type ProviderExecutedTool,
   type Tool,
-  type ToolExecuteFunction,
-  type ToolExecutionOptions,
-  type ToolNeedsApprovalFunction,
 } from './tool';
+export type {
+  ToolExecuteFunction,
+  ToolExecutionOptions,
+} from './tool-execute-function';
+export type { ToolNeedsApprovalFunction } from './tool-needs-approval-function';
 export type { ToolSet } from './tool-set';
 export type { ToolApprovalRequest } from './tool-approval-request';
 export type { ToolApprovalResponse } from './tool-approval-response';
diff --git a/packages/provider-utils/src/types/never-optional.test-d.ts b/packages/provider-utils/src/types/never-optional.test-d.ts
@@ -0,0 +1,60 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { NeverOptional } from './never-optional';
+
+describe('NeverOptional', () => {
+  type Properties = {
+    required: string;
+    optional?: number;
+    readonly readonlyProperty: boolean;
+  };
+
+  it('preserves the original properties for known types', () => {
+    expectTypeOf<
+      NeverOptional<string, Properties>
+    >().toEqualTypeOf<Properties>();
+    expectTypeOf<
+      NeverOptional<unknown, Properties>
+    >().toEqualTypeOf<Properties>();
+    expectTypeOf<
+      NeverOptional<string | undefined, Properties>
+    >().toEqualTypeOf<Properties>();
+  });
+
+  it('makes the properties optional when the condition type is any', () => {
+    expectTypeOf<NeverOptional<any, Properties>>().toEqualTypeOf<
+      Partial<Properties>
+    >();
+
+    expectTypeOf<NeverOptional<any, Properties>>().toMatchTypeOf<{
+      required?: string;
+      optional?: number;
+      readonly readonlyProperty?: boolean;
+    }>();
+  });
+
+  it('allows only undefined optional properties when the condition type is never', () => {
+    expectTypeOf<NeverOptional<never, Properties>>().toEqualTypeOf<{
+      required?: undefined;
+      optional?: undefined;
+      readonlyProperty?: undefined;
+    }>();
+
+    expectTypeOf<{}>().toMatchTypeOf<NeverOptional<never, Properties>>();
+    expectTypeOf<{ required: undefined }>().toMatchTypeOf<
+      NeverOptional<never, Properties>
+    >();
+    expectTypeOf<{ optional: undefined }>().toMatchTypeOf<
+      NeverOptional<never, Properties>
+    >();
+
+    expectTypeOf<{ required: string }>().not.toMatchTypeOf<
+      NeverOptional<never, Properties>
+    >();
+    expectTypeOf<{ optional: number }>().not.toMatchTypeOf<
+      NeverOptional<never, Properties>
+    >();
+    expectTypeOf<{ readonlyProperty: boolean }>().not.toMatchTypeOf<
+      NeverOptional<never, Properties>
+    >();
+  });
+});
diff --git a/packages/provider-utils/src/types/never-optional.ts b/packages/provider-utils/src/types/never-optional.ts
@@ -0,0 +1,7 @@
+// 0 extends 1 & N checks for any
+// [N] extends [never] checks for never
+export type NeverOptional<N, T> = 0 extends 1 & N
+  ? Partial<T>
+  : [N] extends [never]
+    ? Partial<Record<keyof T, undefined>>
+    : T;
diff --git a/packages/provider-utils/src/types/tool-execute-function.test-d.ts b/packages/provider-utils/src/types/tool-execute-function.test-d.ts
@@ -0,0 +1,32 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { Context } from './context';
+import type { ModelMessage } from './model-message';
+import type {
+  ToolExecuteFunction,
+  ToolExecutionOptions,
+} from './tool-execute-function';
+
+describe('tool execute function types', () => {
+  it('should include execution metadata and typed context', () => {
+    expectTypeOf<ToolExecutionOptions<{ requestId: string }>>().toEqualTypeOf<{
+      toolCallId: string;
+      messages: ModelMessage[];
+      abortSignal?: AbortSignal;
+      context: { requestId: string };
+    }>();
+  });
+
+  it('should type the input, output, and execution options', () => {
+    expectTypeOf<
+      ToolExecuteFunction<{ city: string }, { temperature: number }, Context>
+    >().toEqualTypeOf<
+      (
+        input: { city: string },
+        options: ToolExecutionOptions<Context>,
+      ) =>
+        | AsyncIterable<{ temperature: number }>
+        | PromiseLike<{ temperature: number }>
+        | { temperature: number }
+    >();
+  });
+});
diff --git a/packages/provider-utils/src/types/tool-execute-function.ts b/packages/provider-utils/src/types/tool-execute-function.ts
@@ -0,0 +1,50 @@
+import type { Context } from './context';
+import type { ModelMessage } from './model-message';
+
+/**
+ * Additional options that are sent into each tool execution.
+ */
+export interface ToolExecutionOptions<
+  CONTEXT extends Context | unknown | never,
+> {
+  /**
+   * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
+   */
+  toolCallId: string;
+
+  /**
+   * Messages that were sent to the language model to initiate the response that contained the tool call.
+   * The messages **do not** include the system prompt nor the assistant response that contained the tool call.
+   */
+  messages: ModelMessage[];
+
+  /**
+   * An optional abort signal that indicates that the overall operation should be aborted.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Tool context as defined by the tool's context schema.
+   * The tool context is specific to the tool and is passed to the tool execution.
+   *
+   * Treat the context object as immutable inside tools.
+   * Mutating the context object can lead to race conditions and unexpected results
+   * when tools are called in parallel.
+   *
+   * If you need to mutate the context, analyze the tool calls and results
+   * in `prepareStep` and update it there.
+   */
+  context: CONTEXT;
+}
+
+/**
+ * Function that executes the tool and returns either a single result or a stream of results.
+ */
+export type ToolExecuteFunction<
+  INPUT,
+  OUTPUT,
+  CONTEXT extends Context | unknown | never,
+> = (
+  input: INPUT,
+  options: ToolExecutionOptions<CONTEXT>,
+) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
diff --git a/packages/provider-utils/src/types/tool-needs-approval-function.test-d.ts b/packages/provider-utils/src/types/tool-needs-approval-function.test-d.ts
@@ -0,0 +1,20 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { ModelMessage } from './model-message';
+import type { ToolNeedsApprovalFunction } from './tool-needs-approval-function';
+
+describe('tool needs approval function type', () => {
+  it('should type the input, approval metadata, and context', () => {
+    expectTypeOf<
+      ToolNeedsApprovalFunction<{ city: string }, { requestId: string }>
+    >().toEqualTypeOf<
+      (
+        input: { city: string },
+        options: {
+          toolCallId: string;
+          messages: ModelMessage[];
+          context: { requestId: string };
+        },
+      ) => boolean | PromiseLike<boolean>
+    >();
+  });
+});
diff --git a/packages/provider-utils/src/types/tool-needs-approval-function.ts b/packages/provider-utils/src/types/tool-needs-approval-function.ts
@@ -0,0 +1,39 @@
+import type { Context } from './context';
+import type { ModelMessage } from './model-message';
+
+/**
+ * Function that is called to determine if the tool needs approval before it can be executed.
+ *
+ * @deprecated Tool approval is handled on a `generateText` / `streamText` level now.
+ */
+export type ToolNeedsApprovalFunction<
+  INPUT,
+  CONTEXT extends Context | unknown | never,
+> = (
+  input: INPUT,
+  options: {
+    /**
+     * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
+     */
+    toolCallId: string;
+
+    /**
+     * Messages that were sent to the language model to initiate the response that contained the tool call.
+     * The messages **do not** include the system prompt nor the assistant response that contained the tool call.
+     */
+    messages: ModelMessage[];
+
+    /**
+     * Tool context as defined by the tool's context schema.
+     * The tool context is specific to the tool and is passed to the tool execution.
+     *
+     * Treat the context object as immutable inside tools.
+     * Mutating the context object can lead to race conditions and unexpected results
+     * when tools are called in parallel.
+     *
+     * If you need to mutate the context, analyze the tool calls and results
+     * in `prepareStep` and update it there.
+     */
+    context: CONTEXT;
+  },
+) => boolean | PromiseLike<boolean>;
diff --git a/packages/provider-utils/src/types/tool.test-d.ts b/packages/provider-utils/src/types/tool.test-d.ts
diff --git a/packages/provider-utils/src/types/tool.ts b/packages/provider-utils/src/types/tool.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@ai-sdk/provider-utils": patch
 +---
++
 +refactoring: restructure Tool types