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

package/dist/mapping.js

@@ -1,38 +1,115 @@
 import {} from "ai";
+import { vMessageWithMetadata, vToolResultOutput, vToolApprovalRequest, vToolApprovalResponse, } from "./validators.js";
 import { MAX_FILE_SIZE, storeFile } from "./client/files.js";
-import { omit } from "convex-helpers";
-export async function serializeMessage(ctx, component, messageWithId) {
-    const message = "id" in messageWithId ? omit(messageWithId, ["id"]) : messageWithId;
+import { convertUint8ArrayToBase64, } from "@ai-sdk/provider-utils";
+import { parse, validate } from "convex-helpers/validators";
+import { getModelName, getProviderName, } from "./shared.js";
+export async function serializeMessage(ctx, component, message) {
     const { content, fileIds } = await serializeContent(ctx, component, message.content);
     return {
         message: {
-            ...message,
+            role: message.role,
             content,
+            ...(message.providerOptions
+                ? { providerOptions: message.providerOptions }
+                : {}),
         },
         fileIds,
     };
 }
-export function deserializeMessage(message) {
+// Similar to serializeMessage, but doesn't save any files and is looser
+// For use on the frontend / in synchronous environments.
+export function fromModelMessage(message) {
+    const content = fromModelMessageContent(message.content);
+    return {
+        role: message.role,
+        content,
+        ...(message.providerOptions
+            ? { providerOptions: message.providerOptions }
+            : {}),
+    };
+}
+export async function serializeOrThrow(message) {
+    const { content } = await serializeContent({}, {}, message.content);
+    return {
+        role: message.role,
+        content,
+        ...(message.providerOptions
+            ? { providerOptions: message.providerOptions }
+            : {}),
+    };
+}
+export function toModelMessage(message) {
     return {
         ...message,
-        content: deserializeContent(message.content),
+        content: toModelMessageContent(message.content),
     };
 }
+export function docsToModelMessages(messages) {
+    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) {
+    const result = [];
+    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] };
+            result[result.length - 1] = cloned;
+            cloned.content.push(...msg.content);
+        }
+        else {
+            result.push(msg);
+        }
+    }
+    return result;
+}
+function hasApprovalResponse(content) {
+    return content.some((p) => p.type === "tool-approval-response");
+}
 export function serializeUsage(usage) {
     return {
         promptTokens: usage.inputTokens ?? 0,
         completionTokens: usage.outputTokens ?? 0,
         totalTokens: usage.totalTokens ?? 0,
         reasoningTokens: usage.reasoningTokens,
+        cachedInputTokens: usage.cachedInputTokens,
     };
 }
-export function deserializeUsage(usage) {
+export function toModelMessageUsage(usage) {
     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,
+        },
     };
 }
 export function serializeWarnings(warnings) {
@@ -40,25 +117,48 @@ export function serializeWarnings(warnings) {
         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;
     });
 }
-export function deserializeWarnings(warnings) {
-    // We don't need to do anythign here for now
-    return warnings;
+export function toModelMessageWarnings(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;
+    });
 }
