@convex-dev/agent 0.2.6-alpha.0 → 0.2.6

package/src/react/fromUIMessages.test.ts

@@ -0,0 +1,427 @@
+import { describe, it, expect } from "vitest";
+import { toUIMessages } from "./toUIMessages.js";
+import { fromUIMessages } from "./fromUIMessages.js";
+import type { MessageDoc } from "../client/index.js";
+import type { UIMessage } from "./toUIMessages.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", () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "user",
+          content: "Hello world!",
+        },
+        text: "Hello world!",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = fromUIMessages("thread1", uiMessages);
+
+    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", () => {
+    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 = fromUIMessages("thread1", uiMessages);
+
+    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", () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "system",
+          content: "You are a helpful assistant.",
+        },
+        text: "You are a helpful assistant.",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = fromUIMessages("thread1", uiMessages);
+
+    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", () => {
+    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 = fromUIMessages("thread1", uiMessages);
+
+    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", () => {
+    // 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",
+              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 uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = fromUIMessages("thread1", uiMessages);
+
+    // Should be grouped into single UI message
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("assistant");
+
+    // Check tool parts exist
+    const toolParts = uiMessages[0].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", () => {
+    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 = fromUIMessages("thread1", uiMessages);
+
+    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",
+        mimeType: "image/png",
+      });
+    }
+  });
+
+  it("preserves sources correctly", () => {
+    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 = fromUIMessages("thread1", uiMessages);
+
+    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", () => {
+    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 = fromUIMessages("thread1", uiMessages);
+
+    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", () => {
+    const originalMessages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: "Streaming response...",
+        },
+        text: "Streaming response...",
+        streaming: true,
+        status: "pending",
+      }),
+    ];
+
+    const uiMessages = toUIMessages(originalMessages);
+    const backToMessageDocs = fromUIMessages("thread1", uiMessages);
+
+    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", () => {
+    const uiMessages: UIMessage[] = [];
+    const result = fromUIMessages("thread1", uiMessages);
+    expect(result).toHaveLength(0);
+  });
+
+  it("correctly assigns thread ID", () => {
+    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 = fromUIMessages("custom-thread-id", [uiMessage]);
+    expect(result).toHaveLength(1);
+    expect(result[0].threadId).toBe("custom-thread-id");
+  });
+
+  it("correctly determines tool status", () => {
+    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 = fromUIMessages("thread1", [toolUIMessage]);
+    expect(result.length).toBeGreaterThan(0);
+
+    // Should have tool messages
+    const toolMessages = result.filter((msg) => msg.tool);
+    expect(toolMessages.length).toBeGreaterThan(0);
+  });
+});

package/src/react/fromUIMessages.ts

@@ -0,0 +1,85 @@
+import { convertToModelMessages } from "ai";
+import { extractReasoning, extractText, isTool } from "../shared.js";
+import type { MessageDoc, vSource } from "../validators.js";
+import type { UIMessage } from "./toUIMessages.js";
+import type { ProviderOptions } from "@ai-sdk/provider-utils";
+import { omit } from "convex-helpers";
+import { fromModelMessage } from "../mapping.js";
+import type { Infer } from "convex/values";
+
+export function fromUIMessages<METADATA = unknown>(
+  threadId: string,
+  messages: (UIMessage<METADATA> & {
+    userId?: string;
+    model?: string;
+    provider?: string;
+    providerOptions?: ProviderOptions;
+  })[],
+): (MessageDoc & { streaming: boolean; metadata?: METADATA })[] {
+  return messages.flatMap((uiMessage) => {
+    const stepOrder = uiMessage.stepOrder;
+    const commonFields = {
+      _id: uiMessage.id,
+      ...omit(uiMessage, ["parts", "role", "key", "text"]),
+      threadId,
+      status: uiMessage.status === "streaming" ? "pending" : "success",
+      streaming: uiMessage.status === "streaming",
+      // to override
+      tool: false,
+    } satisfies MessageDoc & { streaming: boolean; metadata?: METADATA };
+    const modelMessages = convertToModelMessages([uiMessage]);
+    return modelMessages.map((modelMessage, i) => {
+      const message = fromModelMessage(modelMessage);
+      const tool = isTool(message);
+      const doc: MessageDoc & { streaming: boolean; metadata?: METADATA } = {
+        ...commonFields,
+        stepOrder: stepOrder + i,
+        message,
+        tool,
+        text: extractText(message),
+        reasoning: extractReasoning(message),
+        finishReason: tool ? "tool-calls" : "stop",
+        sources: fromSourceParts(uiMessage.parts),
+      };
+      if (Array.isArray(modelMessage.content)) {
+        const providerOptions = modelMessage.content.find(
+          (c) => c.providerOptions,
+        )?.providerOptions;
+        if (providerOptions) {
+          // convertToModelMessages changes providerMetadata to providerOptions
+          doc.providerMetadata = providerOptions;
+          doc.providerOptions ??= providerOptions;
+        }
+      }
+      return doc;
+    });
+  });
+}
+
+function fromSourceParts(parts: UIMessage["parts"]): Infer<typeof vSource>[] {
+  return parts
+    .map((part) => {
+      if (part.type === "source-url") {
+        return {
+          type: "source",
+          sourceType: "url",
+          url: part.url,
+          id: part.sourceId,
+          providerMetadata: part.providerMetadata,
+          title: part.title,
+        } satisfies Infer<typeof vSource>;
+      }
+      if (part.type === "source-document") {
+        return {
+          type: "source",
+          sourceType: "document",
+          mediaType: part.mediaType,
+          id: part.sourceId,
+          providerMetadata: part.providerMetadata,
+          title: part.title,
+        } satisfies Infer<typeof vSource>;
+      }
+      return undefined;
+    })
+    .filter((p) => p !== undefined);
+}

