@convex-dev/agent 0.6.4 → 0.7.0-alpha.0

package/dist/{client → vercel}/index.d.ts

@@ -1,31 +1,38 @@
+/**
+ * Internal AI SDK implementation for the Agent API.
+ *
+ * Consumers continue to import this API from `@convex-dev/agent`. A public
+ * `@convex-dev/agent/vercel` entry point is intentionally deferred until its
+ * provider-adapter API is defined.
+ */
 import type { JSONValue } from "@ai-sdk/provider";
-import type { FlexibleSchema, IdGenerator, InferSchema } from "@ai-sdk/provider-utils";
-import type { CallSettings, GenerateObjectResult, GenerateTextResult, LanguageModel, ModelMessage, StepResult, StopCondition, StreamTextResult, ToolSet } from "ai";
+import type { Context, FlexibleSchema, IdGenerator, InferSchema } from "@ai-sdk/provider-utils";
+import type { GenerateObjectResult, GenerateTextResult, LanguageModel, Instructions, ModelMessage, Output as AISDKOutput, StepResult, StopCondition, StreamTextResult, ToolSet } from "ai";
 import { streamObject } from "ai";
 import { type GenericDataModel, type PaginationOptions, type PaginationResult } from "convex/server";
 import type { threadFieldsSupportingPatch } from "../component/threads.js";
 import { type VectorDimension } from "../component/vector/tables.js";
 import { type Message, type MessageDoc, type MessageStatus, type MessageWithMetadata, type ProviderMetadata, type StreamArgs, type ThreadDoc } from "../validators.js";
-import { type SaveMessageArgs, type SaveMessagesArgs } from "./messages.js";
-import { type StreamingOptions } from "./streaming.js";
-import type { ActionCtx, AgentComponent, Config, ContextOptions, GenerateObjectArgs, GenerationOutputMetadata, MaybeCustomCtx, ObjectMode, Options, RawRequestResponseHandler, MutationCtx, StorageOptions, StreamingTextArgs, StreamObjectArgs, SyncStreamsReturnValue, TextArgs, Thread, UsageHandler, QueryCtx, AgentPrompt, Output } from "./types.js";
-import { hasSuccessfulToolCall } from "./utils.js";
-export { stepCountIs } from "ai";
+import { type SaveMessageArgs, type SaveMessagesArgs } from "./client/messages.js";
+import { type StreamingOptions } from "./client/streaming.js";
+import type { ActionCtx, AgentComponent, Config, ContextOptions, GenerateObjectArgs, GenerationOutputMetadata, MaybeCustomCtx, ObjectMode, Options, RawRequestResponseHandler, MutationCtx, StorageOptions, StreamingTextArgs, StreamObjectArgs, SyncStreamsReturnValue, TextArgs, Thread, UsageHandler, QueryCtx, AgentPrompt, AgentCallSettings } from "./client/types.js";
+import { hasSuccessfulToolCall } from "./client/utils.js";
+export { isStepCount, stepCountIs } from "ai";
 export { hasSuccessfulToolCall };
-export { docsToModelMessages, toModelMessage, toModelMessage as deserializeMessage, guessMimeType, serializeDataOrUrl, serializeMessage, toUIFilePart, } from "../mapping.js";
+export { docsToModelMessages, toModelMessage, toModelMessage as deserializeMessage, guessMimeType, serializeDataOrUrl, serializeMessage, toUIFilePart, } from "./mapping.js";
 export { extractText, isTool, sorted } from "../shared.js";
 export { vAssistantMessage, vContent, vContextOptions, vMessage, vMessageDoc, vPaginationResult, vProviderMetadata, vSource, vStorageOptions, vStreamArgs, vSystemMessage, vThreadDoc, vToolMessage, vUsage, vUserMessage, type Message, type MessageDoc, type SourcePart, type ThreadDoc, type Usage, } from "../validators.js";
-export { createTool, type ToolCtx } from "./createTool.js";
-export { definePlaygroundAPI, type AgentsFn, type PlaygroundAPI, } from "./definePlaygroundAPI.js";
-export { getFile, storeFile } from "./files.js";
-export { listMessages, listUIMessages, saveMessage, saveMessages, type SaveMessageArgs, type SaveMessagesArgs, } from "./messages.js";
-export { mockModel } from "./mockModel.js";
-export { fetchContextMessages, filterOutOrphanedToolMessages, fetchContextWithPrompt, generateAndSaveEmbeddings, embedMessages, embedMany, } from "./search.js";
-export { startGeneration } from "./start.js";
-export { DEFAULT_STREAMING_OPTIONS, DeltaStreamer, abortStream, compressUIMessageChunks, listStreams, syncStreams, vStreamMessagesReturnValue, } from "./streaming.js";
-export { createThread, getThreadMetadata, searchThreadTitles, updateThreadMetadata, } from "./threads.js";
-export type { ContextHandler } from "./types.js";
-export { toUIMessages, fromUIMessages, type UIMessage } from "../UIMessages.js";
+export { createTool, type ToolCtx } from "./client/createTool.js";
+export { definePlaygroundAPI, type AgentsFn, type PlaygroundAPI, } from "./client/definePlaygroundAPI.js";
+export { getFile, storeFile } from "./client/files.js";
+export { listMessages, listUIMessages, saveMessage, saveMessages, type SaveMessageArgs, type SaveMessagesArgs, } from "./client/messages.js";
+export { mockModel } from "./client/mockModel.js";
+export { fetchContextMessages, filterOutOrphanedToolMessages, fetchContextWithPrompt, generateAndSaveEmbeddings, embedMessages, embedMany, } from "./client/search.js";
+export { startGeneration } from "./client/start.js";
+export { DEFAULT_STREAMING_OPTIONS, DeltaStreamer, abortStream, compressUIMessageChunks, listStreams, syncStreams, vStreamMessagesReturnValue, } from "./client/streaming.js";
+export { createThread, getThreadMetadata, searchThreadTitles, updateThreadMetadata, } from "../client/threads.js";
+export type { ContextHandler } from "./client/types.js";
+export { toUIMessages, fromUIMessages, type UIMessage } from "./UIMessages.js";
 export type { AgentComponent, Config, ContextOptions, ProviderMetadata, RawRequestResponseHandler, StorageOptions, StreamArgs, SyncStreamsReturnValue, Thread, UsageHandler, };
 export declare class Agent<
 /**
@@ -67,7 +74,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * The default system prompt to put in each request.
          * Override per-prompt by passing the "system" parameter.
          */
