@convex-dev/agent 0.1.15-alpha.0 → 0.1.15-alpha.2

package/src/client/listMessages.ts

@@ -0,0 +1,38 @@
+import type { PaginationOptions, PaginationResult } from "convex/server";
+import type { AgentComponent, RunQueryCtx } from "./types.js";
+import type { MessageStatus } from "../validators.js";
+import type { MessageDoc } from "../component/schema.js";
+
+/**
+ * List messages from a thread.
+ * @param ctx A ctx object from a query, mutation, or action.
+ * @param component The agent component, usually `components.agent`.
+ * @param args.threadId The thread to list messages from.
+ * @param args.paginationOpts Pagination options (e.g. via usePaginatedQuery).
+ * @param args.excludeToolMessages Whether to exclude tool messages.
+ *   False by default.
+ * @param args.statuses What statuses to include. All by default.
+ * @returns The MessageDoc's in a format compatible with usePaginatedQuery.
+ */
+export async function listMessages(
+  ctx: RunQueryCtx,
+  component: AgentComponent,
+  args: {
+    threadId: string;
+    paginationOpts: PaginationOptions;
+    excludeToolMessages?: boolean;
+    statuses?: MessageStatus[];
+  }
+): Promise<PaginationResult<MessageDoc>> {
+  if (args.paginationOpts.numItems === 0) {
+    return {
+      page: [],
+      isDone: true,
+      continueCursor: args.paginationOpts.cursor ?? "",
+    };
+  }
+  return ctx.runQuery(component.messages.listMessagesByThreadId, {
+    order: "desc",
+    ...args,
+  });
+}

package/src/client/search.ts

