@convex-dev/agent 0.2.8-alpha.6 → 0.2.9

package/src/client/index.ts

@@ -36,7 +36,7 @@ import { convexToJson, v, type Value } from "convex/values";
 import type { threadFieldsSupportingPatch } from "../component/threads.js";
 import { type VectorDimension } from "../component/vector/tables.js";
 import {
-  deserializeMessage,
+  toModelMessage,
   serializeMessage,
   serializeNewMessagesInStep,
   serializeObjectResult,
@@ -67,7 +67,7 @@ import {
   fetchContextMessages,
   generateAndSaveEmbeddings,
 } from "./search.js";
-import { start } from "./start.js";
+import { startGeneration } from "./start.js";
 import {
   compressUIMessageChunks,
   DeltaStreamer,
@@ -104,7 +104,9 @@ import type {
 
 export { stepCountIs } from "ai";
 export {
-  deserializeMessage,
+  toModelMessage,
+  //** @deprecated use toModelMessage instead */
+  toModelMessage as deserializeMessage,
   guessMimeType,
   serializeDataOrUrl,
   serializeMessage,
@@ -159,10 +161,12 @@ export {
   embedMessages,
   embedMany,
 } from "./search.js";
+export { startGeneration } from "./start.js";
 export {
   DEFAULT_STREAMING_OPTIONS,
   DeltaStreamer,
   abortStream,
+  compressUIMessageChunks,
   listStreams,
   syncStreams,
   vStreamMessagesReturnValue,
@@ -173,6 +177,7 @@ export {
   searchThreadTitles,
   updateThreadMetadata,
 } from "./threads.js";
+export type { ContextHandler } from "./types.js";
 export { toUIMessages, fromUIMessages, type UIMessage } from "../UIMessages.js";
 
 export type {
@@ -449,7 +454,7 @@ export class Agent<
     getSavedMessages: () => MessageDoc[];
   }> {
     type Tools = TOOLS extends undefined ? AgentTools : TOOLS;
-    return start<T, Tools, CustomCtx>(
+    return startGeneration<T, Tools, CustomCtx>(
       ctx,
       this.component,
       {
@@ -1496,10 +1501,8 @@ export class Agent<
           stopWhen: spec?.stopWhen,
           ...overrides,
           ...omit(rest, ["storageOptions", "contextOptions", "stream"]),
-          messages: messages?.map(deserializeMessage),
-          prompt: Array.isArray(prompt)
-            ? prompt.map(deserializeMessage)
-            : prompt,
+          messages: messages?.map(toModelMessage),
+          prompt: Array.isArray(prompt) ? prompt.map(toModelMessage) : prompt,
           toolChoice: args.toolChoice as ToolChoice<AgentTools>,
         } satisfies StreamingTextArgs<AgentTools>;
         if (maxSteps) {
@@ -1573,9 +1576,9 @@ export class Agent<
           ...objectArgs,
           ...callSettings,
           ...omit(rest, ["storageOptions", "contextOptions"]),
-          messages: args.messages?.map(deserializeMessage),
+          messages: args.messages?.map(toModelMessage),
           prompt: Array.isArray(args.prompt)
-            ? args.prompt.map(deserializeMessage)
+            ? args.prompt.map(toModelMessage)
             : args.prompt,
         } as GenerateObjectArgs<FlexibleSchema<T>>;
         const ctx = (
@@ -1633,7 +1636,7 @@ export class Agent<
       handler: async (ctx, args) => {
         const { messages } = await this.saveMessages(ctx, {
           ...args,
-          messages: args.messages.map((m) => deserializeMessage(m.message)),
+          messages: args.messages.map((m) => toModelMessage(m.message)),
           metadata: args.messages.map(({ message: _, ...m }) => m),
           skipEmbeddings: true,
         });

package/src/client/search.ts

@@ -28,7 +28,7 @@ import type {
   RunQueryCtx,
 } from "./types.js";
 import { inlineMessagesFiles } from "./files.js";
-import { deserializeMessage } from "../mapping.js";
+import { toModelMessage } from "../mapping.js";
 
 const DEFAULT_VECTOR_SCORE_THRESHOLD = 0.0;
 // 10k characters should be more than enough for most cases, and stays under
@@ -525,20 +525,28 @@ export async function fetchContextWithPrompt(
   const search = searchMessages
     .map((m) => m.message)
     .filter((m) => !!m)
-    .map(deserializeMessage);
+    .map(toModelMessage);
   const recent = prePromptDocs
     .map((m) => m.message)
     .filter((m) => !!m)
-    .map(deserializeMessage);
-  const inputMessages = messages.map(deserializeMessage);
-  const inputPrompt = promptArray.map(deserializeMessage);
+    .map(toModelMessage);
+  const inputMessages = messages.map(toModelMessage);
+  const inputPrompt = promptArray.map(toModelMessage);
   const existingResponses = existingResponseDocs
     .map((m) => m.message)
     .filter((m) => !!m)
-    .map(deserializeMessage);
+    .map(toModelMessage);
 
+    const allMessages = [
+      ...search,
+      ...recent,
+      ...inputMessages,
+      ...inputPrompt,
+      ...existingResponses,
+    ];
   let processedMessages = args.contextHandler
     ? await args.contextHandler(ctx, {
+        allMessages,
         search,
         recent,
         inputMessages,
@@ -547,13 +555,7 @@ export async function fetchContextWithPrompt(
         userId,
         threadId,
       })
-    : [
-        ...search,
-        ...recent,
-        ...inputMessages,
-        ...inputPrompt,
-        ...existingResponses,
-      ];
+    : allMessages;
 
   // Process messages to inline localhost files (if not, file urls pointing to localhost will be sent to LLM providers)
   if (process.env.CONVEX_CLOUD_URL?.startsWith("http://127.0.0.1")) {

package/src/client/start.ts

@@ -32,7 +32,7 @@ import type { Agent } from "./index.js";
 import { omit } from "convex-helpers";
 import { saveInputMessages } from "./saveInputMessages.js";
 
-export async function start<
+export async function startGeneration<
   T,
   Tools extends ToolSet = ToolSet,
   CustomCtx extends object = object,

package/src/client/streaming.ts

@@ -198,7 +198,7 @@ export function mergeTransforms<TOOLS extends ToolSet>(
  * optimize the data in transit.
  */
 export class DeltaStreamer<T> {
-  public streamId: string | undefined;
+  streamId: string | undefined;
   public readonly config: {
     throttleMs: number;
     onAsyncAbort: (reason: string) => Promise<void>;
@@ -255,16 +255,27 @@ export class DeltaStreamer<T> {
     }
   }
 
+  // Avoid race conditions by only creating once
+  #creatingStreamIdPromise: Promise<string> | undefined;
+  public async getStreamId() {
+    if (this.streamId) {
+      return this.streamId;
+    }
+    if (this.#creatingStreamIdPromise) {
+      return this.#creatingStreamIdPromise;
+    }
+    this.#creatingStreamIdPromise = this.ctx.runMutation(
+      this.component.streams.create,
+      this.metadata,
+    );
+    this.streamId = await this.#creatingStreamIdPromise;
+  }
+
   public async addParts(parts: T[]) {
     if (this.abortController.signal.aborted) {
       return;
     }
-    if (!this.streamId) {
-      this.streamId = await this.ctx.runMutation(
-        this.component.streams.create,
-        this.metadata,
-      );
-    }
+    await this.getStreamId();
     this.#nextParts.push(...parts);
     if (
       !this.#ongoingWrite &&

package/src/client/types.ts

@@ -244,6 +244,10 @@ export type UsageHandler = (
 export type ContextHandler = (
   ctx: RunActionCtx,
   args: {
+    /**
+     * All messages in the default order.
+     */
+    allMessages: ModelMessage[];
     /**
      * The messages fetched from search.
      */

package/src/deltas.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest";
 import {
   blankUIMessage,
+  combineUIMessages,
   deriveUIMessagesFromTextStreamParts,
   updateFromTextStreamParts,
   updateFromUIMessageChunks,
@@ -534,3 +535,264 @@ describe("mergeDeltas", () => {
     ]);
   });
 });
+
+describe("combineUIMessages", () => {
+  it("combines messages spanning two pages correctly", () => {
+    const message1 = {
+      id: "msg1",
+      key: "msg1-key",
+      _creationTime: Date.now(),
+      order: 1,
+      stepOrder: 1,
+      status: "success" as const,
+      role: "assistant" as const,
+      text: "",
+      parts: [
+        {
+          type: "dynamic-tool" as const,
+          state: "input-available" as const,
+          toolCallId: "call_123",
+          toolName: "calculator",
+          input: { operation: "add", a: 2, b: 3 },
+        },
+      ],
+    };
+
+    const message2 = {
+      id: "msg2",
+      key: "msg2-key",
+      _creationTime: Date.now() + 1,
+      order: 1,
+      stepOrder: 2,
+      status: "success" as const,
+      role: "assistant" as const,
+      text: "The result is 5.",
+      parts: [
+        {
+          type: "tool-calculator" as const,
+          state: "output-available" as const,
+          toolCallId: "call_123",
+          input: { operation: "add", a: 2, b: 3 },
+          output: { result: 5 },
+        },
+        {
+          type: "text" as const,
+          text: "The result is 5.",
+          state: "done" as const,
+        },
+      ],
+    };
+
+    const combined = combineUIMessages([message1, message2]);
+
+    expect(combined).toHaveLength(1);
+    expect(combined[0].role).toBe("assistant");
+    expect(combined[0].text).toBe("The result is 5.");
+    expect(combined[0].parts).toHaveLength(2);
+
+    const toolPart = combined[0].parts.find(p => p.type === "tool-calculator");
+    expect(toolPart).toMatchObject({
+      type: "tool-calculator",
+      state: "output-available",
+      toolCallId: "call_123",
+      input: { operation: "add", a: 2, b: 3 },
+      output: { result: 5 },
+    });
+
+    const textPart = combined[0].parts.find(p => p.type === "text");
+    expect(textPart).toMatchObject({
+      type: "text",
+      text: "The result is 5.",
+      state: "done",
+    });
+  });
+
+  it("preserves separate messages with different roles", () => {
+    const userMessage = {
+      id: "user1",
+      key: "user1-key",
+      _creationTime: Date.now(),
+      order: 1,
+      stepOrder: 0,
+      status: "success" as const,
+      role: "user" as const,
+      text: "Calculate 2 + 3",
+      parts: [{ type: "text" as const, text: "Calculate 2 + 3" }],
+    };
+
+    const assistantMessage = {
+      id: "assistant1",
+      key: "assistant1-key",
+      _creationTime: Date.now() + 1,
+      order: 2,
+      stepOrder: 0,
+      status: "success" as const,
+      role: "assistant" as const,
+      text: "The result is 5.",
+      parts: [{ type: "text" as const, text: "The result is 5.", state: "done" as const }],
+    };
+
+    const combined = combineUIMessages([userMessage, assistantMessage]);
+
+    expect(combined).toHaveLength(2);
+    expect(combined[0]).toEqual(userMessage);
+    expect(combined[1]).toEqual(assistantMessage);
+  });
+
+  it("combines multiple tool calls across pages", () => {
+    const message1 = {
+      id: "msg1",
+      key: "msg1-key",
+      _creationTime: Date.now(),
+      order: 1,
+      stepOrder: 1,
+      status: "success" as const,
+      role: "assistant" as const,
+      text: "",
+      parts: [
+        {
+          type: "dynamic-tool" as const,
+          state: "input-available" as const,
+          toolCallId: "call_1",
+          toolName: "calculator",
+          input: { operation: "add", a: 2, b: 3 },
+        },
+        {
+          type: "dynamic-tool" as const,
+          state: "input-available" as const,
+          toolCallId: "call_2",
+          toolName: "formatter",
+          input: { text: "result" },
+        },
+      ],
+    };
+
+    const message2 = {
+      id: "msg2",
+      key: "msg2-key",
+      _creationTime: Date.now() + 1,
+      order: 1,
+      stepOrder: 2,
+      status: "success" as const,
+      role: "assistant" as const,
+      text: "The formatted result is: 5",
+      parts: [
+        {
+          type: "tool-calculator" as const,
+          state: "output-available" as const,
+          toolCallId: "call_1",
+          input: { operation: "add", a: 2, b: 3 },
+          output: { result: 5 },
+        },
+        {
+          type: "tool-formatter" as const,
+          state: "output-available" as const,
+          toolCallId: "call_2",
+          input: { text: "result" },
+          output: { formatted: "The formatted result is: 5" },
+        },
+        {
+          type: "text" as const,
+          text: "The formatted result is: 5",
+          state: "done" as const,
+        },
+      ],
+    };
+
+    const combined = combineUIMessages([message1, message2]);
+
+    expect(combined).toHaveLength(1);
+    expect(combined[0].role).toBe("assistant");
+    expect(combined[0].text).toBe("The formatted result is: 5");
+    expect(combined[0].parts).toHaveLength(3);
+
+    const calculatorPart = combined[0].parts.find(p =>
+      p.type === "tool-calculator" && "toolCallId" in p && p.toolCallId === "call_1"
+    );
+    expect(calculatorPart).toMatchObject({
+      type: "tool-calculator",
+      state: "output-available",
+      toolCallId: "call_1",
+      input: { operation: "add", a: 2, b: 3 },
+      output: { result: 5 },
+    });
+
+    const formatterPart = combined[0].parts.find(p =>
+      p.type === "tool-formatter" && "toolCallId" in p && p.toolCallId === "call_2"
+    );
+    expect(formatterPart).toMatchObject({
+      type: "tool-formatter",
+      state: "output-available",
+      toolCallId: "call_2",
+      input: { text: "result" },
+      output: { formatted: "The formatted result is: 5" },
+    });
+  });
+
+  it("handles tool call without corresponding output", () => {
+    const message1 = {
+      id: "msg1",
+      key: "msg1-key",
+      _creationTime: Date.now(),
+      order: 1,
+      stepOrder: 1,
+      status: "success" as const,
+      role: "assistant" as const,
+      text: "",
+      parts: [
+        {
+          type: "dynamic-tool" as const,
+          state: "input-available" as const,
+          toolCallId: "call_orphan",
+          toolName: "calculator",
+          input: { operation: "add", a: 2, b: 3 },
+        },
+      ],
+    };
+
+    const message2 = {
+      id: "msg2",
+      key: "msg2-key",
+      _creationTime: Date.now() + 1,
+      order: 1,
+      stepOrder: 2,
+      status: "success" as const,
+      role: "assistant" as const,
+      text: "Still processing...",
+      parts: [
+        {
+          type: "text" as const,
+          text: "Still processing...",
+          state: "done" as const,
+        },
+      ],
+    };
+
+    const combined = combineUIMessages([message1, message2]);
+
+    expect(combined).toHaveLength(1);
+    expect(combined[0].role).toBe("assistant");
+    expect(combined[0].text).toBe("Still processing...");
+    expect(combined[0].parts).toHaveLength(2);
+
+    const toolPart = combined[0].parts.find(p =>
+      p.type === "dynamic-tool"
+    );
+    expect(toolPart).toMatchObject({
+      type: "dynamic-tool",
+      state: "input-available",
+      toolCallId: "call_orphan",
+      toolName: "calculator",
+      input: { operation: "add", a: 2, b: 3 },
+    });
+
+    const textPart = combined[0].parts.find(p =>
+      p.type === "text"
+    );
+    expect(textPart).toMatchObject({
+      type: "text",
+      text: "Still processing...",
+      state: "done",
+    });
+  });
+});

package/src/mapping.test.ts

@@ -2,11 +2,11 @@ import { describe, test, expect } from "vitest";
 import {
   guessMimeType,
   serializeDataOrUrl,
-  deserializeUrl,
+  toModelMessageDataOrUrl,
   serializeMessage,
-  deserializeMessage,
+  toModelMessage,
   serializeContent,
-  deserializeContent,
+  toModelMessageContent,
 } from "./mapping.js";
 import { api } from "./component/_generated/api.js";
 import type { AgentComponent, ActionCtx } from "./client/types.js";
@@ -57,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);
   });
@@ -83,7 +83,7 @@ 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);
   });
 
@@ -97,7 +97,7 @@ describe("mapping", () => {
         value: "hello world",
       },
     } satisfies ToolResultPart;
-    const [result] = deserializeContent([toolResult]);
+    const [result] = toModelMessageContent([toolResult]);
     expect(result).toMatchObject(toolResult);
     const {
       content: [roundtrip],
@@ -123,7 +123,7 @@ describe("mapping", () => {
         value: "hello world",
       },
     };
-    const [deserialized] = deserializeContent([toolResult]);
+    const [deserialized] = toModelMessageContent([toolResult]);
     expect(deserialized).toMatchObject(expected);
     const {
       content: [serialized],

package/src/mapping.ts

@@ -125,12 +125,12 @@ export async function serializeOrThrow(
   } as SerializedMessage;
 }
 
-export function deserializeMessage(
+export function toModelMessage(
   message: SerializedMessage | ModelMessage,
 ): ModelMessage {
   return {
     ...message,
-    content: deserializeContent(message.content),
+    content: toModelMessageContent(message.content),
   } as ModelMessage;
 }
 
@@ -144,7 +144,7 @@ export function serializeUsage(usage: LanguageModelUsage): Usage {
   };
 }
 
-export function deserializeUsage(usage: Usage): LanguageModelUsage {
+export function toModelMessageUsage(usage: Usage): LanguageModelUsage {
   return {
     inputTokens: usage.promptTokens,
     outputTokens: usage.completionTokens,
@@ -168,7 +168,7 @@ export function serializeWarnings(
   });
 }
 
-export function deserializeWarnings(
+export function toModelMessageWarnings(
   warnings: MessageWithMetadata["warnings"],
 ): CallWarning[] | undefined {
   // We don't need to do anythign here for now
@@ -262,18 +262,18 @@ export async function serializeContent(
     return { content };
   }
   const fileIds: string[] = [];
-  const metadata: {
-    providerOptions?: ProviderOptions;
-    providerMetadata?: ProviderMetadata;
-  } = {};
-  if ("providerOptions" in content) {
-    metadata.providerOptions = content.providerOptions as ProviderOptions;
-  }
-  if ("providerMetadata" in content) {
-    metadata.providerMetadata = content.providerMetadata as ProviderMetadata;
-  }
   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 {
@@ -371,17 +371,17 @@ export function fromModelMessageContent(content: Content): Message["content"] {
   if (typeof content === "string") {
     return content;
   }
-  const metadata: {
-    providerOptions?: ProviderOptions;
-    providerMetadata?: ProviderMetadata;
-  } = {};
-  if ("providerOptions" in content) {
-    metadata.providerOptions = content.providerOptions as ProviderOptions;
-  }
-  if ("providerMetadata" in content) {
-    metadata.providerMetadata = content.providerMetadata as ProviderMetadata;
-  }
   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>;
@@ -424,7 +424,7 @@ export function fromModelMessageContent(content: Content): Message["content"] {
   }) as Message["content"];
 }
 
-export function deserializeContent(
+export function toModelMessageContent(
   content: SerializedContent | ModelMessage["content"],
 ): Content {
   if (typeof content === "string") {
@@ -451,14 +451,14 @@ export function deserializeContent(
       case "image":
         return {
           type: part.type,
-          image: deserializeUrl(part.image),
+          image: toModelMessageDataOrUrl(part.image),
           mediaType: getMimeOrMediaType(part),
           ...metadata,
         } satisfies ImagePart;
       case "file":
         return {
           type: part.type,
-          data: deserializeUrl(part.data),
+          data: toModelMessageDataOrUrl(part.data),
           filename: part.filename,
           mediaType: getMimeOrMediaType(part)!,
           ...metadata,
@@ -636,7 +636,7 @@ export function serializeDataOrUrl(
   ) as ArrayBuffer;
 }
 
-export function deserializeUrl(
+export function toModelMessageDataOrUrl(
   urlOrString: string | ArrayBuffer | URL | DataContent,
 ): URL | DataContent {
   if (urlOrString instanceof URL) {

package/src/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +1 @@
-{"version":"3.2.4","results":[[":client/index.test.ts",{"duration":129.9694999999997,"failed":false}],[":component/messages.test.ts",{"duration":191.73391600000014,"failed":false}],[":component/users.test.ts",{"duration":545.7272500000001,"failed":false}],[":mapping.test.ts",{"duration":9.238791999999876,"failed":false}],[":react/deltas.test.ts",{"duration":5.8497500000000855,"failed":false}],[":react/toUIMessages.test.ts",{"duration":6.495208000000048,"failed":false}],[":validators.test.ts",{"duration":1.0037499999999682,"failed":false}],[":deltas.test.ts",{"duration":0,"failed":false}],[":client/streaming.test.ts",{"duration":177.87866699695587,"failed":false}]]}
+{"version":"3.2.4","results":[[":client/index.test.ts",{"duration":129.9694999999997,"failed":false}],[":component/messages.test.ts",{"duration":191.73391600000014,"failed":false}],[":component/users.test.ts",{"duration":545.7272500000001,"failed":false}],[":mapping.test.ts",{"duration":28.127082999999402,"failed":false}],[":react/deltas.test.ts",{"duration":5.8497500000000855,"failed":false}],[":react/toUIMessages.test.ts",{"duration":6.495208000000048,"failed":false}],[":validators.test.ts",{"duration":1.0037499999999682,"failed":false}],[":deltas.test.ts",{"duration":0,"failed":false}],[":client/streaming.test.ts",{"duration":177.87866699695587,"failed":false}]]}