-        instructions?: string;
+        instructions?: Instructions;
         /**
          * Tools that the agent can call out to and get responses from.
          * They can be AI SDK tools (import {tool} from "ai")
@@ -99,7 +106,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * The default system prompt to put in each request.
          * Override per-prompt by passing the "system" parameter.
          */
-        instructions?: string;
+        instructions?: Instructions;
         /**
          * Tools that the agent can call out to and get responses from.
          * They can be AI SDK tools (import {tool} from "ai")
@@ -197,7 +204,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
         _internal?: {
             generateId?: IdGenerator;
         };
-    }>(ctx: ActionCtx & CustomCtx, 
+    }, RUNTIME_CONTEXT extends Context = Context>(ctx: ActionCtx & CustomCtx, 
     /**
      * These are the arguments you'll pass to the LLM call such as
      * `generateText` or `streamText`. This function will look up the context
@@ -217,25 +224,28 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * aborted, it will trigger this signal when detected.
          */
         abortSignal?: AbortSignal;
-        stopWhen?: StopCondition<TOOLS extends undefined ? AgentTools : TOOLS> | Array<StopCondition<TOOLS extends undefined ? AgentTools : TOOLS>>;
+        runtimeContext?: RUNTIME_CONTEXT;
+        stopWhen?: StopCondition<TOOLS extends undefined ? AgentTools : TOOLS, RUNTIME_CONTEXT> | Array<StopCondition<TOOLS extends undefined ? AgentTools : TOOLS, RUNTIME_CONTEXT>>;
     }, options?: Options & {
         userId?: string | null;
         threadId?: string;
-    }): Promise<{
+    }, operation?: "generateText" | "streamText" | "generateObject" | "streamObject"): Promise<{
         args: T & {
-            system?: string;
+            instructions?: Instructions;
             model: LanguageModel;
             prompt?: never;
             messages: ModelMessage[];
+            runtimeContext?: RUNTIME_CONTEXT;
             tools?: TOOLS extends undefined ? AgentTools : TOOLS;
-        } & CallSettings;
+        } & AgentCallSettings;
         order: number;
         stepOrder: number;
         userId: string | undefined;
         promptMessageId: string | undefined;
         updateModel: (model: LanguageModel | undefined) => void;
         save: <TOOLS extends ToolSet>(toSave: {
-            step: StepResult<TOOLS>;
+            step: StepResult<TOOLS, RUNTIME_CONTEXT>;
+            responseMessages?: ModelMessage[];
         } | {
             object: GenerateObjectResult<unknown>;
         }, createPendingMessage?: boolean) => Promise<void>;
@@ -255,7 +265,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * @param options Extra controls for the {@link ContextOptions} and {@link StorageOptions}.
      * @returns The result of the generateText function.
      */