@@ -0,0 +1,172 @@
+import type {
+  AgentComponent,
+  ContextOptions,
+  RunActionCtx,
+  RunQueryCtx,
+} from "./types.js";
+import type { MessageDoc } from "../component/schema.js";
+import type { CoreMessage } from "ai";
+import { assert } from "convex-helpers";
+import {
+  DEFAULT_MESSAGE_RANGE,
+  DEFAULT_RECENT_MESSAGES,
+  extractText,
+} from "../shared.js";
+
+const DEFAULT_VECTOR_SCORE_THRESHOLD = 0.0;
+
+export type GetEmbedding = (text: string) => Promise<{
+  vector: number[];
+  vectorModel: string;
+  vectorScoreThreshold?: number;
+}>;
+
+/**
+ * Fetch the context messages for a thread.
+ * @param ctx Either a query, mutation, or action ctx.
+ *   If it is not an action context, you can't do text or
+ *   vector search.
+ * @param args The associated thread, user, message
+ * @returns
+ */
+export async function fetchContextMessages(
+  ctx: RunQueryCtx | RunActionCtx,
+  component: AgentComponent,
+  args: {
+    userId: string | undefined;
+    threadId: string | undefined;
+    messages: CoreMessage[];
+    /**
+     * If provided, it will search for messages up to and including this message.
+     * Note: if this is far in the past, text and vector search results may be more
+     * limited, as it's post-filtering the results.
+     */
+    upToAndIncludingMessageId?: string;
+    contextOptions: ContextOptions;
+    getEmbedding?: GetEmbedding;
+  }
+): Promise<MessageDoc[]> {
+  assert(args.userId || args.threadId, "Specify userId or threadId");
+  const opts = args.contextOptions;
+  // Fetch the latest messages from the thread
+  let included: Set<string> | undefined;
+  const contextMessages: MessageDoc[] = [];
+  if (
+    args.threadId &&
+    (opts.recentMessages !== 0 || args.upToAndIncludingMessageId)
+  ) {
+    const { page } = await ctx.runQuery(
+      component.messages.listMessagesByThreadId,
+      {
+        threadId: args.threadId,
+        excludeToolMessages: opts.excludeToolMessages,
+        paginationOpts: {
+          numItems: opts.recentMessages ?? DEFAULT_RECENT_MESSAGES,
+          cursor: null,
+        },
+        upToAndIncludingMessageId: args.upToAndIncludingMessageId,
+        order: "desc",
+        statuses: ["success"],
+      }
+    );
+    included = new Set(page.map((m) => m._id));
+    contextMessages.push(
+      // Reverse since we fetched in descending order
+      ...page.reverse()
+    );
+  }
+  if (opts.searchOptions?.textSearch || opts.searchOptions?.vectorSearch) {
+    const targetMessage = contextMessages.find(
+      (m) => m._id === args.upToAndIncludingMessageId
+    )?.message;
+    const messagesToSearch = targetMessage ? [targetMessage] : args.messages;
+    if (!("runAction" in ctx)) {
+      throw new Error("searchUserMessages only works in an action");
+    }
+    const lastMessage = messagesToSearch.at(-1)!;
+    assert(lastMessage, "No messages to search");
+    const text = extractText(lastMessage);
+    assert(text, `No text to search in message ${JSON.stringify(lastMessage)}`);
+    assert(
+      !args.contextOptions?.searchOptions?.vectorSearch || "runAction" in ctx,
+      "You must do vector search from an action"
+    );
+    if (opts.searchOptions?.vectorSearch && !args.getEmbedding) {
+      throw new Error(
+        "You must provide an embedding and embeddingModel to use vector search"
+      );
+    }
+    const embeddingFields = opts.searchOptions?.vectorSearch
+      ? await args.getEmbedding?.(text)
+      : undefined;
+    const searchMessages = await ctx.runAction(
+      component.messages.searchMessages,
+      {
+        searchAllMessagesForUserId: opts?.searchOtherThreads
+          ? args.userId ??
+            (args.threadId &&
+              (
+                await ctx.runQuery(component.threads.getThread, {
+                  threadId: args.threadId,
+                })
+              )?.userId)
+          : undefined,
+        threadId: args.threadId,
+        beforeMessageId: args.upToAndIncludingMessageId,
+        limit: opts.searchOptions?.limit ?? 10,
+        messageRange: {
+          ...DEFAULT_MESSAGE_RANGE,
+          ...opts.searchOptions?.messageRange,
+        },
+        text,
+        vectorScoreThreshold:
+          opts.searchOptions?.vectorScoreThreshold ??
+          DEFAULT_VECTOR_SCORE_THRESHOLD,
+        ...embeddingFields,
+      }
+    );
+    // TODO: track what messages we used for context
+    contextMessages.unshift(
+      ...searchMessages.filter((m) => !included?.has(m._id))
+    );
+  }
+  // Ensure we don't include tool messages without a corresponding tool call
+  return filterOutOrphanedToolMessages(
+    contextMessages.sort((a, b) =>
+      // Sort the raw MessageDocs by order and stepOrder
+      a.order === b.order ? a.stepOrder - b.stepOrder : a.order - b.order
+    )
+  );
+}
+
+/**
+ * Filter out tool messages that don't have both a tool call and response.
+ * @param docs The messages to filter.
+ * @returns The filtered messages.
+ */
+export function filterOutOrphanedToolMessages(docs: MessageDoc[]) {
+  const toolCallIds = new Set<string>();
+  const result: MessageDoc[] = [];
+  for (const doc of docs) {
+    if (
+      doc.message?.role === "assistant" &&
+      Array.isArray(doc.message.content)
+    ) {
+      for (const content of doc.message.content) {
+        if (content.type === "tool-call") {
+          toolCallIds.add(content.toolCallId);
+        }
+      }
+      result.push(doc);
+    } else if (doc.message?.role === "tool") {
+      if (doc.message.content.every((c) => toolCallIds.has(c.toolCallId))) {
+        result.push(doc);
+      } else {
+        console.debug("Filtering out orphaned tool message", doc);
+      }
+    } else {
+      result.push(doc);
+    }
+  }
+  return result;
+}

package/src/client/streaming.ts

@@ -6,11 +6,58 @@ import {
 } from "ai";
 import type {
   ProviderOptions,
+  StreamArgs,
   StreamDelta,
   TextStreamPart,
 } from "../validators.js";
