@convex-dev/agent 0.2.8 → 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/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}]]}

package/src/client/mock.json

@@ -1,68 +0,0 @@
-[
-  { "type": "start" },
-  { "type": "start-step" },
-  { "type": "reasoning-start", "id": "0-reasoning" },
-  {
-    "type": "reasoning-delta",
-    "id": "0-reasoning",
-    "delta": "I'm",
-    "providerMetadata": {
-      "mockProvider": { "mock": { "reasoningDetails": null } }
-    }
-  },
-  {
-    "type": "reasoning-delta",
-    "id": "0-reasoning",
-    "delta": " thinking",
-    "providerMetadata": {
-      "mockProvider": { "mock": { "reasoningDetails": null } }
-    }
-  },
-  { "type": "reasoning-end", "id": "0-reasoning" },
-  {
-    "type": "tool-input-available",
-    "toolCallId": "1",
-    "toolName": "say",
-    "input": { "question": "What is the best flavor of ice cream?" }
-  },
-  {
-    "type": "tool-output-available",
-    "toolCallId": "1",
-    "output": "I'm sorry I can't help you. Stop asking me questions."
-  },
-  {
-    "type": "tool-output-available",
-    "toolCallId": "1",
-    "output": "I'm sorry I can't help you. Stop asking me questions."
-  },
-  { "type": "reasoning-start", "id": "3-reasoning" },
-  {
-    "type": "reasoning-delta",
-    "id": "3-reasoning",
-    "delta": "I'm",
-    "providerMetadata": {
-      "mockProvider": { "mock": { "reasoningDetails": null } }
-    }
-  },
-  {
-    "type": "reasoning-delta",
-    "id": "3-reasoning",
-    "delta": " thinking",
-    "providerMetadata": {
-      "mockProvider": { "mock": { "reasoningDetails": null } }
-    }
-  },
-  { "type": "reasoning-end", "id": "3-reasoning" },
-  { "type": "text-start", "id": "4-text" },
-  { "type": "text-delta", "id": "4-text", "delta": "The" },
-  { "type": "text-delta", "id": "4-text", "delta": " best" },
-  { "type": "text-delta", "id": "4-text", "delta": " flavor" },
-  { "type": "text-delta", "id": "4-text", "delta": " of" },
-  { "type": "text-delta", "id": "4-text", "delta": " ice" },
-  { "type": "text-delta", "id": "4-text", "delta": " cream" },
-  { "type": "text-delta", "id": "4-text", "delta": " is" },
-  { "type": "text-delta", "id": "4-text", "delta": " vanilla." },
-  { "type": "text-end", "id": "4-text" },
-  { "type": "finish-step" },
-  { "type": "finish" }
-]

package/src/client/stream.json

@@ -1,48 +0,0 @@
-[
-  { "type": "start" },
-  { "type": "start-step" },
-  { "type": "reasoning-start", "id": "reasoning-0" },
-  { "type": "reasoning-delta", "id": "reasoning-0", "delta": "Okay" },
-  {
-    "type": "reasoning-delta",
-    "id": "reasoning-0",
-    "delta": ", the user is asking, \"What is the best flavor of ice cream?\" I need to figure out how to respond. Let me check the tools provided. The only tool available is the \"say\" function, which allows me to ask a friend for their favorite ice cream flavor. The function requires a \"question\" parameter.\n\nSo, since I don't have any other functions, I can't look up information or calculate the answer. The best approach is to use the \"say\" function to ask a friend. I should formulate the question to match the friend's parameters. The user is asking for the \"best\" flavor, which is subjective. Therefore, asking a friend's favorite makes sense.\n\nI need to structure the function call correctly. The function name is \"say\" and the argument is the question. The question should be, \"What is your favorite flavor of ice cream?\" That's the parameter required. Let me make sure the JSON is properly formatted with the arguments as a JSON object. Yep, that should work. I'll output the tool_call with the function name and the question argument.\n"
-  },
-  { "type": "tool-input-start", "toolCallId": "0ychh9k6f", "toolName": "say" },
-  {
-    "type": "tool-input-delta",
-    "toolCallId": "0ychh9k6f",
-    "inputTextDelta": "{\"question\":\"What is your favorite flavor of ice cream?\"}"
-  },
-  {
-    "type": "tool-input-available",
-    "toolCallId": "0ychh9k6f",
-    "toolName": "say",
-    "input": { "question": "What is your favorite flavor of ice cream?" }
-  },
-  {
-    "type": "tool-output-available",
-    "toolCallId": "0ychh9k6f",
-    "output": "I'm sorry I can't help you. Stop asking me questions."
-  },
-  { "type": "reasoning-end", "id": "reasoning-0" },
-  { "type": "finish-step" },
-  { "type": "start-step" },
-  { "type": "reasoning-start", "id": "reasoning-0" },
-  { "type": "reasoning-delta", "id": "reasoning-0", "delta": "Okay" },
-  {
-    "type": "reasoning-delta",
-    "id": "reasoning-0",
-    "delta": ", the user initially asked for the best ice cream flavor. I tried using the 'say' function to ask a friend, but the friend didn't help. Now I need to respond. Since I can't get an answer from the friend, I should tell the user that I can't determine the best flavor because it's subjective. Maybe suggest they try different ones. Keep the response friendly and helpful.\n"
-  },
-  { "type": "text-start", "id": "txt-0" },
-  {
-    "type": "text-delta",
-    "id": "txt-0",
-    "delta": "The \"best\" ice cream flavor is subjective—it depends on personal taste! Some people love classic vanilla, while others might prefer adventurous options like matcha or salted caramel. Why not try a few and see which one you like most? 🍦"
-  },
-  { "type": "reasoning-end", "id": "reasoning-0" },
-  { "type": "text-end", "id": "txt-0" },
-  { "type": "finish-step" },
-  { "type": "finish" }
-]