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

package/src/fromUIMessages.test.ts

@@ -0,0 +1,497 @@
+import { describe, expect, it } from "vitest";
+import type { MessageDoc } from "./client/index.js";
+import type { UIMessage } from "./UIMessages.js";
+import { fromUIMessages, toUIMessages } from "./UIMessages.js";
+
+// Helper to create a base message doc
+function baseMessageDoc<T = unknown>(
+  overrides: Partial<MessageDoc & { streaming?: boolean; metadata?: T }> = {},
+): MessageDoc & { streaming?: boolean; metadata?: T } {
+  return {
+    _id: "msg1",
+    _creationTime: Date.now(),
+    order: 0,
+    stepOrder: 0,
+    status: "success",
+    threadId: "thread1",
+    tool: false,
+    ...overrides,
+  };
+}
+
+describe("fromUIMessages round-trip tests", () => {
+  it("preserves essential data for simple user message", async () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "user",
+          content: "Hello world!",
+        },
+        text: "Hello world!",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = await fromUIMessages(uiMessages, {
+      threadId: "thread1",
+    });
+
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("user");
+    expect(uiMessages[0].text).toBe("Hello world!");
+
+    expect(backToMessageDocs).toHaveLength(1);
+    expect(backToMessageDocs[0].text).toBe("Hello world!");
+    expect(backToMessageDocs[0].threadId).toBe("thread1");
+
+    // Content gets normalized to array format
+    expect(Array.isArray(backToMessageDocs[0].message?.content)).toBe(true);
+    if (Array.isArray(backToMessageDocs[0].message?.content)) {
+      expect(backToMessageDocs[0].message.content[0]).toMatchObject({
+        type: "text",
+        text: "Hello world!",
+      });
+    }
+  });
+
+  it("preserves essential data for assistant message", async () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: "Hi there! How can I help?",
+        },
+        text: "Hi there! How can I help?",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = await fromUIMessages(uiMessages, {
+      threadId: "thread1",
+    });
+
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("assistant");
+    expect(uiMessages[0].text).toBe("Hi there! How can I help?");
+
+    expect(backToMessageDocs).toHaveLength(1);
+    expect(backToMessageDocs[0].text).toBe("Hi there! How can I help?");
+  });
+
+  it("preserves system messages correctly", async () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "system",
+          content: "You are a helpful assistant.",
+        },
+        text: "You are a helpful assistant.",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = await fromUIMessages(uiMessages, {
+      threadId: "thread1",
+    });
+
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("system");
+    expect(uiMessages[0].text).toBe("You are a helpful assistant.");
+
+    expect(backToMessageDocs).toHaveLength(1);
+    expect(backToMessageDocs[0].text).toBe("You are a helpful assistant.");
+    expect(backToMessageDocs[0].message?.role).toBe("system");
+
+    // System content stays as string
+    expect(backToMessageDocs[0].message?.content).toBe(
+      "You are a helpful assistant.",
+    );
+  });
+
+  it("preserves reasoning in assistant messages", async () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "reasoning",
+              text: "Let me think about this...",
+            },
+            {
+              type: "text",
+              text: "Here's my response.",
+            },
+          ],
+        },
+        text: "Here's my response.",
+        reasoning: "Let me think about this...",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = await fromUIMessages(uiMessages, {
+      threadId: "thread1",
+    });
+
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].text).toBe("Here's my response.");
+
+    // Check that reasoning parts are preserved in UI message
+    const reasoningParts = uiMessages[0].parts.filter(
+      (part) => part.type === "reasoning",
+    );
+    expect(reasoningParts).toHaveLength(1);
+    expect(reasoningParts[0]).toMatchObject({
+      type: "reasoning",
+      text: "Let me think about this...",
+    });
+
+    expect(backToMessageDocs).toHaveLength(1);
+    expect(backToMessageDocs[0].text).toBe("Here's my response.");
+    expect(backToMessageDocs[0].reasoning).toBe("Let me think about this...");
+  });
+
+  it("handles tool calls and groups them correctly", async () => {
+    // Tool calls get grouped into single UI message but expanded back to multiple message docs
+    const originalMessages = [
+      baseMessageDoc({
+        _id: "msg1",
+        order: 1,
+        stepOrder: 1,
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "tool-call",
+              toolName: "calculator",
+              toolCallId: "call1",
+              input: { operation: "add", a: 2, b: 3 },
+              args: { operation: "add", a: 2, b: 3 },
+            },
+          ],
+        },
+        tool: true,
+      }),
+      baseMessageDoc({
+        _id: "msg2",
+        order: 1,
+        stepOrder: 2,
+        message: {
+          role: "tool",
+          content: [
+            {
+              type: "tool-result",
+              toolCallId: "call1",
+              toolName: "calculator",
+              output: {
+                type: "json",
+                value: { result: 5 },
+              },
+            },
+          ],
+        },
+        tool: true,
+      }),
+    ];
+    const toTest = [originalMessages, [...originalMessages].reverse()];
+    for (const messages of toTest) {
+      const uiMessages = toUIMessages(messages);
+      const backToMessageDocs = await fromUIMessages(uiMessages, {
+        threadId: "thread1",
+      });
+
+      // Should be grouped into single UI message
+      expect(uiMessages).toHaveLength(1);
+      const uiMessage = uiMessages[0];
+      expect(uiMessage.role).toBe("assistant");
+      expect(uiMessage.id).toBe("msg1");
+
+      // Check tool parts exist
+      const toolParts = uiMessage.parts.filter(
+        (part) => part.type === "tool-calculator",
+      );
+      expect(toolParts).toHaveLength(1);
+      expect(toolParts[0]).toMatchObject({
+        type: "tool-calculator",
+        toolCallId: "call1",
+        state: "output-available",
+        input: { operation: "add", a: 2, b: 3 },
+        output: { result: 5 },
+      });
+
+      // Should expand back to multiple message docs
+      expect(backToMessageDocs.length).toBeGreaterThanOrEqual(1);
+
+      // Check that tool information is preserved
+      const toolMessages = backToMessageDocs.filter((msg) => msg.tool);
+      expect(toolMessages.length).toBeGreaterThan(0);
+      expect(toolMessages[0].stepOrder).toBe(1);
+      expect(toolMessages[1].stepOrder).toBe(2);
+    }
+  });
+
+  it("preserves file attachments in user messages", async () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "user",
+          content: [
+            {
+              type: "text",
+              text: "What's in this image?",
+            },
+            {
+              type: "file",
+              mimeType: "image/png",
+              data: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
+            },
+          ],
+        },
+        text: "What's in this image?",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = await fromUIMessages(uiMessages, {
+      threadId: "thread1",
+    });
+
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("user");
+    expect(uiMessages[0].text).toBe("What's in this image?");
+
+    // Check file parts exist in UI message
+    const fileParts = uiMessages[0].parts.filter(
+      (part) => part.type === "file",
+    );
+    expect(fileParts).toHaveLength(1);
+
+    expect(backToMessageDocs).toHaveLength(1);
+    expect(backToMessageDocs[0].text).toBe("What's in this image?");
+
+    // Check file content is preserved
+    const content = backToMessageDocs[0].message?.content;
+    expect(Array.isArray(content)).toBe(true);
+    if (Array.isArray(content)) {
+      const fileContent = content.find((c) => c.type === "file");
+      expect(fileContent).toBeDefined();
+      expect(fileContent).toMatchObject({
+        type: "file",
+        mediaType: "image/png",
+      });
+    }
+  });
+
+  it("preserves sources correctly", async () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "text",
+              text: "I found some relevant sources.",
+            },
+          ],
+        },
+        text: "I found some relevant sources.",
+        sources: [
+          {
+            type: "source",
+            sourceType: "url",
+            id: "source1",
+            url: "https://example.com",
+            title: "Example Source",
+          },
+          {
+            type: "source",
+            sourceType: "document",
+            id: "source2",
+            mediaType: "application/pdf",
+            title: "Document Source",
+          },
+        ],
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = await fromUIMessages(uiMessages, {
+      threadId: "thread1",
+    });
+
+    expect(uiMessages).toHaveLength(1);
+
+    // Check source parts exist in UI message
+    const sourceParts = uiMessages[0].parts.filter(
+      (part) => part.type === "source-url" || part.type === "source-document",
+    );
+    expect(sourceParts).toHaveLength(2);
+
+    expect(backToMessageDocs).toHaveLength(1);
+    expect(backToMessageDocs[0].sources).toHaveLength(2);
+    expect(backToMessageDocs[0].sources![0]).toMatchObject({
+      type: "source",
+      sourceType: "url",
+      id: "source1",
+      url: "https://example.com",
+      title: "Example Source",
+    });
+  });
+
+  it("preserves metadata when provided", async () => {
+    const testMetadata = {
+      customField: "customValue",
+      timestamp: Date.now(),
+    };
+
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "user",
+          content: "Test message",
+        },
+        text: "Test message",
+        metadata: testMetadata,
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = await fromUIMessages(uiMessages, {
+      threadId: "thread1",
+    });
+
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].metadata).toEqual(testMetadata);
+
+    expect(backToMessageDocs).toHaveLength(1);
+    expect(backToMessageDocs[0].metadata).toEqual(testMetadata);
+  });
+
+  it("handles streaming status correctly", async () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: "Streaming response...",
+        },
+        text: "Streaming response...",
+        streaming: true,
+        status: "pending",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = await fromUIMessages(uiMessages, {
+      threadId: "thread1",
+    });
+
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].status).toBe("streaming");
+
+    expect(backToMessageDocs).toHaveLength(1);
+    expect(backToMessageDocs[0].streaming).toBe(true);
+    expect(backToMessageDocs[0].status).toBe("pending");
+  });
+});
+
+describe("fromUIMessages functionality tests", () => {
+  it("handles empty messages array", async () => {
+    const uiMessages: UIMessage[] = [];
+    const result = await fromUIMessages(uiMessages, { threadId: "thread1" });
+    expect(result).toHaveLength(0);
+  });
+
+  it("correctly assigns thread ID", async () => {
+    const uiMessage: UIMessage = {
+      id: "test-id",
+      _creationTime: Date.now(),
+      order: 0,
+      stepOrder: 0,
+      status: "success",
+      key: "test-key",
+      text: "Hello",
+      role: "user",
+      parts: [{ type: "text", text: "Hello" }],
+    };
+
+    const result = await fromUIMessages([uiMessage], {
+      threadId: "custom-thread-id",
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].threadId).toBe("custom-thread-id");
+  });
+
+  it("correctly determines tool status", async () => {
+    const toolUIMessage: UIMessage = {
+      id: "tool-id",
+      _creationTime: Date.now(),
+      order: 0,
+      stepOrder: 0,
+      status: "success",
+      key: "tool-key",
+      text: "",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-calculator",
+          toolCallId: "call1",
+          input: { a: 1, b: 2 },
+          state: "output-available",
+          output: { result: 3 },
+        },
+      ],
+    };
+
+    const result = await fromUIMessages([toolUIMessage], {
+      threadId: "thread1",
+    });
+    expect(result.length).toBeGreaterThan(0);
+
+    // Should have tool messages
+    const toolMessages = result.filter((msg) => msg.tool);
+    expect(toolMessages.length).toBeGreaterThan(0);
+  });
+
+  it("handles tool calls without responses", async () => {
+    const toolUIMessage: UIMessage = {
+      id: "tool-id",
+      _creationTime: Date.now(),
+      order: 0,
+      stepOrder: 0,
+      status: "success",
+      key: "tool-key",
+      text: "",
+      role: "assistant",
+      parts: [
+        { type: "text", text: "Tool call" },
+        {
+          type: "tool-calculator",
+          toolCallId: "call1",
+          input: { a: 1, b: 2 },
+          state: "input-available",
+        },
+      ],
+    };
+
+    const result = await fromUIMessages([toolUIMessage], {
+      threadId: "thread1",
+    });
+    expect(result.length).toBeGreaterThan(0);
+
+    // Should have tool messages
+    const toolMessages = result.filter((msg) => msg.tool);
+    expect(toolMessages.length).toBe(1);
+    expect(toolMessages[0].message?.role).toBe("assistant");
+    expect(toolMessages[0].message?.content[0]).toMatchObject({
+      type: "text",
+      text: "Tool call",
+    });
+    expect(toolMessages[0].message?.content[1]).toMatchObject({
+      args: { a: 1, b: 2 },
+      toolCallId: "call1",
+      toolName: "calculator",
+      type: "tool-call",
+    });
+  });
+});

