@convex-dev/agent 0.6.3 → 0.7.0-alpha.0

package/src/vercel/client/messages.ts

@@ -0,0 +1,182 @@
+import type { ModelMessage } from "ai";
+import type { PaginationOptions, PaginationResult } from "convex/server";
+import type { MessageDoc } from "../../validators.js";
+import {
+  type Message,
+  type MessageEmbeddings,
+  type MessageWithMetadata,
+} from "../../validators.js";
+import { serializeMessage } from "../mapping.js";
+import { toUIMessages, type UIMessage } from "../UIMessages.js";
+import {
+  listMessages,
+  saveMessages as saveCanonicalMessages,
+} from "../../client/messages.js";
+import type {
+  AgentComponent,
+  MutationCtx,
+  QueryCtx,
+  ActionCtx,
+} from "./types.js";
+
+export { listMessages } from "../../client/messages.js";
+
+export async function listUIMessages(
+  ctx: QueryCtx | MutationCtx | ActionCtx,
+  component: AgentComponent,
+  args: {
+    threadId: string;
+    paginationOpts: PaginationOptions;
+  },
+): Promise<PaginationResult<UIMessage>> {
+  const result = await listMessages(ctx, component, args);
+  return { ...result, page: toUIMessages(result.page) };
+}
+
+export type SaveMessagesArgs = {
+  threadId: string;
+  userId?: string | null;
+  /**
+   * The message that these messages are in response to. They will be
+   * the same "order" as this message, at increasing stepOrder(s).
+   */
+  promptMessageId?: string;
+  /**
+   * The messages to save.
+   */
+  messages: (ModelMessage | Message)[];
+  /**
+   * Metadata to save with the messages. Each element corresponds to the
+   * message at the same index.
+   */
+  metadata?: Omit<MessageWithMetadata, "message">[];
+  /**
+   * If true, it will fail any pending steps.
+   * Defaults to false.
+   */
+  failPendingSteps?: boolean;
+  /**
+   * The embeddings to save with the messages.
+   */
+  embeddings?: MessageEmbeddings;
+  /**
+   * A pending message ID to replace when adding messages.
+   */
+  pendingMessageId?: string;
+};
+
+/**
+ * Explicitly save messages associated with the thread (& user if provided)
+ */
+export async function saveMessages(
+  ctx: MutationCtx | ActionCtx,
+  component: AgentComponent,
+  args: SaveMessagesArgs & {
+    /**
+     * The agent name to associate with the messages.
+     */
+    agentName?: string;
+  },
+): Promise<{ messages: MessageDoc[] }> {
+  const serialized = await Promise.all(
+    args.messages.map((message) => serializeMessage(ctx, component, message)),
+  );
+  return saveCanonicalMessages(ctx, component, {
+    threadId: args.threadId,
+    userId: args.userId ?? undefined,
+    agentName: args.agentName,
+    promptMessageId: args.promptMessageId,
+    pendingMessageId: args.pendingMessageId,
+    embeddings: args.embeddings,
+    messages: serialized.map(({ message }) => message),
+    metadata: serialized.map(({ fileIds }, i) => {
+      const base = args.metadata?.[i];
+      const allFileIds = [...(base?.fileIds ?? [])];
+      if (fileIds) allFileIds.push(...fileIds);
+      return {
+        ...base,
+        ...(allFileIds.length > 0 ? { fileIds: allFileIds } : {}),
+      };
+    }),
+    failPendingSteps: args.failPendingSteps ?? false,
+  });
+}
+
+export type SaveMessageArgs = {
+  threadId: string;
+  userId?: string | null;
+  /**
+   * The message that these messages are in response to. They will be
+   * the same "order" as this message, at increasing stepOrder(s).
+   */
+  promptMessageId?: string;
+  /**
+   * Metadata to save with the messages. Each element corresponds to the
+   * message at the same index.
+   */
+  metadata?: Omit<MessageWithMetadata, "message">;
+  /**
+   * The embedding to save with the message.
+   */
+  embedding?: { vector: number[]; model: string };
+  /**
+   * A pending message ID to replace with this message.
+   */
+  pendingMessageId?: string;
+} & (
+  | {
+      prompt?: undefined;
+      /**
+       * The message to save.
+       */
+      message: ModelMessage | Message;
+    }
+  | {
+      /*
+       * The prompt to save with the message.
+       */
+      prompt: string;
+      message?: undefined;
+    }
+);
+
+/**
+ * Save a message to the thread.
+ * @param ctx A ctx object from a mutation or action.
+ * @param args The message and what to associate it with (user / thread)
+ * You can pass extra metadata alongside the message, e.g. associated fileIds.
+ * @returns The messageId of the saved message.
+ */
+export async function saveMessage(
+  ctx: MutationCtx | ActionCtx,
+  component: AgentComponent,
+  args: SaveMessageArgs & {
+    /**
+     * The agent name to associate with the message.
+     */
+    agentName?: string;
+  },
+) {
+  let embeddings: { vectors: number[][]; model: string } | undefined;
+  if (args.embedding && args.embedding.vector) {
+    embeddings = {
+      model: args.embedding.model,
+      vectors: [args.embedding.vector],
+    };
+  }
+  const { messages } = await saveMessages(ctx, component, {
+    threadId: args.threadId,
+    userId: args.userId ?? undefined,
+    agentName: args.agentName,
+    promptMessageId: args.promptMessageId,
+    pendingMessageId: args.pendingMessageId,
+    messages:
+      args.prompt !== undefined
+        ? [{ role: "user", content: args.prompt }]
+        : [args.message],
+    metadata: args.metadata ? [args.metadata] : undefined,
+    embeddings,
+  });
+  const message = messages.at(-1)!;
+  return { messageId: message._id, message };
+}