-export async function serializeNewMessagesInStep(ctx, component, step, metadata) {
+export async function serializeNewMessagesInStep(ctx, component, step, model, 
+/**
+ * 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) {
     // 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,
@@ -66,28 +166,36 @@ export async function serializeNewMessagesInStep(ctx, component, step, metadata)
         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,
     };
-    const toolFields = {
-        sources: step.sources,
-    };
-    const messages = await Promise.all((step.toolResults.length > 0
-        ? step.response.messages.slice(-2)
-        : step.response.messages.slice(-1)).map(async (messageWithId) => {
-        const { message, fileIds } = await serializeMessage(ctx, component, messageWithId);
-        return {
+    const toolFields = { sources: step.sources };
+    // Determine which messages to serialize for this step
+    let messagesToSerialize;
+    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", content: [] }];
+    }
+    const messages = await Promise.all(messagesToSerialize.map(async (msg) => {
+        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, component, result, metadata) {
+export async function serializeObjectResult(ctx, component, result, model) {
     const text = JSON.stringify(result.object);
     const { message, fileIds } = await serializeMessage(ctx, component, {
         role: "assistant",
@@ -97,9 +205,8 @@ export async function serializeObjectResult(ctx, component, result, metadata) {
         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,
@@ -110,27 +217,34 @@ export async function serializeObjectResult(ctx, component, result, metadata) {
         ],
     };
 }
+function getMimeOrMediaType(part) {
+    if ("mediaType" in part) {
+        return part.mediaType;
+    }
+    if ("mimeType" in part) {
+        return part.mimeType;
+    }
+    return undefined;
+}
 export async function serializeContent(ctx, component, content) {
     if (typeof content === "string") {
         return { content };
     }
     const fileIds = [];
-    function getMimeType(part) {
-        if ("mediaType" in part) {
-            return part.mediaType;
+    const serialized = await Promise.all(content.map(async (part) => {
+        const metadata = {};
+        if ("providerOptions" in part) {
+            metadata.providerOptions = part.providerOptions;
         }
-        if ("mimeType" in part) {
-            return part.mimeType;
+        if ("providerMetadata" in part) {
+            metadata.providerMetadata = part.providerMetadata;
         }
-        return undefined;
-    }
-    const serialized = await Promise.all(content.map(async (part) => {
         switch (part.type) {
             case "text": {
                 return {
                     type: part.type,
                     text: part.text,
-                    providerOptions: part.providerOptions,
+                    ...metadata,
                 };
             }
             case "image": {
@@ -138,22 +252,22 @@ export async function serializeContent(ctx, component, content) {
                 if (image instanceof ArrayBuffer &&
                     image.byteLength > MAX_FILE_SIZE) {
                     const { file } = await storeFile(ctx, component, new Blob([image], {
-                        type: getMimeType(part) || guessMimeType(image),
+                        type: getMimeOrMediaType(part) || guessMimeType(image),
                     }));
                     image = file.url;
                     fileIds.push(file.fileId);
                 }
                 return {
                     type: part.type,
-                    mimeType: getMimeType(part),
-                    providerOptions: part.providerOptions,
+                    mediaType: getMimeOrMediaType(part),
+                    ...metadata,
                     image,
                 };
             }
             case "file": {
                 let data = serializeDataOrUrl(part.data);
                 if (data instanceof ArrayBuffer && data.byteLength > MAX_FILE_SIZE) {
-                    const { file } = await storeFile(ctx, component, new Blob([data], { type: getMimeType(part) }));
+                    const { file } = await storeFile(ctx, component, new Blob([data], { type: getMimeOrMediaType(part) }));
                     data = file.url;
                     fileIds.push(file.fileId);
                 }
@@ -161,116 +275,270 @@ export async function serializeContent(ctx, component, content) {
                     type: part.type,
                     data,
                     filename: part.filename,
-                    mimeType: getMimeType(part),
-                    providerOptions: part.providerOptions,
+                    mediaType: getMimeOrMediaType(part),
+                    ...metadata,
                 };
             }
             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?.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,
                 };
             }
             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,
-                };
+                return normalizeToolResult(part, metadata);
             }
             case "reasoning": {
                 return {
                     type: part.type,
                     text: part.text,
-                    providerOptions: part.providerOptions,
+                    ...metadata,
                 };
             }
+            // 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,
                 };
             }
-            default:
+            case "source": {
                 return part;
+            }
+            case "tool-approval-request": {
+                return {
+                    type: part.type,
+                    approvalId: part.approvalId,
+                    toolCallId: part.toolCallId,
+                    ...metadata,
+                };
+            }
+            case "tool-approval-response": {
+                return {
+                    type: part.type,
+                    approvalId: part.approvalId,
+                    approved: part.approved,
+                    reason: part.reason,
+                    providerExecuted: part.providerExecuted,
+                    ...metadata,
+                };
+            }
+            default:
+                return null;
         }
     }));
     return {
-        content: serialized,
+        content: serialized.filter((p) => p !== null),
         fileIds: fileIds.length > 0 ? fileIds : undefined,
     };
 }
-export function deserializeContent(content) {
+export function fromModelMessageContent(content) {
     if (typeof content === "string") {
         return content;
     }
-    return content.map((part) => {
+    return content
+        .map((part) => {
+        const metadata = {};
+        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,
-                    providerOptions: part.providerOptions,
-                };
+                return part;
             case "image":
                 return {
                     type: part.type,
-                    image: deserializeUrl(part.image),
-                    mediaType: part.mimeType,
-                    providerOptions: part.providerOptions,
+                    mediaType: getMimeOrMediaType(part),
+                    ...metadata,
+                    image: serializeDataOrUrl(part.image),
                 };
             case "file":
                 return {
                     type: part.type,
-                    data: deserializeUrl(part.data),
+                    data: serializeDataOrUrl(part.data),
                     filename: part.filename,
-                    mediaType: part.mimeType,
-                    providerOptions: part.providerOptions,
+                    mediaType: getMimeOrMediaType(part),
+                    ...metadata,
                 };
             case "tool-call":
+                // Handle legacy data where only args field exists
                 return {
                     type: part.type,
-                    input: part.args ?? null,
-                    providerExecuted: part.providerExecuted,
+                    input: part.input ?? part?.args ?? {},
+                    /** @deprecated Use `input` instead. */
+                    args: part.input ?? part?.args ?? {},
                     toolCallId: part.toolCallId,
                     toolName: part.toolName,
-                    providerOptions: part.providerOptions,
+                    providerExecuted: part.providerExecuted,
+                    ...metadata,
                 };
             case "tool-result":
+                return normalizeToolResult(part, metadata);
+            case "reasoning":
                 return {
                     type: part.type,
-                    output: part.result ?? null,
+                    text: part.text,
+                    ...metadata,
+                };
+            case "tool-approval-request":
+                return {
+                    type: part.type,
+                    approvalId: part.approvalId,
+                    toolCallId: part.toolCallId,
+                    ...metadata,
+                };
+            case "tool-approval-response":
+                return {
+                    type: part.type,
+                    approvalId: part.approvalId,
+                    approved: part.approved,
+                    reason: part.reason,
+                    providerExecuted: part.providerExecuted,
+                    ...metadata,
+                };
+            // Not in current generation output, but could be in historical messages
+            default:
+                return null;
+        }
+    })
+        .filter((p) => p !== null);
+}
+export function toModelMessageContent(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    return content
+        .map((part) => {
+        const metadata = {};
+        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,
+                };
+            case "image":
+                return {
+                    type: part.type,
+                    image: toModelMessageDataOrUrl(part.image),
+                    mediaType: getMimeOrMediaType(part),
+                    ...metadata,
+                };
+            case "file":
+                return {
+                    type: part.type,
+                    data: toModelMessageDataOrUrl(part.data),
+                    filename: part.filename,
+                    mediaType: getMimeOrMediaType(part),
+                    ...metadata,
+                };
+            case "tool-call": {
+                // Handle legacy data where only args field exists
+                const input = part.input ?? part?.args ?? {};
+                return {
+                    type: part.type,
+                    input,
                     toolCallId: part.toolCallId,
                     toolName: part.toolName,
-                    providerOptions: part.providerOptions,
+                    providerExecuted: part.providerExecuted,
+                    ...metadata,
                 };
+            }
+            case "tool-result": {
+                return normalizeToolResult(part, metadata);
+            }
             case "reasoning":
                 return {
                     type: part.type,
                     text: part.text,
-                    providerMetadata: part.providerOptions,
-                    state: part.state,
+                    ...metadata,
                 };
             case "redacted-reasoning":
                 // TODO: should we just drop this?
                 return {
                     type: "reasoning",
-                    text: part.data,
-                    providerMetadata: part.providerOptions,
+                    text: "",
+                    ...metadata,
+                    providerOptions: metadata.providerOptions
+                        ? {
+                            ...Object.fromEntries(Object.entries(metadata.providerOptions ?? {}).map(([key, value]) => [
+                                key,
+                                { ...value, redactedData: part.data },
+                            ])),
+                        }
+                        : undefined,
                 };
-            default:
+            case "source":
                 return part;
+            case "tool-approval-request":
+                return {
+                    type: part.type,
+                    approvalId: part.approvalId,
+                    toolCallId: part.toolCallId,
+                    ...metadata,
+                };
+            case "tool-approval-response":
+                return {
+                    type: part.type,
+                    approvalId: part.approvalId,
+                    approved: part.approved,
+                    reason: part.reason,
+                    providerExecuted: part.providerExecuted,
+                    ...metadata,
+                };
+            default:
+                return null;
         }
-    });
+    })
+        .filter((p) => p !== null);
+}
+export function normalizeToolOutput(result) {
+    if (typeof result === "string") {
+        return {
+            type: "text",
+            value: result,
+        };
+    }
+    if (validate(vToolResultOutput, result)) {
+        return result;
+    }
+    return {
+        type: "json",
+        value: result ?? null,
+    };
+}
+function normalizeToolResult(part, metadata) {
+    return {
+        type: part.type,
+        output: part.output
+            ? validate(vToolResultOutput, part.output)
+                ? part.output
+                : 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,
+    };
 }
 /**
  * Return a best-guess MIME type based on the magic-number signature
@@ -362,7 +630,10 @@ export function serializeDataOrUrl(dataOrUrl) {
     }
     return dataOrUrl.buffer.slice(dataOrUrl.byteOffset, dataOrUrl.byteOffset + dataOrUrl.byteLength);
 }
-export function deserializeUrl(urlOrString) {
+export function toModelMessageDataOrUrl(urlOrString) {
+    if (urlOrString instanceof URL) {
+        return urlOrString;
+    }
     if (typeof urlOrString === "string") {
         if (urlOrString.startsWith("http://") ||
             urlOrString.startsWith("https://")) {
@@ -375,7 +646,7 @@ export function deserializeUrl(urlOrString) {
 export function toUIFilePart(part) {
     const dataOrUrl = part.type === "image" ? part.image : part.data;
     const url = dataOrUrl instanceof ArrayBuffer
-        ? encodeBase64(dataOrUrl)
+        ? convertUint8ArrayToBase64(new Uint8Array(dataOrUrl))
         : dataOrUrl.toString();
     return {
         type: "file",
@@ -385,9 +656,6 @@ export function toUIFilePart(part) {
         providerMetadata: part.providerOptions,
     };
 }
-function encodeBase64(data) {
-    return Buffer.from(data).toString("base64");
-}
 // Currently unused
 // export function toModelMessages(args: {
 //   messages?: ModelMessage[] | AIMessageWithoutId[];