-    generateText<TOOLS extends ToolSet | undefined = undefined, OUTPUT extends Output<any, any, any> = never>(ctx: ActionCtx & CustomCtx, threadOpts: {
+    generateText<TOOLS extends ToolSet | undefined = undefined, OUTPUT extends AISDKOutput.Output<any, any, any> = AISDKOutput.Output<string, string>, RUNTIME_CONTEXT extends Context = Context>(ctx: ActionCtx & CustomCtx, threadOpts: {
         userId?: string | null;
         threadId?: string;
     }, 
@@ -263,7 +273,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * The arguments to the generateText function, similar to the ai sdk's
      * {@link generateText} function, along with Agent prompt options.
      */
-    generateTextArgs: AgentPrompt & TextArgs<AgentTools, TOOLS, OUTPUT>, options?: Options): Promise<GenerateTextResult<TOOLS extends undefined ? AgentTools : TOOLS, OUTPUT> & GenerationOutputMetadata>;
+    generateTextArgs: TextArgs<AgentTools, TOOLS, OUTPUT, RUNTIME_CONTEXT>, options?: Options): Promise<GenerateTextResult<TOOLS extends undefined ? AgentTools : TOOLS, RUNTIME_CONTEXT, OUTPUT> & GenerationOutputMetadata>;
     /**
      * This behaves like {@link streamText} from the "ai" package except that
      * it add context based on the userId and threadId and saves the input and
@@ -271,7 +281,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * Use {@link continueThread} to get a version of this function already scoped
      * to a thread (and optionally userId).
      */
-    streamText<TOOLS extends ToolSet | undefined = undefined, OUTPUT extends Output<any, any, any> = never>(ctx: ActionCtx & CustomCtx, threadOpts: {
+    streamText<TOOLS extends ToolSet | undefined = undefined, OUTPUT extends AISDKOutput.Output<any, any, any> = AISDKOutput.Output<string, string, never>, RUNTIME_CONTEXT extends Context = Context>(ctx: ActionCtx & CustomCtx, threadOpts: {
         userId?: string | null;
         threadId?: string;
     }, 
@@ -279,7 +289,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * The arguments to the streamText function, similar to the ai sdk's
      * {@link streamText} function, along with Agent prompt options.
      */
-    streamTextArgs: AgentPrompt & StreamingTextArgs<AgentTools, TOOLS, OUTPUT>, 
+    streamTextArgs: StreamingTextArgs<AgentTools, TOOLS, OUTPUT, RUNTIME_CONTEXT>, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
@@ -296,7 +306,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * iterating over the text, streaming it over HTTP, etc.
          */
         saveStreamDeltas?: boolean | StreamingOptions;
-    }): Promise<StreamTextResult<TOOLS extends undefined ? AgentTools : TOOLS, OUTPUT> & GenerationOutputMetadata>;
+    }): Promise<StreamTextResult<TOOLS extends undefined ? AgentTools : TOOLS, RUNTIME_CONTEXT, OUTPUT> & GenerationOutputMetadata>;
     /**
      * This behaves like {@link generateObject} from the "ai" package except that
      * it add context based on the userId and threadId and saves the input and
@@ -312,7 +322,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * The arguments to the generateObject function, similar to the ai sdk's
      * {@link generateObject} function, along with Agent prompt options.
      */
-    generateObjectArgs: AgentPrompt & GenerateObjectArgs<SCHEMA, OUTPUT, RESULT>, 
+    generateObjectArgs: GenerateObjectArgs<SCHEMA, OUTPUT, RESULT>, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
@@ -333,7 +343,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * The arguments to the streamObject function, similar to the ai sdk's
      * {@link streamObject} function, along with Agent prompt options.
      */
