@convex-dev/agent 0.5.0-alpha.1 → 0.6.0-alpha.1

package/src/mapping.ts

@@ -16,27 +16,43 @@ import {
   type TextPart,
   type ToolCallPart,
   type ToolResultPart,
-  type ReasoningUIPart,
+  type ProviderMetadata,
+  type JSONValue,
 } from "ai";
-import type {
-  Message,
-  MessageWithMetadata,
-  Usage,
-  vContent,
-  vFilePart,
-  vImagePart,
-  vReasoningPart,
-  vRedactedReasoningPart,
-  vTextPart,
-  vToolCallPart,
-  vToolResultPart,
+import {
+  vMessageWithMetadata,
+  type vSourcePart,
+  type Message,
+  type MessageWithMetadata,
+  type Usage,
+  type vFilePart,
+  type vImagePart,
+  type vReasoningPart,
+  type vRedactedReasoningPart,
+  type vTextPart,
+  type vToolCallPart,
+  type vToolResultPart,
+  type SourcePart,
+  vToolResultOutput,
+  type MessageDoc,
+  vToolApprovalRequest,
+  vToolApprovalResponse,
 } from "./validators.js";
 import type { ActionCtx, AgentComponent } from "./client/types.js";
-import type { RunMutationCtx } from "./client/types.js";
+import type { MutationCtx } from "./client/types.js";
 import { MAX_FILE_SIZE, storeFile } from "./client/files.js";
 import type { Infer } from "convex/values";
-import { omit } from "convex-helpers";
-
+import {
+  convertUint8ArrayToBase64,
+  type ProviderOptions,
+  type ReasoningPart,
+} from "@ai-sdk/provider-utils";
+import { parse, validate } from "convex-helpers/validators";
+import {
+  getModelName,
+  getProviderName,
+  type ModelOrMetadata,
+} from "./shared.js";
 export type AIMessageWithoutId = Omit<AIMessage, "id">;
 
 export type SerializeUrlsAndUint8Arrays<T> = T extends URL
@@ -45,8 +61,7 @@ export type SerializeUrlsAndUint8Arrays<T> = T extends URL
     ? ArrayBuffer
     : T extends Array<infer Inner>
       ? Array<SerializeUrlsAndUint8Arrays<Inner>>
-      : // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        T extends Record<string, any>
+      : T extends Record<string, any>
         ? { [K in keyof T]: SerializeUrlsAndUint8Arrays<T[K]> }
         : T;
 
@@ -56,12 +71,10 @@ export type SerializedContent = Message["content"];
 export type SerializedMessage = Message;
 
 export async function serializeMessage(
-  ctx: ActionCtx | RunMutationCtx,
+  ctx: ActionCtx | MutationCtx,
   component: AgentComponent,
-  messageWithId: (ModelMessage & { id?: string }) | Message,
+  message: ModelMessage | Message,
 ): Promise<{ message: SerializedMessage; fileIds?: string[] }> {
-  const message =
-    "id" in messageWithId ? omit(messageWithId, ["id"]) : messageWithId;
   const { content, fileIds } = await serializeContent(
     ctx,
     component,
@@ -69,36 +82,129 @@ export async function serializeMessage(
   );
   return {
     message: {
-      ...message,
+      role: message.role,
       content,
+      ...(message.providerOptions
+        ? { providerOptions: message.providerOptions }
+        : {}),
     } as SerializedMessage,
     fileIds,
   };
 }
 
-export function deserializeMessage(message: SerializedMessage): ModelMessage {
+// Similar to serializeMessage, but doesn't save any files and is looser
+// For use on the frontend / in synchronous environments.
+export function fromModelMessage(message: ModelMessage): Message {
+  const content = fromModelMessageContent(message.content);
+  return {
+    role: message.role,
+    content,
+    ...(message.providerOptions
+      ? { providerOptions: message.providerOptions }
+      : {}),
+  } as SerializedMessage;
+}
+
+export async function serializeOrThrow(
+  message: ModelMessage | Message,
+): Promise<SerializedMessage> {
+  const { content } = await serializeContent(
+    {} as any,
+    {} as any,
+    message.content,
+  );
+  return {
+    role: message.role,
+    content,
+    ...(message.providerOptions
+      ? { providerOptions: message.providerOptions }
+      : {}),
+  } as SerializedMessage;
+}
+
+export function toModelMessage(
+  message: SerializedMessage | ModelMessage,
+): ModelMessage {
   return {
     ...message,
-    content: deserializeContent(message.content),
+    content: toModelMessageContent(message.content),
   } as ModelMessage;
 }
 
+export function docsToModelMessages(messages: MessageDoc[]): ModelMessage[] {
+  return messages
+    .map((m) => m.message)
+    .filter((m) => !!m)
+    .filter((m) => !!m.content.length)
+    .map(toModelMessage);
+}
+
+/**
+ * Merge consecutive tool messages that contain `tool-approval-response` parts
+ * into a single tool message. The AI SDK's `collectToolApprovals` only examines
+ * the last tool message, so when multiple approvals are saved as separate
+ * messages (e.g. approve tool A, then deny tool B), they must be combined
+ * for the SDK to process them all.
+ */
+export function mergeApprovalResponseMessages(
+  messages: ModelMessage[],
+): ModelMessage[] {
+  const result: ModelMessage[] = [];
+  for (const msg of messages) {
+    const prev = result.at(-1);
+    if (
+      msg.role === "tool" &&
+      prev?.role === "tool" &&
+      Array.isArray(msg.content) &&
+      Array.isArray(prev.content) &&
+      hasApprovalResponse(msg.content) &&
+      hasApprovalResponse(prev.content)
+    ) {
+      // Clone before merging to avoid mutating the original message's content array
+      const cloned = { ...prev, content: [...(prev.content as any[])] };
+      result[result.length - 1] = cloned;
+      (cloned.content as any[]).push(...(msg.content as any[]));
+    } else {
+      result.push(msg);
+    }
+  }
+  return result;
+}
+
+function hasApprovalResponse(content: any[]): boolean {
+  return content.some(
+    (p: any) => p.type === "tool-approval-response",
+  );
+}
+
 export function serializeUsage(usage: LanguageModelUsage): Usage {
   return {
     promptTokens: usage.inputTokens ?? 0,
     completionTokens: usage.outputTokens ?? 0,
     totalTokens: usage.totalTokens ?? 0,
     reasoningTokens: usage.reasoningTokens,
+    cachedInputTokens: usage.cachedInputTokens,
   };
 }
 
-export function deserializeUsage(usage: Usage): LanguageModelUsage {
+export function toModelMessageUsage(usage: Usage): LanguageModelUsage {
   return {
     inputTokens: usage.promptTokens,
     outputTokens: usage.completionTokens,
     totalTokens: usage.totalTokens,
     reasoningTokens: usage.reasoningTokens,
     cachedInputTokens: usage.cachedInputTokens,
+    // These detail fields are required by LanguageModelUsage type but we don't
+    // have the granular data, so we provide empty objects with undefined values.
+    inputTokenDetails: {
+      cacheReadTokens: undefined,
+      cacheWriteTokens: undefined,
+      noCacheTokens: undefined,
+    },
+    outputTokenDetails: {
+      textTokens: undefined,
+      reasoningTokens: undefined,
+    },
   };
 }
 
@@ -109,34 +215,57 @@ export function serializeWarnings(
     return undefined;
   }
   return warnings.map((warning) => {
-    if (warning.type !== "unsupported-setting") {
-      return warning;
+    if (warning.type === "compatibility") {
+      return {
+        type: "unsupported-setting",
+        setting: warning.feature,
+        details: warning.details,
+      };
     }
-    return {
-      ...warning,
-      setting: warning.setting.toString(),
-    };
-  });
+    return warning;
+  }) as any;
 }
 
-export function deserializeWarnings(
+export function toModelMessageWarnings(
   warnings: MessageWithMetadata["warnings"],
 ): CallWarning[] | undefined {
-  // We don't need to do anythign here for now
-  return warnings;
+  if (!warnings) {
+    return undefined;
+  }
+  return warnings.map((warning) => {
+    if (warning.type === "unsupported-setting") {
+      return {
+        type: "compatibility",
+        feature: warning.setting,
+        details: warning.details,
+      };
+    }
+    return warning;
+  }) as any;
 }
 
 export async function serializeNewMessagesInStep<TOOLS extends ToolSet>(
   ctx: ActionCtx,
   component: AgentComponent,
   step: StepResult<TOOLS>,
-  metadata: { model: string; provider: string },
-): Promise<MessageWithMetadata[]> {
+  model: ModelOrMetadata | undefined,
+  /**
+   * If provided, these are the new response messages for this step
+   * (pre-sliced by the caller). When not provided, falls back to the
+   * existing heuristic of slicing the last 1-2 messages.
+   *
+   * This is needed for tool approval flows where the SDK adds extra
+   * messages (e.g. approval tool-results) at the beginning of
+   * responseMessages that the old slice(-1/-2) logic would miss.
+   */
+  newResponseMessages?: ModelMessage[],
+): Promise<{ messages: MessageWithMetadata[] }> {
   // If there are tool results, there's another message with the tool results
-  // ref: https://github.com/vercel/ai/blob/main/packages/ai/core/generate-text/to-response-messages.ts
+  // ref: https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/to-response-messages.ts#L120
+  const hasToolMessage = step.response.messages.at(-1)?.role === "tool";
   const assistantFields = {
-    model: metadata.model,
-    provider: metadata.provider,
+    model: model ? getModelName(model) : undefined,
+    provider: model ? getProviderName(model) : undefined,
     providerMetadata: step.providerMetadata,
     reasoning: step.reasoningText,
     reasoningDetails: step.reasoning,
@@ -144,40 +273,42 @@ export async function serializeNewMessagesInStep<TOOLS extends ToolSet>(
     warnings: serializeWarnings(step.warnings),
     finishReason: step.finishReason,
     // Only store the sources on one message
-    sources: step.toolResults.length === 0 ? step.sources : undefined,
+    sources: hasToolMessage ? undefined : step.sources,
   } satisfies Omit<MessageWithMetadata, "message" | "text" | "fileIds">;
-  const toolFields = {
-    sources: step.sources,
-  };
+  const toolFields = { sources: step.sources };
+
+  // Determine which messages to serialize for this step
+  let messagesToSerialize: ModelMessage[];
+  if (newResponseMessages) {
+    messagesToSerialize = newResponseMessages;
+  } else if (hasToolMessage) {
+    messagesToSerialize = step.response.messages.slice(-2);
+  } else if (step.content.length) {
+    messagesToSerialize = step.response.messages.slice(-1);
+  } else {
+    messagesToSerialize = [{ role: "assistant" as const, content: [] }];
+  }
+
   const messages: MessageWithMetadata[] = await Promise.all(
-    (step.toolResults.length > 0
-      ? step.response.messages.slice(-2)
-      : step.response.messages.slice(-1)
-    ).map(async (messageWithId): Promise<MessageWithMetadata> => {
-      const { message, fileIds } = await serializeMessage(
-        ctx,
-        component,
-        messageWithId,
-      );
-      return {
+    messagesToSerialize.map(async (msg): Promise<MessageWithMetadata> => {
+      const { message, fileIds } = await serializeMessage(ctx, component, msg);
+      return parse(vMessageWithMetadata, {
         message,
-        // Let's not store the ID by default here. It's being generated internally
-        // and not referenced elsewhere that we know of.
-        // id: message.id,
         ...(message.role === "tool" ? toolFields : assistantFields),
         text: step.text,
         fileIds,
-      };
+      });
     }),
   );
-  return messages;
+  // TODO: capture step.files separately?
+  return { messages };
 }
 
 export async function serializeObjectResult(
   ctx: ActionCtx,
   component: AgentComponent,
   result: GenerateObjectResult<unknown>,
-  metadata: { model: string; provider: string },
+  model: ModelOrMetadata | undefined,
 ): Promise<{ messages: MessageWithMetadata[] }> {
   const text = JSON.stringify(result.object);
 
@@ -189,9 +320,8 @@ export async function serializeObjectResult(
     messages: [
       {
         message,
-        id: result.response.id,
-        model: metadata.model,
-        provider: metadata.provider,
+        model: model ? getModelName(model) : undefined,
+        provider: model ? getProviderName(model) : undefined,
         providerMetadata: result.providerMetadata,
         finishReason: result.finishReason,
         text,
@@ -203,8 +333,18 @@ export async function serializeObjectResult(
   };
 }
 
+function getMimeOrMediaType(part: { mediaType?: string; mimeType?: string }) {
+  if ("mediaType" in part) {
+    return part.mediaType;
+  }
+  if ("mimeType" in part) {
+    return part.mimeType;
+  }
+  return undefined;
+}
+
 export async function serializeContent(
-  ctx: ActionCtx | RunMutationCtx,
+  ctx: ActionCtx | MutationCtx,
   component: AgentComponent,
   content: Content | Message["content"],
 ): Promise<{ content: SerializedContent; fileIds?: string[] }> {
@@ -212,23 +352,24 @@ export async function serializeContent(
     return { content };
   }
   const fileIds: string[] = [];
-  function getMimeType(part: { mediaType?: string; mimeType?: string }) {
-    if ("mediaType" in part) {
-      return part.mediaType;
-    }
-    if ("mimeType" in part) {
-      return part.mimeType;
-    }
-    return undefined;
-  }
   const serialized = await Promise.all(
     content.map(async (part) => {
+      const metadata: {
+        providerOptions?: ProviderOptions;
+        providerMetadata?: ProviderMetadata;
+      } = {};
+      if ("providerOptions" in part) {
+        metadata.providerOptions = part.providerOptions as ProviderOptions;
+      }
+      if ("providerMetadata" in part) {
+        metadata.providerMetadata = part.providerMetadata as ProviderMetadata;
+      }
       switch (part.type) {
         case "text": {
           return {
             type: part.type,
             text: part.text,
-            providerOptions: part.providerOptions,
+            ...metadata,
           } satisfies Infer<typeof vTextPart>;
         }
         case "image": {
@@ -241,7 +382,7 @@ export async function serializeContent(
               ctx,
               component,
               new Blob([image], {
-                type: getMimeType(part) || guessMimeType(image),
+                type: getMimeOrMediaType(part) || guessMimeType(image),
               }),
             );
             image = file.url;
@@ -249,8 +390,8 @@ export async function serializeContent(
           }
           return {
             type: part.type,
-            mimeType: getMimeType(part),
-            providerOptions: part.providerOptions,
+            mediaType: getMimeOrMediaType(part),
+            ...metadata,
             image,
           } satisfies Infer<typeof vImagePart>;
         }
@@ -260,7 +401,7 @@ export async function serializeContent(
             const { file } = await storeFile(
               ctx,
               component,
-              new Blob([data], { type: getMimeType(part) }),
+              new Blob([data], { type: getMimeOrMediaType(part) }),
             );
             data = file.url;
             fileIds.push(file.fileId);
@@ -269,118 +410,295 @@ export async function serializeContent(
             type: part.type,
             data,
             filename: part.filename,
-            mimeType: getMimeType(part)!,
-            providerOptions: part.providerOptions,
+            mediaType: getMimeOrMediaType(part)!,
+            ...metadata,
           } satisfies Infer<typeof vFilePart>;
         }
         case "tool-call": {
-          const args = "input" in part ? part.input : part.args;
+          // Handle legacy data where only args field exists
+          const input = part.input ?? (part as any)?.args ?? {};
           return {
             type: part.type,
-            args: args ?? null,
+            input,
+            /** @deprecated Use `input` instead. */
+            args: input,
             toolCallId: part.toolCallId,
             toolName: part.toolName,
-            providerOptions: part.providerOptions,
             providerExecuted: part.providerExecuted,
+            ...metadata,
           } satisfies Infer<typeof vToolCallPart>;
         }
         case "tool-result": {
-          const result = "output" in part ? part.output : part.result;
-          return {
-            type: part.type,
-            result: result ?? null,
-            toolCallId: part.toolCallId,
-            toolName: part.toolName,
-            providerOptions: part.providerOptions,
-          } satisfies Infer<typeof vToolResultPart>;
+          return normalizeToolResult(part, metadata);
         }
         case "reasoning": {
           return {
             type: part.type,
             text: part.text,
-            providerOptions: part.providerOptions,
+            ...metadata,
           } satisfies Infer<typeof vReasoningPart>;
         }
+        // Not in current generation output, but could be in historical messages
         case "redacted-reasoning": {
           return {
             type: part.type,
             data: part.data,
-            providerOptions: part.providerOptions,
+            ...metadata,
           } satisfies Infer<typeof vRedactedReasoningPart>;
         }
+        case "source": {
+          return part satisfies Infer<typeof vSourcePart>;
+        }
+        case "tool-approval-request": {
+          return {
+            type: part.type,
+            approvalId: part.approvalId,
+            toolCallId: part.toolCallId,
+            ...metadata,
+          } satisfies Infer<typeof vToolApprovalRequest>;
+        }
+        case "tool-approval-response": {
+          return {
+            type: part.type,
+            approvalId: part.approvalId,
+            approved: part.approved,
+            reason: part.reason,
+            providerExecuted: part.providerExecuted,
+            ...metadata,
+          } satisfies Infer<typeof vToolApprovalResponse>;
+        }
         default:
-          return part satisfies Infer<typeof vContent>;
+          return null;
       }
     }),
   );
   return {
-    content: serialized as SerializedContent,
+    content: serialized.filter((p) => p !== null) as SerializedContent,
     fileIds: fileIds.length > 0 ? fileIds : undefined,
   };
 }
 
-export function deserializeContent(content: SerializedContent): Content {
+export function fromModelMessageContent(content: Content): Message["content"] {
   if (typeof content === "string") {
     return content;
   }
-  return content.map((part) => {
-    switch (part.type) {
-      case "text":
-        return {
-          type: part.type,
-          text: part.text,
-          providerOptions: part.providerOptions,
-        } satisfies TextPart;
-      case "image":
-        return {
-          type: part.type,
-          image: deserializeUrl(part.image),
-          mediaType: part.mimeType,
-          providerOptions: part.providerOptions,
-        } satisfies ImagePart;
-      case "file":
-        return {
-          type: part.type,
-          data: deserializeUrl(part.data),
-          filename: part.filename,
-          mediaType: part.mimeType,
-          providerOptions: part.providerOptions,
-        } satisfies FilePart;
-      case "tool-call":
-        return {
-          type: part.type,
-          input: part.args ?? null,
-          providerExecuted: part.providerExecuted,
-          toolCallId: part.toolCallId,
-          toolName: part.toolName,
-          providerOptions: part.providerOptions,
-        } satisfies ToolCallPart;
-      case "tool-result":
-        return {
-          type: part.type,
-          output: part.result ?? null,
-          toolCallId: part.toolCallId,
-          toolName: part.toolName,
-          providerOptions: part.providerOptions,
-        } satisfies ToolResultPart;
-      case "reasoning":
-        return {
-          type: part.type,
-          text: part.text,
-          providerMetadata: part.providerOptions,
-          state: part.state,
-        } satisfies ReasoningUIPart;
-      case "redacted-reasoning":
-        // TODO: should we just drop this?
-        return {
-          type: "reasoning",
-          text: part.data,
-          providerMetadata: part.providerOptions,
-        } satisfies ReasoningUIPart;
-      default:
-        return part satisfies Content;
-    }
-  }) as Content;
+  return content
+    .map((part) => {
+      const metadata: {
+        providerOptions?: ProviderOptions;
+        providerMetadata?: ProviderMetadata;
+      } = {};
+      if ("providerOptions" in part) {
+        metadata.providerOptions = part.providerOptions as ProviderOptions;
+      }
+      if ("providerMetadata" in part) {
+        metadata.providerMetadata = part.providerMetadata as ProviderMetadata;
+      }
+      switch (part.type) {
+        case "text":
+          return part satisfies Infer<typeof vTextPart>;
+        case "image":
+          return {
+            type: part.type,
+            mediaType: getMimeOrMediaType(part),
+            ...metadata,
+            image: serializeDataOrUrl(part.image),
+          } satisfies Infer<typeof vImagePart>;
+        case "file":
+          return {
+            type: part.type,
+            data: serializeDataOrUrl(part.data),
+            filename: part.filename,
+            mediaType: getMimeOrMediaType(part)!,
+            ...metadata,
+          } satisfies Infer<typeof vFilePart>;
+        case "tool-call":
+          // Handle legacy data where only args field exists
+          return {
+            type: part.type,
+            input: part.input ?? (part as any)?.args ?? {},
+            /** @deprecated Use `input` instead. */
+            args: part.input ?? (part as any)?.args ?? {},
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            providerExecuted: part.providerExecuted,
+            ...metadata,
+          } satisfies Infer<typeof vToolCallPart>;
+        case "tool-result":
+          return normalizeToolResult(part, metadata);
+        case "reasoning":
+          return {
+            type: part.type,
+            text: part.text,
+            ...metadata,
+          } satisfies Infer<typeof vReasoningPart>;
+        case "tool-approval-request":
+          return {
+            type: part.type,
+            approvalId: part.approvalId,
+            toolCallId: part.toolCallId,
+            ...metadata,
+          } satisfies Infer<typeof vToolApprovalRequest>;
+        case "tool-approval-response":
+          return {
+            type: part.type,
+            approvalId: part.approvalId,
+            approved: part.approved,
+            reason: part.reason,
+            providerExecuted: part.providerExecuted,
+            ...metadata,
+          } satisfies Infer<typeof vToolApprovalResponse>;
+        // Not in current generation output, but could be in historical messages
+        default:
+          return null;
+      }
+    })
+    .filter((p) => p !== null) as Message["content"];
+}
+
+export function toModelMessageContent(
+  content: SerializedContent | ModelMessage["content"],
+): Content {
+  if (typeof content === "string") {
+    return content;
+  }
+  return content
+    .map((part) => {
+      const metadata: {
+        providerOptions?: ProviderOptions;
+        providerMetadata?: ProviderMetadata;
+      } = {};
+      if ("providerOptions" in part) {
+        metadata.providerOptions = part.providerOptions;
+      }
+      if ("providerMetadata" in part) {
+        metadata.providerMetadata = part.providerMetadata;
+      }
+      switch (part.type) {
+        case "text":
+          return {
+            type: part.type,
+            text: part.text,
+            ...metadata,
+          } satisfies TextPart;
+        case "image":
+          return {
+            type: part.type,
+            image: toModelMessageDataOrUrl(part.image),
+            mediaType: getMimeOrMediaType(part),
+            ...metadata,
+          } satisfies ImagePart;
+        case "file":
+          return {
+            type: part.type,
+            data: toModelMessageDataOrUrl(part.data),
+            filename: part.filename,
+            mediaType: getMimeOrMediaType(part)!,
+            ...metadata,
+          } satisfies FilePart;
+        case "tool-call": {
+          // Handle legacy data where only args field exists
+          const input = part.input ?? (part as any)?.args ?? {};
+          return {
+            type: part.type,
+            input,
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            providerExecuted: part.providerExecuted,
+            ...metadata,
+          } satisfies ToolCallPart;
+        }
+        case "tool-result": {
+          return normalizeToolResult(part, metadata);
+        }
+        case "reasoning":
+          return {
+            type: part.type,
+            text: part.text,
+            ...metadata,
+          } satisfies ReasoningPart;
+        case "redacted-reasoning":
+          // TODO: should we just drop this?
+          return {
+            type: "reasoning",
+            text: "",
+            ...metadata,
+            providerOptions: metadata.providerOptions
+              ? {
+                  ...Object.fromEntries(
+                    Object.entries(metadata.providerOptions ?? {}).map(
+                      ([key, value]) => [
+                        key,
+                        { ...value, redactedData: part.data },
+                      ],
+                    ),
+                  ),
+                }
+              : undefined,
+          } satisfies ReasoningPart;
+        case "source":
+          return part satisfies SourcePart;
+        case "tool-approval-request":
+          return {
+            type: part.type,
+            approvalId: part.approvalId,
+            toolCallId: part.toolCallId,
+            ...metadata,
+          } satisfies Infer<typeof vToolApprovalRequest>;
+        case "tool-approval-response":
+          return {
+            type: part.type,
+            approvalId: part.approvalId,
+            approved: part.approved,
+            reason: part.reason,
+            providerExecuted: part.providerExecuted,
+            ...metadata,
+          } satisfies Infer<typeof vToolApprovalResponse>;
+        default:
+          return null;
+      }
+    })
+    .filter((p) => p !== null) as Content;
+}
+
+export function normalizeToolOutput(
+  result: string | JSONValue | undefined,
+): ToolResultPart["output"] {
+  if (typeof result === "string") {
+    return {
+      type: "text",
+      value: result,
+    };
+  }
+  if (validate(vToolResultOutput, result)) {
+    return result;
+  }
+  return {
+    type: "json",
+    value: result ?? null,
+  };
+}
+
+function normalizeToolResult(
+  part: ToolResultPart | Infer<typeof vToolResultPart>,
+  metadata: {
+    providerOptions?: ProviderOptions;
+    providerMetadata?: ProviderMetadata;
+  },
+): ToolResultPart & Infer<typeof vToolResultPart> {
+  return {
+    type: part.type,
+    output: part.output
+      ? validate(vToolResultOutput, part.output)
+        ? (part.output as any)
+        : normalizeToolOutput(JSON.stringify(part.output))
+      : normalizeToolOutput("result" in part ? part.result : undefined),
+    toolCallId: part.toolCallId,
+    toolName: part.toolName,
+    // Preserve isError flag for error reporting
+    ...("isError" in part && part.isError ? { isError: true } : {}),
+    ...metadata,
+  } satisfies ToolResultPart;
 }
 
 /**
@@ -473,9 +791,12 @@ export function serializeDataOrUrl(
   ) as ArrayBuffer;
 }
 
-export function deserializeUrl(
-  urlOrString: string | ArrayBuffer,
+export function toModelMessageDataOrUrl(
+  urlOrString: string | ArrayBuffer | URL | DataContent,
 ): URL | DataContent {
+  if (urlOrString instanceof URL) {
+    return urlOrString;
+  }
   if (typeof urlOrString === "string") {
     if (
       urlOrString.startsWith("http://") ||
@@ -492,7 +813,7 @@ export function toUIFilePart(part: ImagePart | FilePart): FileUIPart {
   const dataOrUrl = part.type === "image" ? part.image : part.data;
   const url =
     dataOrUrl instanceof ArrayBuffer
-      ? encodeBase64(dataOrUrl)
+      ? convertUint8ArrayToBase64(new Uint8Array(dataOrUrl))
       : dataOrUrl.toString();
 
   return {
@@ -504,10 +825,6 @@ export function toUIFilePart(part: ImagePart | FilePart): FileUIPart {
   };
 }
 
-function encodeBase64(data: ArrayBuffer): string {
-  return Buffer.from(data).toString("base64");
-}
-
 // Currently unused
 // export function toModelMessages(args: {
 //   messages?: ModelMessage[] | AIMessageWithoutId[];