package/src/react/toUIMessages.ts

@@ -30,12 +30,17 @@ export type UIMessage<
   _creationTime: number;
 };
 
+type ExtraFields<METADATA = unknown> = {
+  streaming?: boolean;
+  metadata?: METADATA;
+};
+
 export function toUIMessages<
   METADATA = unknown,
   DATA_PARTS extends UIDataTypes = UIDataTypes,
   TOOLS extends UITools = UITools,
 >(
-  messages: (MessageDoc & { streaming?: boolean })[],
+  messages: (MessageDoc & ExtraFields<METADATA>)[],
 ): UIMessage<METADATA, DATA_PARTS, TOOLS>[] {
   // Group assistant and tool messages together
   const assistantGroups = groupAssistantMessages(messages);
@@ -55,29 +60,29 @@ export function toUIMessages<
   return uiMessages;
 }
 
-type Group =
+type Group<METADATA = unknown> =
   | {
       role: "user";
-      message: MessageDoc & { streaming?: boolean };
+      message: MessageDoc & ExtraFields<METADATA>;
     }
   | {
       role: "system";
-      message: MessageDoc & { streaming?: boolean };
+      message: MessageDoc & ExtraFields<METADATA>;
     }
   | {
       role: "assistant";
-      messages: (MessageDoc & { streaming?: boolean })[];
+      messages: (MessageDoc & ExtraFields<METADATA>)[];
     };
 
