feat(ai): change type of experimental_context from unknown to generic

.changeset/bright-glasses-happen.md

@@ -0,0 +1,6 @@
+---
+"@ai-sdk/provider-utils": major
+"ai": major
+---
+
+feat(ai): change type of experimental_context from unknown to generic

examples/ai-e2e-next/app/api/chat/human-in-the-loop/utils.ts

@@ -51,7 +51,7 @@ export async function processToolCalls<
   executeFunctions: {
     [K in keyof Tools & keyof ExecutableTools]?: (
       args: ExecutableTools[K] extends Tool<infer P> ? P : never,
-      context: ToolExecutionOptions,
+      context: ToolExecutionOptions<{}>,
     ) => Promise<any>;
   },
 ): Promise<HumanInTheLoopUIMessage[]> {
@@ -86,6 +86,7 @@ export async function processToolCalls<
           result = await toolInstance(part.input, {
             messages: await convertToModelMessages(messages),
             toolCallId: part.toolCallId,
+            experimental_context: {},
           });
         } else {
           result = 'Error: No execute function found on tool';

examples/ai-functions/src/generate-text/openai/tool-call-with-context.ts

@@ -5,26 +5,61 @@ import { run } from '../../lib/run';
 
 run(async () => {
   const result = await generateText({
-    model: openai('gpt-4o'),
+    model: openai('gpt-5-mini'),
     tools: {
       weather: tool({
         description: 'Get the weather in a location',
         inputSchema: z.object({
           location: z.string().describe('The location to get the weather for'),
         }),
-        execute: async ({ location }, { experimental_context: context }) => {
-          const typedContext = context as { weatherApiKey: string }; // or use type validation library
-
-          console.log(typedContext);
+        contextSchema: z.object({
+          weatherApiKey: z.string().describe('The API key for the weather API'),
+        }),
+        execute: async (
+          { location },
+          { experimental_context: { weatherApiKey } },
+        ) => {
+          console.log('weather tool api key:', weatherApiKey);
 
           return {
             location,
             temperature: 72 + Math.floor(Math.random() * 21) - 10,
           };
         },
       }),
+      calculator: tool({
+        description: 'Calculate mathematical expressions',
+        inputSchema: z.object({
+          expression: z
+            .string()
+            .describe('The mathematical expression to calculate'),
+        }),
+        contextSchema: z.object({
+          calculatorApiKey: z
+            .string()
+            .describe('The API key for the calculator API'),
+        }),
+        execute: async (
+          { expression },
+          { experimental_context: { calculatorApiKey } },
+        ) => {
+          console.log('calculator tool api key:', calculatorApiKey);
+          return {
+            expression,
+            result: eval(expression),
+          };
+        },
+      }),
+    },
+    experimental_context: {
+      weatherApiKey: 'weather-123',
+      calculatorApiKey: 'calculator-456',
+      somethingElse: 'other-context',
+    },
+    prepareStep: async ({ experimental_context: context }) => {
+      console.log('prepareStep context:', context);
+      return {};
     },
-    experimental_context: { weatherApiKey: '123' },
     prompt: 'What is the weather in San Francisco?',
   });
 

examples/ai-functions/src/lib/print-full-stream.ts

@@ -3,7 +3,7 @@ import { StreamTextResult } from 'ai';
 export async function printFullStream({
   result,
 }: {
-  result: StreamTextResult<any, any>;
+  result: StreamTextResult<any, any, any>;
 }) {
   for await (const chunk of result.fullStream) {
     switch (chunk.type) {

examples/ai-functions/src/lib/save-raw-chunks.ts

@@ -5,7 +5,7 @@ export async function saveRawChunks({
   result,
   filename,
 }: {
-  result: StreamTextResult<any, any>;
+  result: StreamTextResult<any, any, any>;
   filename: string;
 }) {
   const rawChunks: unknown[] = [];

examples/ai-functions/src/stream-text/openai/tool-call-with-context.ts

@@ -0,0 +1,68 @@
+import { openai } from '@ai-sdk/openai';
+import { streamText, tool } from 'ai';
+import { z } from 'zod';
+import { run } from '../../lib/run';
+import { printFullStream } from '../../lib/print-full-stream';
+
+run(async () => {
+  const result = streamText({
+    model: openai('gpt-5-mini'),
+    tools: {
+      weather: tool({
+        description: 'Get the weather in a location',
+        inputSchema: z.object({
+          location: z.string().describe('The location to get the weather for'),
+        }),
+        contextSchema: z.object({
+          weatherApiKey: z.string().describe('The API key for the weather API'),
+        }),
+        execute: async (
+          { location },
+          { experimental_context: { weatherApiKey } },
+        ) => {
+          console.log('weather tool api key:', weatherApiKey);
+
+          return {
+            location,
+            temperature: 72 + Math.floor(Math.random() * 21) - 10,
+          };
+        },
+      }),
+      calculator: tool({
+        description: 'Calculate mathematical expressions',
+        inputSchema: z.object({
+          expression: z
+            .string()
+            .describe('The mathematical expression to calculate'),
+        }),
+        contextSchema: z.object({
+          calculatorApiKey: z
+            .string()
+            .describe('The API key for the calculator API'),
+        }),
+        execute: async (
+          { expression },
+          { experimental_context: { calculatorApiKey } },
+        ) => {
+          console.log('calculator tool api key:', calculatorApiKey);
+          return {
+            expression,
+            result: eval(expression),
+          };
+        },
+      }),
+    },
+    experimental_context: {
+      weatherApiKey: 'weather-123',
+      calculatorApiKey: 'calculator-456',
+      somethingElse: 'other-context',
+    },
+    prepareStep: async ({ experimental_context: context }) => {
+      console.log('prepareStep context:', context);
+      return {};
+    },
+    prompt: 'What is the weather in San Francisco?',
+  });
+
+  await printFullStream({ result });
+});

examples/ai-functions/src/test/typed-context-2.ts

@@ -0,0 +1,92 @@
+import { FlexibleSchema } from 'ai';
+import { run } from '../lib/run';
+import { z } from 'zod';
+
+type Context = Record<string, unknown>;
+
+interface Tool<INPUT = any, CONTEXT extends Context = Context> {
+  inputSchema: FlexibleSchema<INPUT>;
+  contextSchema: FlexibleSchema<CONTEXT>;
+  execute: (input: NoInfer<INPUT>, context: NoInfer<CONTEXT>) => unknown;
+}
+
+function tool<INPUT, CONTEXT extends Context>(options: {
+  inputSchema: FlexibleSchema<INPUT>;
+  contextSchema: FlexibleSchema<CONTEXT>;
+  execute: (input: NoInfer<INPUT>, context: NoInfer<CONTEXT>) => unknown;
+}) {
+  return options;
+}
+
+type InferToolInput<TOOL extends Tool> =
+  TOOL extends Tool<infer INPUT, any> ? INPUT : never;
+type InferToolContext<TOOL extends Tool> =
+  TOOL extends Tool<any, infer CONTEXT> ? CONTEXT : never;
+
+export type ToolSet = Record<string, Tool<any, any>>;
+
+type UnionToIntersection<U> = (
+  U extends unknown ? (arg: U) => void : never
+) extends (arg: infer I) => void
+  ? I
+  : never;
+
+// should be a union of all the context types of the tools
+type InferToolSetContext<TOOLS extends ToolSet> = UnionToIntersection<
+  {
+    [K in keyof TOOLS]: InferToolContext<TOOLS[K]>;
+  }[keyof TOOLS]
+>;
+
+type ExpandedContext<TOOLS extends ToolSet> = InferToolSetContext<TOOLS> &
+  Context;
+
+function executeTool<
+  TOOLS extends ToolSet,
+  CONTEXT extends ExpandedContext<TOOLS>,
+>({
+  tools,
+  toolName,
+  input,
+  context,
+}: {
+  tools: TOOLS;
+  toolName: keyof TOOLS;
+  input: InferToolInput<TOOLS[typeof toolName]>;
+  context: CONTEXT;
+  prepareStep: (context: CONTEXT) => void;
+}) {
+  const tool = tools[toolName];
+  return tool.execute(input, context);
+}
+
+run(async () => {
+  const tool1 = tool({
+    inputSchema: z.object({ input1: z.string() }),
+    contextSchema: z.object({ context1: z.number() }),
+    execute: async ({ input1 }, { context1 }) => {
+      console.log(input1, context1);
+    },
+  });
+
+  const tool2 = tool({
+    inputSchema: z.object({ input2: z.number() }),
+    contextSchema: z.object({ context2: z.string() }),
+    execute: async ({ input2 }, { context2 }) => {
+      console.log(input2, context2);
+    },
+  });
+
+  executeTool({
+    tools: {
+      tool1,
+      tool2,
+    },
+    toolName: 'tool1',
+    input: { input1: 'Hello' },
+    context: { context1: 1, context2: 'world', somethingElse: 'context' },
+    prepareStep: context => {
+      console.log(context);
+    },
+  });
+});

examples/ai-functions/src/test/typed-context.ts

@@ -0,0 +1,42 @@
+import { run } from '../lib/run';
+
+interface Tool<CONTEXT> {
+  execute: (context: CONTEXT) => Promise<void>;
+}
+
+export type ToolSet<CONTEXT> = Record<string, Tool<CONTEXT>>;
+
+function executeTool<CONTEXT, TOOLS extends ToolSet<CONTEXT>>({
+  tools,
+  toolName,
+  context,
+}: {
+  tools: TOOLS;
+  toolName: keyof TOOLS;
+  context: CONTEXT;
+}) {
+  return tools[toolName].execute(context);
+}
+
+run(async () => {
+  const tool1: Tool<{ name: string }> = {
+    execute: async context => {
+      console.log(context);
+    },
+  };
+
+  const tool2: Tool<{ age: number }> = {
+    execute: async context => {
+      console.log(context);
+    },
+  };
+
+  executeTool({
+    tools: {
+      tool1,
+      tool2,
+    },
+    toolName: 'tool1',
+    context: { name: 'John', age: 30 },
+  });
+});

examples/mcp/src/image-content/client.ts

@@ -20,7 +20,10 @@ async function main() {
     const tool = tools['get-image'];
 
     console.log('Calling get-image tool...\n');
-    const result = await tool.execute!({}, { messages: [], toolCallId: '1' });
+    const result = await tool.execute!(
+      {},
+      { messages: [], toolCallId: '1', experimental_context: {} },
+    );
 
     console.log('Raw execute() result (MCP format):');
     console.log(JSON.stringify(result, null, 2));

examples/mcp/src/output-schema/client.ts

@@ -59,7 +59,7 @@ async function main() {
   const weatherTool = tools['get-weather'];
   const weatherResult = await weatherTool.execute(
     { location: 'New York' },
-    { messages: [], toolCallId: 'weather-1' },
+    { messages: [], toolCallId: 'weather-1', experimental_context: {} },
   );
 
   const weather = weatherResult as {
@@ -78,7 +78,7 @@ async function main() {
   const usersTool = tools['list-users'];
   const usersResult = await usersTool.execute(
     {},
-    { messages: [], toolCallId: 'users-1' },
+    { messages: [], toolCallId: 'users-1', experimental_context: {} },
   );
 
   const users = usersResult as {
@@ -96,7 +96,7 @@ async function main() {
   const echoTool = tools['echo'];
   const echoResult = await echoTool.execute(
     { message: 'Hello, MCP!' },
-    { messages: [], toolCallId: 'echo-1' },
+    { messages: [], toolCallId: 'echo-1', experimental_context: {} },
   );
 
   console.log('Raw result:', JSON.stringify(echoResult, null, 2));