-    streamObjectArgs: AgentPrompt & StreamObjectArgs<SCHEMA, OUTPUT, RESULT>, 
+    streamObjectArgs: StreamObjectArgs<SCHEMA, OUTPUT, RESULT>, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
@@ -357,6 +367,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
     }): Promise<{
         messageId: string;
         message: {
+            text?: string | undefined;
+            reasoning?: string | undefined;
             id?: string | undefined;
             userId?: string | undefined;
             embeddingId?: string | undefined;
@@ -372,14 +384,17 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 content: string | ({
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
-                    type: "text";
                     text: string;
+                    type: "text";
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     mediaType?: string | undefined;
                     mimeType?: string | undefined;
                     type: "image";
-                    image: string | ArrayBuffer;
+                    image: string | ArrayBuffer | {
+                        type: "reference";
+                        reference: Record<string, string>;
+                    };
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -387,7 +402,10 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     mimeType?: string | undefined;
                     filename?: string | undefined;
                     type: "file";
-                    data: string | ArrayBuffer;
+                    data: string | ArrayBuffer | {
+                        type: "reference";
+                        reference: Record<string, string>;
+                    };
                 })[];
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
@@ -395,8 +413,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 content: string | ({
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
-                    type: "text";
                     text: string;
+                    type: "text";
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -404,32 +422,51 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     mimeType?: string | undefined;
                     filename?: string | undefined;
                     type: "file";
-                    data: string | ArrayBuffer;
+                    data: string | ArrayBuffer | {
+                        type: "reference";
+                        reference: Record<string, string>;
+                    };
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
                     signature?: string | undefined;
-                    type: "reasoning";
                     text: string;
+                    type: "reasoning";
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    providerMetadata?: Record<string, Record<string, any>> | undefined;
+                    data?: string | ArrayBuffer | undefined;
+                    url?: string | undefined;
+                    type: "reasoning-file";
+                    mediaType: string;
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    providerMetadata?: Record<string, Record<string, any>> | undefined;
+                    type: "custom";
+                    kind: string;
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
                     type: "redacted-reasoning";
                     data: string;
                 } | {
+                    title?: string | undefined;
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
                     args?: any;
                     providerExecuted?: boolean | undefined;
+                    toolMetadata?: Record<string, any> | undefined;
                     type: "tool-call";
                     toolCallId: string;
                     toolName: string;
                     input: any;
                 } | {
+                    title?: string | undefined;
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
                     input?: any;
                     providerExecuted?: boolean | undefined;
+                    toolMetadata?: Record<string, any> | undefined;
                     type: "tool-call";
                     toolCallId: string;
                     toolName: string;
@@ -463,8 +500,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                         type: "content";
                         value: ({
                             providerOptions?: Record<string, Record<string, any>> | undefined;
-                            type: "text";
                             text: string;
+                            type: "text";
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            filename?: string | undefined;
+                            type: "file";
+                            mediaType: string;
+                            data: {
+                                type: "reference";
+                                reference: Record<string, string>;
+                            } | {
+                                type: "url";
+                                url: string;
+                            } | {
+                                type: "data";
+                                data: string | ArrayBuffer;
+                            } | {
+                                text: string;
+                                type: "text";
+                            };
                         } | {
                             type: "media";
                             mediaType: string;
@@ -477,17 +532,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                             data: string;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
+                            mediaType?: string | undefined;
                             type: "file-url";
                             url: string;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "file-id";
                             fileId: string | Record<string, string>;
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            type: "file-reference";
+                            providerReference: Record<string, string>;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "image-data";
                             mediaType: string;
                             data: string;
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            type: "image-file-reference";
+                            providerReference: Record<string, string>;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "image-url";
@@ -504,8 +568,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     result?: any;
                     isError?: boolean | undefined;
                     experimental_content?: ({
-                        type: "text";
                         text: string;
+                        type: "text";
                     } | {
                         mimeType?: string | undefined;
                         type: "image";
@@ -534,6 +598,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
+                    signature?: string | undefined;
+                    isAutomatic?: boolean | undefined;
                     type: "tool-approval-request";
                     toolCallId: string;
                     approvalId: string;
@@ -570,8 +636,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                         type: "content";
                         value: ({
                             providerOptions?: Record<string, Record<string, any>> | undefined;
-                            type: "text";
                             text: string;
+                            type: "text";
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            filename?: string | undefined;
+                            type: "file";
+                            mediaType: string;
+                            data: {
+                                type: "reference";
+                                reference: Record<string, string>;
+                            } | {
+                                type: "url";
+                                url: string;
+                            } | {
+                                type: "data";
+                                data: string | ArrayBuffer;
+                            } | {
+                                text: string;
+                                type: "text";
+                            };
                         } | {
                             type: "media";
                             mediaType: string;
@@ -584,17 +668,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                             data: string;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
+                            mediaType?: string | undefined;
                             type: "file-url";
                             url: string;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "file-id";
                             fileId: string | Record<string, string>;
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            type: "file-reference";
+                            providerReference: Record<string, string>;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "image-data";
                             mediaType: string;
                             data: string;
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            type: "image-file-reference";
+                            providerReference: Record<string, string>;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "image-url";
@@ -611,8 +704,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     result?: any;
                     isError?: boolean | undefined;
                     experimental_content?: ({
-                        type: "text";
                         text: string;
+                        type: "text";
                     } | {
                         mimeType?: string | undefined;
                         type: "image";
@@ -635,15 +728,17 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 role: "system";
                 content: string;
             } | undefined;
-            text?: string | undefined;
             providerMetadata?: Record<string, Record<string, any>> | undefined;
-            reasoning?: string | undefined;
             usage?: {
+                promptTokens?: number | undefined;
+                completionTokens?: number | undefined;
+                totalTokens?: number | undefined;
                 reasoningTokens?: number | undefined;
                 cachedInputTokens?: number | undefined;
-                promptTokens: number;
-                completionTokens: number;
-                totalTokens: number;
+                nonCachedInputTokens?: number | undefined;
+                cacheWriteInputTokens?: number | undefined;
+                textOutputTokens?: number | undefined;
+                raw?: Record<string, any> | undefined;
             } | undefined;
             sources?: ({
                 title?: string | undefined;
@@ -664,13 +759,25 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 sourceType: "document";
             })[] | undefined;
             warnings?: ({
+                details?: string | undefined;
+                type: "unsupported";
+                feature: string;
+            } | {
+                details?: string | undefined;
+                type: "compatibility";
+                feature: string;
+            } | {
+                type: "deprecated";
+                message: string;
+                setting: string;
+            } | {
                 details?: string | undefined;
                 type: "unsupported-setting";
                 setting: string;
             } | {
                 details?: string | undefined;
-                type: "unsupported-tool";
                 tool: any;
+                type: "unsupported-tool";
             } | {
                 type: "other";
                 message: string;
@@ -680,22 +787,22 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 signature?: string | undefined;
-                type: "reasoning";
                 text: string;
+                type: "reasoning";
             } | {
                 signature?: string | undefined;
-                type: "text";
                 text: string;
+                type: "text";
             } | {
                 type: "redacted";
                 data: string;
             })[] | undefined;
+            tool: boolean;
             status: "pending" | "success" | "failed";
             order: number;
             _creationTime: number;
             threadId: string;
             stepOrder: number;
-            tool: boolean;
             _id: string;
         };
     }>;
@@ -870,8 +977,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
     private findApprovalContext;
     /**
      * Explicitly save a "step" created by the AI SDK. For multi-step generation
-     * loops, pass `previousStep` so we save only the new response messages —
-     * see the arg JSDoc for why.
+     * loops, each SDK 7 step already owns its response messages.
      * @param ctx The ctx argument to a mutation or action.
      * @param args The Step generated by the AI SDK.
      */
@@ -886,14 +992,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * The step to save, possibly including multiple tool calls.
          */
         step: StepResult<TOOLS>;
-        /**
-         * The previous step in the same generation loop, if any. Pass it so we
-         * can compute how many of `step.response.messages` are already saved.
-         * Omit for the first step. AI SDK v6's `step.response.messages` is
-         * cumulative across steps; without this, multi-step callers duplicate
-         * every prior message on every save — the exact failure mode this fix
-         * addresses, just at the public-API layer.
-         */
+        /** @deprecated SDK 7 response messages are step-local. */
         previousStep?: StepResult<TOOLS>;
         /**
          * The model used to generate the step.
@@ -1107,25 +1206,36 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * Defaults to the {@link Agent["options"].stopWhen} option.
          */
         stopWhen?: StopCondition<AgentTools> | Array<StopCondition<AgentTools>>;
-    } & Options, overrides?: CallSettings): import("convex/server").RegisteredAction<"internal", {
+    } & Options, overrides?: AgentCallSettings): import("convex/server").RegisteredAction<"internal", {
+        system?: string | {
+            providerOptions?: Record<string, Record<string, any>> | undefined;
+            role: "system";
+            content: string;
+        } | {
+            providerOptions?: Record<string, Record<string, any>> | undefined;
+            role: "system";
+            content: string;
+        }[] | undefined;
         userId?: string | undefined;
         threadId?: string | undefined;
         providerOptions?: Record<string, Record<string, any>> | undefined;
-        system?: string | undefined;
         messages?: ({
             providerOptions?: Record<string, Record<string, any>> | undefined;
             role: "user";
             content: string | ({
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
-                type: "text";
                 text: string;
+                type: "text";
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 mediaType?: string | undefined;
                 mimeType?: string | undefined;
                 type: "image";
-                image: string | ArrayBuffer;
+                image: string | ArrayBuffer | {
+                    type: "reference";
+                    reference: Record<string, string>;
+                };
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -1133,7 +1243,10 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 mimeType?: string | undefined;
                 filename?: string | undefined;
                 type: "file";
-                data: string | ArrayBuffer;
+                data: string | ArrayBuffer | {
+                    type: "reference";
+                    reference: Record<string, string>;
+                };
             })[];
         } | {
             providerOptions?: Record<string, Record<string, any>> | undefined;
@@ -1141,8 +1254,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
             content: string | ({
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
-                type: "text";
                 text: string;
+                type: "text";
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -1150,32 +1263,51 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 mimeType?: string | undefined;
                 filename?: string | undefined;
                 type: "file";
-                data: string | ArrayBuffer;
+                data: string | ArrayBuffer | {
+                    type: "reference";
+                    reference: Record<string, string>;
+                };
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 signature?: string | undefined;
-                type: "reasoning";
                 text: string;
+                type: "reasoning";
+            } | {
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                providerMetadata?: Record<string, Record<string, any>> | undefined;
+                data?: string | ArrayBuffer | undefined;
+                url?: string | undefined;
+                type: "reasoning-file";
+                mediaType: string;
+            } | {
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                providerMetadata?: Record<string, Record<string, any>> | undefined;
+                type: "custom";
+                kind: string;
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 type: "redacted-reasoning";
                 data: string;
             } | {
+                title?: string | undefined;
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 args?: any;
                 providerExecuted?: boolean | undefined;
+                toolMetadata?: Record<string, any> | undefined;
                 type: "tool-call";
                 toolCallId: string;
                 toolName: string;
                 input: any;
             } | {
+                title?: string | undefined;
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 input?: any;
                 providerExecuted?: boolean | undefined;
+                toolMetadata?: Record<string, any> | undefined;
                 type: "tool-call";
                 toolCallId: string;
                 toolName: string;
@@ -1209,8 +1341,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     type: "content";
                     value: ({
                         providerOptions?: Record<string, Record<string, any>> | undefined;
-                        type: "text";
                         text: string;
+                        type: "text";
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        filename?: string | undefined;
+                        type: "file";
+                        mediaType: string;
+                        data: {
+                            type: "reference";
+                            reference: Record<string, string>;
+                        } | {
+                            type: "url";
+                            url: string;
+                        } | {
+                            type: "data";
+                            data: string | ArrayBuffer;
+                        } | {
+                            text: string;
+                            type: "text";
+                        };
                     } | {
                         type: "media";
                         mediaType: string;
@@ -1223,17 +1373,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                         data: string;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
+                        mediaType?: string | undefined;
                         type: "file-url";
                         url: string;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "file-id";
                         fileId: string | Record<string, string>;
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        type: "file-reference";
+                        providerReference: Record<string, string>;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "image-data";
                         mediaType: string;
                         data: string;
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        type: "image-file-reference";
+                        providerReference: Record<string, string>;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "image-url";
@@ -1250,8 +1409,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 result?: any;
                 isError?: boolean | undefined;
                 experimental_content?: ({
-                    type: "text";
                     text: string;
+                    type: "text";
                 } | {
                     mimeType?: string | undefined;
                     type: "image";
@@ -1280,6 +1439,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
+                signature?: string | undefined;
+                isAutomatic?: boolean | undefined;
                 type: "tool-approval-request";
                 toolCallId: string;
                 approvalId: string;
@@ -1316,8 +1477,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     type: "content";
                     value: ({
                         providerOptions?: Record<string, Record<string, any>> | undefined;
-                        type: "text";
                         text: string;
+                        type: "text";
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        filename?: string | undefined;
+                        type: "file";
+                        mediaType: string;
+                        data: {
+                            type: "reference";
+                            reference: Record<string, string>;
+                        } | {
+                            type: "url";
+                            url: string;
+                        } | {
+                            type: "data";
+                            data: string | ArrayBuffer;
+                        } | {
+                            text: string;
+                            type: "text";
+                        };
                     } | {
                         type: "media";
                         mediaType: string;
@@ -1330,17 +1509,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                         data: string;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
+                        mediaType?: string | undefined;
                         type: "file-url";
                         url: string;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "file-id";
                         fileId: string | Record<string, string>;
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        type: "file-reference";
+                        providerReference: Record<string, string>;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "image-data";
                         mediaType: string;
                         data: string;
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        type: "image-file-reference";
+                        providerReference: Record<string, string>;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "image-url";
@@ -1357,8 +1545,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 result?: any;
                 isError?: boolean | undefined;
                 experimental_content?: ({
-                    type: "text";
                     text: string;
+                    type: "text";
                 } | {
                     mimeType?: string | undefined;
                     type: "image";
@@ -1420,12 +1608,13 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
             seed?: number | undefined;
             maxRetries?: number | undefined;
         } | undefined;
+        allowSystemInMessages?: boolean | undefined;
     }, Promise<{
         text: string;
         promptMessageId: string | undefined;
         order: number | undefined;
         finishReason: import("ai").FinishReason;
-        warnings: import("@ai-sdk/provider").SharedV3Warning[] | undefined;
+        warnings: import("@ai-sdk/provider").SharedV4Warning[] | undefined;
         savedMessageIds: string[];
     }>>;
     /**
@@ -1436,24 +1625,35 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * and stopWhen.
      */
     asObjectAction<T, DataModel extends GenericDataModel>(objectArgs: GenerateObjectArgs<FlexibleSchema<T>> & Partial<AgentPrompt>, options?: Options & MaybeCustomCtx<CustomCtx, DataModel, AgentTools>): import("convex/server").RegisteredAction<"internal", {
+        system?: string | {
+            providerOptions?: Record<string, Record<string, any>> | undefined;
+            role: "system";
+            content: string;
+        } | {
+            providerOptions?: Record<string, Record<string, any>> | undefined;
+            role: "system";
+            content: string;
+        }[] | undefined;
         userId?: string | undefined;
         threadId?: string | undefined;
         providerOptions?: Record<string, Record<string, any>> | undefined;
-        system?: string | undefined;
         messages?: ({
             providerOptions?: Record<string, Record<string, any>> | undefined;
             role: "user";
             content: string | ({
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
-                type: "text";
                 text: string;
+                type: "text";
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 mediaType?: string | undefined;
                 mimeType?: string | undefined;
                 type: "image";
-                image: string | ArrayBuffer;
+                image: string | ArrayBuffer | {
+                    type: "reference";
+                    reference: Record<string, string>;
+                };
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -1461,7 +1661,10 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 mimeType?: string | undefined;
                 filename?: string | undefined;
                 type: "file";
-                data: string | ArrayBuffer;
+                data: string | ArrayBuffer | {
+                    type: "reference";
+                    reference: Record<string, string>;
+                };
             })[];
         } | {
             providerOptions?: Record<string, Record<string, any>> | undefined;
@@ -1469,8 +1672,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
             content: string | ({
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
-                type: "text";
                 text: string;
+                type: "text";
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -1478,32 +1681,51 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 mimeType?: string | undefined;
                 filename?: string | undefined;
                 type: "file";
-                data: string | ArrayBuffer;
+                data: string | ArrayBuffer | {
+                    type: "reference";
+                    reference: Record<string, string>;
+                };
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 signature?: string | undefined;
-                type: "reasoning";
                 text: string;
+                type: "reasoning";
+            } | {
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                providerMetadata?: Record<string, Record<string, any>> | undefined;
+                data?: string | ArrayBuffer | undefined;
+                url?: string | undefined;
+                type: "reasoning-file";
+                mediaType: string;
+            } | {
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                providerMetadata?: Record<string, Record<string, any>> | undefined;
+                type: "custom";
+                kind: string;
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 type: "redacted-reasoning";
                 data: string;
             } | {
+                title?: string | undefined;
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 args?: any;
                 providerExecuted?: boolean | undefined;
+                toolMetadata?: Record<string, any> | undefined;
                 type: "tool-call";
                 toolCallId: string;
                 toolName: string;
                 input: any;
             } | {
+                title?: string | undefined;
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 input?: any;
                 providerExecuted?: boolean | undefined;
+                toolMetadata?: Record<string, any> | undefined;
                 type: "tool-call";
                 toolCallId: string;
                 toolName: string;
@@ -1537,8 +1759,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     type: "content";
                     value: ({
                         providerOptions?: Record<string, Record<string, any>> | undefined;
-                        type: "text";
                         text: string;
+                        type: "text";
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        filename?: string | undefined;
+                        type: "file";
+                        mediaType: string;
+                        data: {
+                            type: "reference";
+                            reference: Record<string, string>;
+                        } | {
+                            type: "url";
+                            url: string;
+                        } | {
+                            type: "data";
+                            data: string | ArrayBuffer;
+                        } | {
+                            text: string;
+                            type: "text";
+                        };
                     } | {
                         type: "media";
                         mediaType: string;
@@ -1551,17 +1791,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                         data: string;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
+                        mediaType?: string | undefined;
                         type: "file-url";
                         url: string;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "file-id";
                         fileId: string | Record<string, string>;
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        type: "file-reference";
+                        providerReference: Record<string, string>;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "image-data";
                         mediaType: string;
                         data: string;
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        type: "image-file-reference";
+                        providerReference: Record<string, string>;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "image-url";
@@ -1578,8 +1827,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 result?: any;
                 isError?: boolean | undefined;
                 experimental_content?: ({
-                    type: "text";
                     text: string;
+                    type: "text";
                 } | {
                     mimeType?: string | undefined;
                     type: "image";
@@ -1608,6 +1857,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
+                signature?: string | undefined;
+                isAutomatic?: boolean | undefined;
                 type: "tool-approval-request";
                 toolCallId: string;
                 approvalId: string;
@@ -1644,8 +1895,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     type: "content";
                     value: ({
                         providerOptions?: Record<string, Record<string, any>> | undefined;
-                        type: "text";
                         text: string;
+                        type: "text";
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        filename?: string | undefined;
+                        type: "file";
+                        mediaType: string;
+                        data: {
+                            type: "reference";
+                            reference: Record<string, string>;
+                        } | {
+                            type: "url";
+                            url: string;
+                        } | {
+                            type: "data";
+                            data: string | ArrayBuffer;
+                        } | {
+                            text: string;
+                            type: "text";
+                        };
                     } | {
                         type: "media";
                         mediaType: string;
@@ -1658,17 +1927,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                         data: string;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
+                        mediaType?: string | undefined;
                         type: "file-url";
                         url: string;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "file-id";
                         fileId: string | Record<string, string>;
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        type: "file-reference";
+                        providerReference: Record<string, string>;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "image-data";
                         mediaType: string;
                         data: string;
+                    } | {
+                        providerOptions?: Record<string, Record<string, any>> | undefined;
+                        type: "image-file-reference";
+                        providerReference: Record<string, string>;
                     } | {
                         providerOptions?: Record<string, Record<string, any>> | undefined;
                         type: "image-url";
@@ -1685,8 +1963,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 result?: any;
                 isError?: boolean | undefined;
                 experimental_content?: ({
-                    type: "text";
                     text: string;
+                    type: "text";
                 } | {
                     mimeType?: string | undefined;
                     type: "image";
@@ -1741,12 +2019,13 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
             seed?: number | undefined;
             maxRetries?: number | undefined;
         } | undefined;
+        allowSystemInMessages?: boolean | undefined;
     }, Promise<{
         object: T;
         promptMessageId: string | undefined;
         order: number | undefined;
         finishReason: import("ai").FinishReason;
-        warnings: import("@ai-sdk/provider").SharedV3Warning[] | undefined;
+        warnings: import("@ai-sdk/provider").SharedV4Warning[] | undefined;
         savedMessageIds: string[];
     }>>;
     /**
@@ -1762,20 +2041,24 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
         failPendingSteps?: boolean | undefined;
         threadId: string;
         messages: {
+            text?: string | undefined;
+            reasoning?: string | undefined;
             status?: "pending" | "success" | "failed" | undefined;
             fileIds?: string[] | undefined;
             error?: string | undefined;
             model?: string | undefined;
             provider?: string | undefined;
-            text?: string | undefined;
             providerMetadata?: Record<string, Record<string, any>> | undefined;
-            reasoning?: string | undefined;
             usage?: {
+                promptTokens?: number | undefined;
+                completionTokens?: number | undefined;
+                totalTokens?: number | undefined;
                 reasoningTokens?: number | undefined;
                 cachedInputTokens?: number | undefined;
-                promptTokens: number;
-                completionTokens: number;
-                totalTokens: number;
+                nonCachedInputTokens?: number | undefined;
+                cacheWriteInputTokens?: number | undefined;
+                textOutputTokens?: number | undefined;
+                raw?: Record<string, any> | undefined;
             } | undefined;
             sources?: ({
                 title?: string | undefined;
@@ -1796,13 +2079,25 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 sourceType: "document";
             })[] | undefined;
             warnings?: ({
+                details?: string | undefined;
+                type: "unsupported";
+                feature: string;
+            } | {
+                details?: string | undefined;
+                type: "compatibility";
+                feature: string;
+            } | {
+                type: "deprecated";
+                message: string;
+                setting: string;
+            } | {
                 details?: string | undefined;
                 type: "unsupported-setting";
                 setting: string;
             } | {
                 details?: string | undefined;
-                type: "unsupported-tool";
                 tool: any;
+                type: "unsupported-tool";
             } | {
                 type: "other";
                 message: string;
@@ -1812,12 +2107,12 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
                 signature?: string | undefined;
-                type: "reasoning";
                 text: string;
+                type: "reasoning";
             } | {
                 signature?: string | undefined;
-                type: "text";
                 text: string;
+                type: "text";
             } | {
                 type: "redacted";
                 data: string;
@@ -1828,14 +2123,17 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 content: string | ({
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
-                    type: "text";
                     text: string;
+                    type: "text";
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     mediaType?: string | undefined;
                     mimeType?: string | undefined;
                     type: "image";
-                    image: string | ArrayBuffer;
+                    image: string | ArrayBuffer | {
+                        type: "reference";
+                        reference: Record<string, string>;
+                    };
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -1843,7 +2141,10 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     mimeType?: string | undefined;
                     filename?: string | undefined;
                     type: "file";
-                    data: string | ArrayBuffer;
+                    data: string | ArrayBuffer | {
+                        type: "reference";
+                        reference: Record<string, string>;
+                    };
                 })[];
             } | {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
@@ -1851,8 +2152,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 content: string | ({
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
-                    type: "text";
                     text: string;
+                    type: "text";
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -1860,32 +2161,51 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     mimeType?: string | undefined;
                     filename?: string | undefined;
                     type: "file";
-                    data: string | ArrayBuffer;
+                    data: string | ArrayBuffer | {
+                        type: "reference";
+                        reference: Record<string, string>;
+                    };
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
                     signature?: string | undefined;
-                    type: "reasoning";
                     text: string;
+                    type: "reasoning";
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    providerMetadata?: Record<string, Record<string, any>> | undefined;
+                    data?: string | ArrayBuffer | undefined;
+                    url?: string | undefined;
+                    type: "reasoning-file";
+                    mediaType: string;
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    providerMetadata?: Record<string, Record<string, any>> | undefined;
+                    type: "custom";
+                    kind: string;
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
                     type: "redacted-reasoning";
                     data: string;
                 } | {
+                    title?: string | undefined;
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
                     args?: any;
                     providerExecuted?: boolean | undefined;
+                    toolMetadata?: Record<string, any> | undefined;
                     type: "tool-call";
                     toolCallId: string;
                     toolName: string;
                     input: any;
                 } | {
+                    title?: string | undefined;
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
                     input?: any;
                     providerExecuted?: boolean | undefined;
+                    toolMetadata?: Record<string, any> | undefined;
                     type: "tool-call";
                     toolCallId: string;
                     toolName: string;
@@ -1919,8 +2239,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                         type: "content";
                         value: ({
                             providerOptions?: Record<string, Record<string, any>> | undefined;
-                            type: "text";
                             text: string;
+                            type: "text";
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            filename?: string | undefined;
+                            type: "file";
+                            mediaType: string;
+                            data: {
+                                type: "reference";
+                                reference: Record<string, string>;
+                            } | {
+                                type: "url";
+                                url: string;
+                            } | {
+                                type: "data";
+                                data: string | ArrayBuffer;
+                            } | {
+                                text: string;
+                                type: "text";
+                            };
                         } | {
                             type: "media";
                             mediaType: string;
@@ -1933,17 +2271,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                             data: string;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
+                            mediaType?: string | undefined;
                             type: "file-url";
                             url: string;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "file-id";
                             fileId: string | Record<string, string>;
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            type: "file-reference";
+                            providerReference: Record<string, string>;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "image-data";
                             mediaType: string;
                             data: string;
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            type: "image-file-reference";
+                            providerReference: Record<string, string>;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "image-url";
@@ -1960,8 +2307,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     result?: any;
                     isError?: boolean | undefined;
                     experimental_content?: ({
-                        type: "text";
                         text: string;
+                        type: "text";
                     } | {
                         mimeType?: string | undefined;
                         type: "image";
@@ -1990,6 +2337,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 } | {
                     providerOptions?: Record<string, Record<string, any>> | undefined;
                     providerMetadata?: Record<string, Record<string, any>> | undefined;
+                    signature?: string | undefined;
+                    isAutomatic?: boolean | undefined;
                     type: "tool-approval-request";
                     toolCallId: string;
                     approvalId: string;
@@ -2026,8 +2375,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                         type: "content";
                         value: ({
                             providerOptions?: Record<string, Record<string, any>> | undefined;
-                            type: "text";
                             text: string;
+                            type: "text";
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            filename?: string | undefined;
+                            type: "file";
+                            mediaType: string;
+                            data: {
+                                type: "reference";
+                                reference: Record<string, string>;
+                            } | {
+                                type: "url";
+                                url: string;
+                            } | {
+                                type: "data";
+                                data: string | ArrayBuffer;
+                            } | {
+                                text: string;
+                                type: "text";
+                            };
                         } | {
                             type: "media";
                             mediaType: string;
@@ -2040,17 +2407,26 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                             data: string;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
+                            mediaType?: string | undefined;
                             type: "file-url";
                             url: string;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "file-id";
                             fileId: string | Record<string, string>;
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            type: "file-reference";
+                            providerReference: Record<string, string>;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "image-data";
                             mediaType: string;
                             data: string;
+                        } | {
+                            providerOptions?: Record<string, Record<string, any>> | undefined;
+                            type: "image-file-reference";
+                            providerReference: Record<string, string>;
                         } | {
                             providerOptions?: Record<string, Record<string, any>> | undefined;
                             type: "image-url";
@@ -2067,8 +2443,8 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                     result?: any;
                     isError?: boolean | undefined;
                     experimental_content?: ({
-                        type: "text";
                         text: string;
+                        type: "text";
                     } | {
                         mimeType?: string | undefined;
                         type: "image";