package/src/{client → vercel/client}/mockModel.ts

@@ -1,7 +1,7 @@
 import type {
-  LanguageModelV3,
-  LanguageModelV3Content,
-  LanguageModelV3StreamPart,
+  LanguageModelV4,
+  LanguageModelV4Content,
+  LanguageModelV4StreamPart,
 } from "@ai-sdk/provider";
 import { simulateReadableStream, type ProviderMetadata } from "ai";
 import { assert, pick } from "convex-helpers";
@@ -13,26 +13,25 @@ C C C C C C C C C C C C C C C
 D D D D D D D D D D D D D D D
 `;
 const DEFAULT_USAGE = {
-  outputTokens: 10,
-  inputTokens: 3,
-  totalTokens: 13,
-  inputTokenDetails: {
-    noCacheTokens: 3,
-    cacheReadTokens: 0,
-    cacheWriteTokens: 0,
+  inputTokens: {
+    total: 3,
+    noCache: 3,
+    cacheRead: 0,
+    cacheWrite: 0,
   },
-  outputTokenDetails: {
-    textTokens: 10,
-    reasoningTokens: 0,
+  outputTokens: {
+    total: 10,
+    text: 10,
+    reasoning: 0,
   },
 };
 
 export type MockModelArgs = {
-  provider?: LanguageModelV3["provider"];
-  modelId?: LanguageModelV3["modelId"];
+  provider?: LanguageModelV4["provider"];
+  modelId?: LanguageModelV4["modelId"];
   supportedUrls?:
-    | LanguageModelV3["supportedUrls"]
-    | (() => LanguageModelV3["supportedUrls"]);
+    | LanguageModelV4["supportedUrls"]
+    | (() => LanguageModelV4["supportedUrls"]);
   chunkDelayInMs?: number;
   initialDelayInMs?: number;
   /** A list of the responses for multiple steps.
@@ -40,15 +39,15 @@ export type MockModelArgs = {
    * then the next list would be after the tool response or another tool call.
    * Tool responses come from actual tool calls!
    */
-  contentSteps?: LanguageModelV3Content[][];
+  contentSteps?: LanguageModelV4Content[][];
   /** A single list of content responded from each step.
    * Provide contentSteps instead if you want to do multi-step responses with
    * tool calls.
    */
-  content?: LanguageModelV3Content[];
+  content?: LanguageModelV4Content[];
   // provide either content, contentResponses or doGenerate & doStream
-  doGenerate?: LanguageModelV3["doGenerate"];
-  doStream?: LanguageModelV3["doStream"];
+  doGenerate?: LanguageModelV4["doGenerate"];
+  doStream?: LanguageModelV4["doStream"];
   providerMetadata?: ProviderMetadata;
   fail?:
     | boolean
@@ -62,23 +61,23 @@ function atMostOneOf(...args: unknown[]) {
   return args.filter(Boolean).length <= 1;
 }
 
-export function mockModel(args?: MockModelArgs): LanguageModelV3 {
+export function mockModel(args?: MockModelArgs): LanguageModelV4 {
   return new MockLanguageModel(args ?? {});
 }
 
-export class MockLanguageModel implements LanguageModelV3 {
-  readonly specificationVersion = "v3";
+export class MockLanguageModel implements LanguageModelV4 {
+  readonly specificationVersion = "v4";
 
-  private _supportedUrls: () => LanguageModelV3["supportedUrls"];
+  private _supportedUrls: () => LanguageModelV4["supportedUrls"];
 
-  readonly provider: LanguageModelV3["provider"];
-  readonly modelId: LanguageModelV3["modelId"];
+  readonly provider: LanguageModelV4["provider"];
+  readonly modelId: LanguageModelV4["modelId"];
 
-  doGenerate: LanguageModelV3["doGenerate"];
-  doStream: LanguageModelV3["doStream"];
+  doGenerate: LanguageModelV4["doGenerate"];
+  doStream: LanguageModelV4["doStream"];
 
-  doGenerateCalls: Parameters<LanguageModelV3["doGenerate"]>[0][] = [];
-  doStreamCalls: Parameters<LanguageModelV3["doStream"]>[0][] = [];
+  doGenerateCalls: Parameters<LanguageModelV4["doGenerate"]>[0][] = [];
+  doStreamCalls: Parameters<LanguageModelV4["doStream"]>[0][] = [];
 
   constructor(args: MockModelArgs) {
     assert(
@@ -108,19 +107,19 @@ export class MockLanguageModel implements LanguageModelV3 {
       "Mock error message";
     const metadata = pick(args, ["providerMetadata"]);
 
-    const chunkResponses: LanguageModelV3StreamPart[][] = contentSteps.map(
+    const chunkResponses: LanguageModelV4StreamPart[][] = contentSteps.map(
       (content) => {
-        const chunks: LanguageModelV3StreamPart[] = [
+        const chunks: LanguageModelV4StreamPart[] = [
           { type: "stream-start", warnings: [] },
         ];
         chunks.push(
-          ...content.flatMap((c, ci): LanguageModelV3StreamPart[] => {
+          ...content.flatMap((c, ci): LanguageModelV4StreamPart[] => {
             if (c.type !== "text" && c.type !== "reasoning") {
               return [c];
             }
             const metadata = pick(c, ["providerMetadata"]);
             const deltas = c.text.split(" ");
-            const parts: LanguageModelV3StreamPart[] = [];
+            const parts: LanguageModelV4StreamPart[] = [];
             if (c.type === "reasoning") {
               parts.push({
                 type: "reasoning-start",
@@ -135,7 +134,7 @@ export class MockLanguageModel implements LanguageModelV3 {
                       delta: (di ? " " : "") + delta,
                       id: `reasoning-${ci}`,
                       ...metadata,
-                    }) satisfies LanguageModelV3StreamPart,
+                    }) satisfies LanguageModelV4StreamPart,
                 ),
               );
               parts.push({
@@ -157,7 +156,7 @@ export class MockLanguageModel implements LanguageModelV3 {
                       delta: (di ? " " : "") + delta,
                       id: `txt-${ci}`,
                       ...metadata,
-                    }) satisfies LanguageModelV3StreamPart,
+                    }) satisfies LanguageModelV4StreamPart,
                 ),
               );
               parts.push({
@@ -177,7 +176,7 @@ export class MockLanguageModel implements LanguageModelV3 {
         }
         chunks.push({
           type: "finish",
-          finishReason: fail ? "error" : "stop",
+          finishReason: { unified: fail ? "error" : "stop", raw: undefined },
           usage: DEFAULT_USAGE,
           ...(metadata as any),
         });
@@ -198,7 +197,7 @@ export class MockLanguageModel implements LanguageModelV3 {
       } else if (contentSteps.length) {
         const result = {
           content: contentSteps[callIndex % contentSteps.length],
-          finishReason: "stop" as const,
+          finishReason: { unified: "stop" as const, raw: undefined },
           usage: DEFAULT_USAGE,
           ...(metadata as any),
           warnings: [],

package/src/{client → vercel/client}/saveInputMessages.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { saveInputMessages } from "./saveInputMessages.js";
-import type { MessageDoc } from "../validators.js";
+import type { MessageDoc } from "../../validators.js";
 import type { ActionCtx } from "./types.js";
 import {
   defineSchema,

package/src/{client → vercel/client}/saveInputMessages.ts

@@ -1,5 +1,5 @@
 import { type ModelMessage } from "ai";
-import type { MessageDoc } from "../validators.js";
+import type { MessageDoc } from "../../validators.js";
 import { embedMessages, getPromptArray } from "./search.js";
 import type {
   ActionCtx,
@@ -8,9 +8,9 @@ import type {
   MutationCtx,
 } from "./types.js";
 import { saveMessages } from "./messages.js";
-import type { Message } from "../validators.js";
+import type { Message } from "../../validators.js";
 import { assert } from "convex-helpers";
-import type { VectorDimension } from "../component/vector/tables.js";
+import type { VectorDimension } from "../../component/vector/tables.js";
 
 export async function saveInputMessages(
   ctx: MutationCtx | ActionCtx,
@@ -31,7 +31,10 @@ export async function saveInputMessages(
     storageOptions?: {
       saveMessages?: "all" | "promptAndOutput";
     };
-  } & Pick<Config, "usageHandler" | "textEmbeddingModel" | "embeddingModel" | "callSettings">,
+  } & Pick<
+    Config,
+    "usageHandler" | "textEmbeddingModel" | "embeddingModel" | "callSettings"
+  >,
 ): Promise<{
   promptMessageId: string | undefined;
   pendingMessage: MessageDoc;

package/src/{client → vercel/client}/search.test.ts

@@ -13,7 +13,7 @@ import {
   type StorageActionWriter,
   type StorageReader,
 } from "convex/server";
-import type { MessageDoc } from "../validators.js";
+import type { MessageDoc } from "../../validators.js";
 import type { ActionCtx, QueryCtx } from "./types.js";
 import {
   fetchContextWithPrompt,
@@ -22,8 +22,8 @@ import {
   getPromptArray,
 } from "./search.js";
 import { components, initConvexTest } from "./setup.test.js";
-import { createThread } from "./threads.js";
-import { saveMessages } from "./messages.js";
+import { createThread } from "../../client/threads.js";
+import { saveMessages } from "../../client/messages.js";
 
 // Helper to create mock MessageDoc
 const createMockMessageDoc = (

package/src/{client → vercel/client}/search.ts

@@ -4,11 +4,11 @@ import {
   type ModelMessage,
 } from "ai";
 import { assert } from "convex-helpers";
-import type { MessageDoc } from "../validators.js";
+import type { MessageDoc } from "../../validators.js";
 import {
   validateVectorDimension,
   type VectorDimension,
-} from "../component/vector/tables.js";
+} from "../../component/vector/tables.js";
 import {
   DEFAULT_MESSAGE_RANGE,
   DEFAULT_RECENT_MESSAGES,
@@ -17,8 +17,8 @@ import {
   getProviderName,
   isTool,
   sorted,
-} from "../shared.js";
-import type { Message } from "../validators.js";
+} from "../../shared.js";
+import type { Message } from "../../validators.js";
 import type {
   AgentComponent,
   Config,

package/src/{client → vercel/client}/setup.test.ts

@@ -1,16 +1,19 @@
 /// <reference types="vite/client" />
 import { test } from "vitest";
 import { convexTest } from "convex-test";
-export const modules = import.meta.glob("./**/*.*s");
+export const modules = {
+  ...import.meta.glob("./**/*.*s"),
+  "./_generated/api.ts": () => import("../../component/_generated/api.js"),
+};
 
 import {
   defineSchema,
   type GenericSchema,
   type SchemaDefinition,
 } from "convex/server";
-import { type AgentComponent } from "./index.js";
+import { type AgentComponent } from "./types.js";
 import { componentsGeneric } from "convex/server";
-import component from "../test.js";
+import component from "../../test.js";
 
 export function initConvexTest<
   Schema extends SchemaDefinition<GenericSchema, boolean>,

package/src/vercel/client/start.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { resolveUsageModel } from "./start.js";
+
+describe("resolveUsageModel", () => {
+  it("prefers a step model while object results retain the active model", () => {
+    const activeModel = { provider: "fallback", model: "fallback-model" };
+    const stepModel = { provider: "router", model: "routed-model" };
+
+    expect(resolveUsageModel({ step: { model: stepModel } }, activeModel)).toBe(
+      stepModel,
+    );
+    expect(resolveUsageModel({ object: {} }, activeModel)).toBe(activeModel);
+  });
+});