-import type { AgentComponent, MessageDoc } from "./index.js";
-import type { RunActionCtx } from "./types.js";
+import type { MessageDoc } from "../component/schema.js";
+import type {
+  AgentComponent,
+  RunActionCtx,
+  RunQueryCtx,
+  SyncStreamsReturnValue,
+} from "./types.js";
+
+/**
+ * A function that handles fetching stream deltas, used with the React hooks
+ * `useThreadMessages` or `useStreamingThreadMessages`.
+ * @param ctx A ctx object from a query, mutation, or action.
+ * @param component The agent component, usually `components.agent`.
+ * @param args.threadId The thread to sync streams for.
+ * @param args.streamArgs The stream arguments with per-stream cursors.
+ * @returns The deltas for each stream from their existing cursor.
+ */
+export async function syncStreams(
+  ctx: RunQueryCtx,
+  component: AgentComponent,
+  args: {
+    threadId: string;
+    streamArgs: StreamArgs | undefined;
+    // By default, only streaming messages are included.
+    includeStatuses?: ("streaming" | "finished" | "aborted")[];
+  }
+): Promise<SyncStreamsReturnValue | undefined> {
+  if (!args.streamArgs) return undefined;
+  if (args.streamArgs.kind === "list") {
+    return {
+      kind: "list",
+      messages: await ctx.runQuery(component.streams.list, {
+        threadId: args.threadId,
+        startOrder: args.streamArgs.startOrder,
+        statuses: args.includeStatuses,
+      }),
+    };
+  } else {
+    return {
+      kind: "deltas",
+      deltas: await ctx.runQuery(component.streams.listDeltas, {
+        threadId: args.threadId,
+        cursors: args.streamArgs.cursors,
+      }),
+    };
+  }
+}
+
 
 export type StreamingOptions = {
   /**

package/src/client/types.ts

@@ -77,6 +77,10 @@ export type ContextOptions = {
      * At least one of textSearch or vectorSearch must be true.
      */
     vectorSearch?: boolean;
+    /**
+     * The score threshold for vector search. Default is 0.0.
+     */
+    vectorScoreThreshold?: number;
     /**
      * What messages around the search results to include.
      * Default: { before: 2, after: 1 }
@@ -144,7 +148,7 @@ export type UsageHandler = (
 ) => void | Promise<void>;
 
 export type RawRequestResponseHandler = (
-  ctx: RunActionCtx,
+  ctx: ActionCtx,
   args: {
     userId: string | undefined;
     threadId: string | undefined;

package/src/component/_generated/api.d.ts

@@ -900,13 +900,13 @@ export type Mounts = {
       "public",
       {
         beforeMessageId?: string;
+        embedding?: Array<number>;
+        embeddingModel?: string;
         limit: number;
         messageRange?: { after: number; before: number };
         searchAllMessagesForUserId?: string;
         text?: string;
         threadId?: string;
-        vector?: Array<number>;
-        vectorModel?: string;
         vectorScoreThreshold?: number;
       },
       Array<{

package/src/component/messages.ts

@@ -13,7 +13,6 @@ import {
   vMessageStatus,
   vMessageWithMetadataInternal,
   vPaginationResult,
-  vSearchOptions,
 } from "../validators.js";
 import { api, internal } from "./_generated/api.js";
 import type { Doc, Id } from "./_generated/dataModel.js";
@@ -467,7 +466,14 @@ export const searchMessages = action({
     threadId: v.optional(v.id("threads")),
     searchAllMessagesForUserId: v.optional(v.string()),
     beforeMessageId: v.optional(v.id("messages")),
-    ...vSearchOptions.fields,
+    embedding: v.optional(v.array(v.number())),
+    embeddingModel: v.optional(v.string()),
+    text: v.optional(v.string()),
+    limit: v.number(),
+    vectorScoreThreshold: v.optional(v.number()),
+    messageRange: v.optional(
+      v.object({ before: v.number(), after: v.number() })
+    ),
   },
   returns: v.array(vMessageDoc),
   handler: async (ctx, args): Promise<MessageDoc[]> => {
@@ -486,15 +492,15 @@ export const searchMessages = action({
         beforeMessageId: args.beforeMessageId,
       });
     }
-    if (args.vector) {
-      const dimension = args.vector.length as VectorDimension;
+    if (args.embedding) {
+      const dimension = args.embedding.length as VectorDimension;
       if (!VectorDimensions.includes(dimension)) {
-        throw new Error(`Unsupported vector dimension: ${dimension}`);
+        throw new Error(`Unsupported embedding dimension: ${dimension}`);
       }
       const vectors = (
-        await searchVectors(ctx, args.vector, {
+        await searchVectors(ctx, args.embedding, {
           dimension,
-          model: args.vectorModel ?? "unknown",
+          model: args.embeddingModel ?? "unknown",
           table: "messages",
           searchAllMessagesForUserId: args.searchAllMessagesForUserId,
           threadId: args.threadId,

package/src/component/vector/index.ts

@@ -182,10 +182,10 @@ export const updateBatch = mutation({
   returns: v.null(),
   handler: async (ctx, args) => {
     await Promise.all(
-      args.vectors.map((v) =>
-        ctx.db.patch(v.id, {
-          model: v.model,
-          vector: v.vector,
+      args.vectors.map((embedding) =>
+        ctx.db.patch(embedding.id, {
+          model: embedding.model,
+          vector: embedding.vector,
         })
       )
     );

package/src/react/optimisticallySendMessage.ts

@@ -28,7 +28,7 @@ export function optimisticallySendMessage(
       argsToMatch: { threadId: args.threadId, streamArgs: undefined },
       item: {
         _creationTime: Date.now(),
-        _id: crypto.randomUUID(),
+        _id: randomUUID(),
         order,
         stepOrder,
         status: "pending",
@@ -44,3 +44,13 @@ export function optimisticallySendMessage(
     });
   };
 }
+
+export function randomUUID() {
+  if (typeof crypto !== "undefined") {
+    return crypto.randomUUID();
+  }
+  return (
+    Math.random().toString(36).substring(2, 15) +
+    Math.random().toString(36).substring(2, 15)
+  );
+}

package/src/react/toUIMessages.ts

@@ -9,6 +9,7 @@ export type UIMessage = AIUIMessage & {
   order: number;
   stepOrder: number;
   status: "streaming" | MessageStatus;
+  agentName?: string;
 };
 
 export function toUIMessages(
@@ -36,6 +37,7 @@ export function toUIMessages(
         ...common,
         role: "system",
         content: text,
+        agentName: message.agentName,
         parts: [{ type: "text", text }],
       });
     } else if (coreMessage.role === "user") {
@@ -69,6 +71,7 @@ export function toUIMessages(
         assistantMessage = {
           ...common,
           role: "assistant",
+          agentName: message.agentName,
           content: "",
           parts: [],
         };

package/src/validators.ts

@@ -277,7 +277,7 @@ export const vMessageEmbeddings = v.object({
   dimension: vVectorDimension,
   vectors: v.array(v.union(v.array(v.number()), v.null())),
 });
-
+export type MessageEmbeddings = Infer<typeof vMessageEmbeddings>;
 
 export const vObjectResult = v.object({
   request: vRequest,
@@ -290,20 +290,12 @@ export const vObjectResult = v.object({
   providerMetadata,
 });
 export type ObjectResult = Infer<typeof vObjectResult>;
-export const vSearchOptions = v.object({
-  vector: v.optional(v.array(v.number())),
-  vectorModel: v.optional(v.string()),
-  text: v.optional(v.string()),
-  limit: v.number(),
-  vectorScoreThreshold: v.optional(v.number()),
-  messageRange: v.optional(v.object({ before: v.number(), after: v.number() })),
-});
-export type SearchOptions = Infer<typeof vSearchOptions>;
 
 export const vContextOptionsSearchOptions = v.object({
   limit: v.number(),
   textSearch: v.optional(v.boolean()),
   vectorSearch: v.optional(v.boolean()),
+  vectorScoreThreshold: v.optional(v.number()),
   messageRange: v.optional(v.object({ before: v.number(), after: v.number() })),
 });