-function groupAssistantMessages(
-  messages: (MessageDoc & { streaming?: boolean })[],
-): Group[] {
-  const groups: Group[] = [];
+function groupAssistantMessages<METADATA = unknown>(
+  messages: (MessageDoc & ExtraFields<METADATA>)[],
+): Group<METADATA>[] {
+  const groups: Group<METADATA>[] = [];
 
   // Sort messages by order and stepOrder first to handle out-of-order arrivals
   const sortedMessages = sorted(messages);
 
-  let currentAssistantGroup: (MessageDoc & { streaming?: boolean })[] = [];
+  let currentAssistantGroup: (MessageDoc & ExtraFields<METADATA>)[] = [];
   let currentOrder: number | undefined;
 
   for (const message of sortedMessages) {
@@ -145,7 +150,7 @@ function createSystemUIMessage<
   DATA_PARTS extends UIDataTypes = UIDataTypes,
   TOOLS extends UITools = UITools,
 >(
-  message: MessageDoc & { streaming?: boolean },
+  message: MessageDoc & ExtraFields<METADATA>,
 ): UIMessage<METADATA, DATA_PARTS, TOOLS> {
   const text = extractTextFromMessageDoc(message);
   const partCommon = {
@@ -166,6 +171,7 @@ function createSystemUIMessage<
     role: "system",
     agentName: message.agentName,
     parts: [{ type: "text", text, ...partCommon } satisfies TextUIPart],
+    metadata: message.metadata,
   };
 }
 
@@ -180,7 +186,7 @@ function createUserUIMessage<
   DATA_PARTS extends UIDataTypes = UIDataTypes,
   TOOLS extends UITools = UITools,
 >(
-  message: MessageDoc & { streaming?: boolean },
+  message: MessageDoc & ExtraFields<METADATA>,
 ): UIMessage<METADATA, DATA_PARTS, TOOLS> {
   const text = extractTextFromMessageDoc(message);
   const coreMessage = deserializeMessage(message.message!);
@@ -224,6 +230,7 @@ function createUserUIMessage<
     text,
     role: "user",
     parts,
+    metadata: message.metadata,
   };
 }
 
@@ -232,7 +239,7 @@ function createAssistantUIMessage<
   DATA_PARTS extends UIDataTypes = UIDataTypes,
   TOOLS extends UITools = UITools,
 >(
-  groupUnordered: (MessageDoc & { streaming?: boolean })[],
+  groupUnordered: (MessageDoc & ExtraFields<METADATA>)[],
 ): UIMessage<METADATA, DATA_PARTS, TOOLS> {
   const group = sorted(groupUnordered);
   const firstMessage = group[0];
@@ -415,6 +422,7 @@ function createAssistantUIMessage<
     text: allText,
     status,
     parts: allParts,
+    metadata: group.find((m) => m.metadata)?.metadata,
   };
 }
 

package/src/shared.ts

@@ -37,6 +37,16 @@ export function extractText(message: Message | ModelMessage) {
   return undefined;
 }
 
+export function extractReasoning(message: Message | ModelMessage) {
+  if (typeof message.content === "string") {
+    return undefined;
+  }
+  return message.content
+    .filter((c) => c.type === "reasoning")
+    .map((c) => c.text)
+    .join("");
+}
+
 export const DEFAULT_MESSAGE_RANGE = { before: 2, after: 1 };
 
 export function sorted<T extends { order: number; stepOrder: number }>(
@@ -49,3 +59,26 @@ export function sorted<T extends { order: number; stepOrder: number }>(
       : (a, b) => b.order - a.order || b.stepOrder - a.stepOrder,
   );
 }
+
+export type ModelOrMetadata =
+  | string
+  | ({ provider: string } & ({ modelId: string } | { model: string }));
+
+export function getModelName(embeddingModel: ModelOrMetadata): string {
+  if (typeof embeddingModel === "string") {
+    if (embeddingModel.includes("/")) {
+      return embeddingModel.split("/").slice(1).join("/");
+    }
+    return embeddingModel;
+  }
+  return "modelId" in embeddingModel
+    ? embeddingModel.modelId
+    : embeddingModel.model;
+}
+
+export function getProviderName(embeddingModel: ModelOrMetadata): string {
+  if (typeof embeddingModel === "string") {
+    return embeddingModel.split("/").at(0)!;
+  }
+  return embeddingModel.provider;
+}

package/src/validators.test.ts

@@ -1,7 +1,12 @@
 import type { Infer } from "convex/values";
 import { expectTypeOf, test } from "vitest";
-import type { ContextOptions, StorageOptions } from "./client/types.js";
-import { vContextOptions, vStorageOptions } from "./validators.js";
+import type {
+  ContextOptions,
+  OpaqueIds,
+  StorageOptions,
+} from "./client/types.js";
+import { vContextOptions, vMessageDoc, vStorageOptions } from "./validators.js";
+import type { Doc } from "./component/_generated/dataModel.js";
 
 expectTypeOf<Infer<typeof vContextOptions>>().toExtend<ContextOptions>();
 expectTypeOf<ContextOptions>().toExtend<Infer<typeof vContextOptions>>();
@@ -9,4 +14,10 @@ expectTypeOf<ContextOptions>().toExtend<Infer<typeof vContextOptions>>();
 expectTypeOf<Infer<typeof vStorageOptions>>().toExtend<StorageOptions>();
 expectTypeOf<StorageOptions>().toExtend<Infer<typeof vStorageOptions>>();
 
+type MessageBasedOnSchema = OpaqueIds<
+  Omit<Doc<"messages">, "files" | "stepId" | "parentMessageId">
+>;
+expectTypeOf<Infer<typeof vMessageDoc>>().toEqualTypeOf<MessageBasedOnSchema>();
+expectTypeOf<MessageBasedOnSchema>().toEqualTypeOf<Infer<typeof vMessageDoc>>();
+
 test("noop", () => {});