package/src/mapping.test.ts

@@ -2,18 +2,21 @@ import { describe, test, expect } from "vitest";
 import {
   guessMimeType,
   serializeDataOrUrl,
-  deserializeUrl,
+  toModelMessageDataOrUrl,
   serializeMessage,
-  deserializeMessage,
+  toModelMessage,
   serializeContent,
+  toModelMessageContent,
 } from "./mapping.js";
 import { api } from "./component/_generated/api.js";
 import type { AgentComponent, ActionCtx } from "./client/types.js";
-import { vMessage } from "./validators.js";
+import { vMessage, vToolResultPart } from "./validators.js";
 import fs from "fs";
 import path from "path";
 import type { SerializedContent } from "./mapping.js";
 import { validate } from "convex-helpers/validators";
+import type { ToolResultPart } from "ai";
+import type { Infer } from "convex/values";
 
 const testAssetsDir = path.join(__dirname, "../test-assets");
 const testFiles = [
@@ -54,8 +57,8 @@ describe("mapping", () => {
     const ser = serializeDataOrUrl(arr);
     expect(ser).toBeInstanceOf(ArrayBuffer);
     expect(new Uint8Array(ser as ArrayBuffer)).toEqual(arr);
-    // deserializeUrl should return the same ArrayBuffer
-    const deser = deserializeUrl(ser);
+    // toModelMessageDataOrUrl should return the same ArrayBuffer
+    const deser = toModelMessageDataOrUrl(ser);
     expect(deser).toBeInstanceOf(ArrayBuffer);
     expect(new Uint8Array(deser as ArrayBuffer)).toEqual(arr);
   });
@@ -80,10 +83,56 @@ describe("mapping", () => {
     const { message: ser } = await serializeMessage(ctx, component, message);
     // Use is for type validation
     expect(validate(vMessage, ser)).toBeTruthy();
-    const round = deserializeMessage(ser);
+    const round = toModelMessage(ser);
     expect(round).toEqual(message);
   });
 
+  test("tool output round-trips", async () => {
+    const toolResult = {
+      type: "tool-result" as const,
+      toolCallId: "tool-call-id",
+      toolName: "tool-name",
+      output: {
+        type: "text",
+        value: "hello world",
+      },
+    } satisfies ToolResultPart;
+    const [result] = toModelMessageContent([toolResult]);
+    expect(result).toMatchObject(toolResult);
+    const {
+      content: [roundtrip],
+    } = await serializeContent({} as ActionCtx, {} as AgentComponent, [
+      result as ToolResultPart,
+    ]);
+    expect(roundtrip).toMatchObject(toolResult);
+  });
+
+  test("tool results get normalized to output", async () => {
+    const toolResult = {
+      type: "tool-result" as const,
+      toolCallId: "tool-call-id",
+      toolName: "tool-name",
+      result: "hello world",
+    } satisfies Infer<typeof vToolResultPart>;
+    const expected = {
+      type: "tool-result",
+      toolCallId: "tool-call-id",
+      toolName: "tool-name",
+      output: {
+        type: "text",
+        value: "hello world",
+      },
+    };
+    const [deserialized] = toModelMessageContent([toolResult]);
+    expect(deserialized).toMatchObject(expected);
+    const {
+      content: [serialized],
+    } = await serializeContent({} as ActionCtx, {} as AgentComponent, [
+      toolResult,
+    ]);
+    expect(serialized).toMatchObject(expected);
+  });
+
   test("saving files returns fileIds when too big", async () => {
     // Make a big file
     const bigArr = new Uint8Array(1024 * 65).fill(1);
@@ -160,4 +209,52 @@ describe("mapping", () => {
     const { fileIds } = await serializeContent(ctx, component, content);
     expect(fileIds).toBeUndefined();
   });
+
+  test("tool-approval-request is preserved after serialization", async () => {
+    const approvalRequest = {
+      type: "tool-approval-request" as const,
+      approvalId: "approval-123",
+      toolCallId: "tool-call-456",
+    };
+    const { content } = await serializeContent(
+      {} as ActionCtx,
+      {} as AgentComponent,
+      [approvalRequest],
+    );
+    expect(content).toHaveLength(1);
+    expect((content as unknown[])[0]).toMatchObject(approvalRequest);
+  });
+
+  test("tool-approval-response with approved: true is preserved", async () => {
+    const approvalResponse = {
+      type: "tool-approval-response" as const,
+      approvalId: "approval-123",
+      approved: true,
+      reason: "User approved",
+    };
+    const { content } = await serializeContent(
+      {} as ActionCtx,
+      {} as AgentComponent,
+      [approvalResponse],
+    );
+    expect(content).toHaveLength(1);
+    expect((content as unknown[])[0]).toMatchObject(approvalResponse);
+  });
+
+  test("tool-approval-response with approved: false is preserved", async () => {
+    const approvalResponse = {
+      type: "tool-approval-response" as const,
+      approvalId: "approval-123",
+      approved: false,
+      reason: "User denied",
+      providerExecuted: false,
+    };
+    const { content } = await serializeContent(
+      {} as ActionCtx,
+      {} as AgentComponent,
+      [approvalResponse],
+    );
+    expect(content).toHaveLength(1);
+    expect((content as unknown[])[0]).toMatchObject(approvalResponse);
+  });
 });