@convex-dev/agent 0.2.12 → 0.3.1

package/src/component/_generated/{server.d.ts → server.ts}

@@ -8,9 +8,8 @@
  * @module
  */
 
-import {
+import type {
   ActionBuilder,
-  AnyComponents,
   HttpActionBuilder,
   MutationBuilder,
   QueryBuilder,
@@ -19,15 +18,18 @@ import {
   GenericQueryCtx,
   GenericDatabaseReader,
   GenericDatabaseWriter,
-  FunctionReference,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
 } from "convex/server";
 import type { DataModel } from "./dataModel.js";
 
-type GenericCtx =
-  | GenericActionCtx<DataModel>
-  | GenericMutationCtx<DataModel>
-  | GenericQueryCtx<DataModel>;
-
 /**
  * Define a query in this Convex app's public API.
  *
@@ -36,7 +38,7 @@ type GenericCtx =
  * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
  * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
  */
-export declare const query: QueryBuilder<DataModel, "public">;
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
 
 /**
  * Define a query that is only accessible from other Convex functions (but not from the client).
@@ -46,7 +48,8 @@ export declare const query: QueryBuilder<DataModel, "public">;
  * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
  * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
  */
-export declare const internalQuery: QueryBuilder<DataModel, "internal">;
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
 
 /**
  * Define a mutation in this Convex app's public API.
@@ -56,7 +59,7 @@ export declare const internalQuery: QueryBuilder<DataModel, "internal">;
  * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
  * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
  */
-export declare const mutation: MutationBuilder<DataModel, "public">;
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
 
 /**
  * Define a mutation that is only accessible from other Convex functions (but not from the client).
@@ -66,7 +69,8 @@ export declare const mutation: MutationBuilder<DataModel, "public">;
  * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
  * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
  */
-export declare const internalMutation: MutationBuilder<DataModel, "internal">;
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
 
 /**
  * Define an action in this Convex app's public API.
@@ -79,7 +83,7 @@ export declare const internalMutation: MutationBuilder<DataModel, "internal">;
  * @param func - The action. It receives an {@link ActionCtx} as its first argument.
  * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
  */
-export declare const action: ActionBuilder<DataModel, "public">;
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
 
 /**
  * Define an action that is only accessible from other Convex functions (but not from the client).
@@ -87,19 +91,26 @@ export declare const action: ActionBuilder<DataModel, "public">;
  * @param func - The function. It receives an {@link ActionCtx} as its first argument.
  * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
  */
-export declare const internalAction: ActionBuilder<DataModel, "internal">;
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
 
 /**
  * Define an HTTP action.
  *
- * This function will be used to respond to HTTP requests received by a Convex
- * deployment if the requests matches the path and method where this action
- * is routed. Be sure to route your action in `convex/http.js`.
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
  *
- * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
  * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
  */
-export declare const httpAction: HttpActionBuilder;
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
 
 /**
  * A set of services for use within Convex query functions.
@@ -107,8 +118,7 @@ export declare const httpAction: HttpActionBuilder;
  * The query context is passed as the first argument to any Convex query
  * function run on the server.
  *
- * This differs from the {@link MutationCtx} because all of the services are
- * read-only.
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
  */
 export type QueryCtx = GenericQueryCtx<DataModel>;
 
@@ -117,6 +127,8 @@ export type QueryCtx = GenericQueryCtx<DataModel>;
  *
  * The mutation context is passed as the first argument to any Convex mutation
  * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
  */
 export type MutationCtx = GenericMutationCtx<DataModel>;
 

package/src/component/messages.ts

@@ -24,6 +24,7 @@ import { api, internal } from "./_generated/api.js";
 import type { Doc, Id } from "./_generated/dataModel.js";
 import {
   action,
+  internalMutation,
   internalQuery,
   mutation,
   type MutationCtx,
@@ -137,6 +138,9 @@ const addMessagesArgs = {
   failPendingSteps: v.optional(v.boolean()),
   // A pending message to update. If the pending message failed, abort.
   pendingMessageId: v.optional(v.id("messages")),
+  // if set to true, these messages will not show up in text or vector search
+  // results for the userId
+  hideFromUserIdSearch: v.optional(v.boolean()),
 };
 export const addMessages = mutation({
   args: addMessagesArgs,
@@ -160,6 +164,7 @@ async function addMessagesHandler(
     messages,
     promptMessageId,
     pendingMessageId,
+    hideFromUserIdSearch,
     ...rest
   } = args;
   const promptMessage = promptMessageId && (await ctx.db.get(promptMessageId));
@@ -226,7 +231,7 @@ async function addMessagesHandler(
         vector: embeddings.vectors[i]!,
         model: embeddings.model,
         table: "messages",
-        userId,
+        userId: hideFromUserIdSearch ? undefined : userId,
         threadId,
       });
     }
@@ -237,7 +242,7 @@ async function addMessagesHandler(
       parentMessageId: promptMessageId,
       userId,
       tool: isTool(message.message),
-      text: extractText(message.message),
+      text: hideFromUserIdSearch ? undefined : extractText(message.message),
       status: fail ? "failed" : (message.status ?? "success"),
       error: fail ? error : message.error,
     } satisfies Omit<
@@ -439,64 +444,216 @@ export const updateMessage = mutation({
   },
 });
 
-export const listMessagesByThreadId = query({
+const cloneMessageArgs = {
+  sourceThreadId: v.id("threads"),
+  targetThreadId: v.id("threads"),
+  // defaults to false, so searching for a message by userId will not find
+  // these copies
+  copyUserIdForVectorSearch: v.optional(v.boolean()),
+  // defaults to false, so tool calls & responses will be copied
+  excludeToolMessages: v.optional(v.boolean()),
+  // defaults to copying all messages, but you could just copy success messages.
+  statuses: v.optional(v.array(vMessageStatus)),
+  // stop at this message id
+  upToAndIncludingMessageId: v.optional(v.id("messages")),
+  // defaults to 0. the messages will be inserted starting at this order.
+  insertAtOrder: v.optional(v.number()),
+};
+export const cloneMessageBatch = internalMutation({
   args: {
-    threadId: v.id("threads"),
-    excludeToolMessages: v.optional(v.boolean()),
-    /** What order to sort the messages in. To get the latest, use "desc". */
-    order: v.union(v.literal("asc"), v.literal("desc")),
-    paginationOpts: v.optional(paginationOptsValidator),
-    statuses: v.optional(v.array(vMessageStatus)),
-    upToAndIncludingMessageId: v.optional(v.id("messages")),
+    ...cloneMessageArgs,
+    paginationOpts: paginationOptsValidator,
   },
-  handler: async (ctx, args) => {
-    const statuses =
-      args.statuses ?? vMessageStatus.members.map((m) => m.value);
-    const last =
-      args.upToAndIncludingMessageId &&
-      (await ctx.db.get(args.upToAndIncludingMessageId));
-    assert(
-      !last || last.threadId === args.threadId,
-      "upToAndIncludingMessageId must be a message in the thread",
-    );
-    const toolOptions = args.excludeToolMessages ? [false] : [true, false];
-    const order = args.order ?? "desc";
-    const streams = toolOptions.flatMap((tool) =>
-      statuses.map((status) =>
-        stream(ctx.db, schema)
-          .query("messages")
-          .withIndex("threadId_status_tool_order_stepOrder", (q) => {
-            const qq = q
-              .eq("threadId", args.threadId)
-              .eq("status", status)
-              .eq("tool", tool);
-            if (last) {
-              return qq.lte("order", last.order);
-            }
-            return qq;
-          })
-          .order(order)
-          .filterWith(
-            // We allow all messages on the same order.
-            async (m) =>
-              !last || m.order < last.order || m.order === last.order,
-          ),
-      ),
-    );
-    const messages = await mergedStream(streams, [
-      "order",
-      "stepOrder",
-    ]).paginate(
-      args.paginationOpts ?? {
-        numItems: DEFAULT_RECENT_MESSAGES,
-        cursor: null,
-      },
+  handler: async (
+    ctx,
+    args,
+  ): Promise<{
+    numCopied: number;
+    continueCursor: string;
+    isDone: boolean;
+  }> => {
+    const orderOffset = args.insertAtOrder ?? 0;
+    const result = await listMessagesByThreadIdHandler(ctx, {
+      threadId: args.sourceThreadId,
+      excludeToolMessages: args.excludeToolMessages,
+      order: "desc",
+      paginationOpts: args.paginationOpts,
+      statuses: args.statuses,
+      upToAndIncludingMessageId: args.upToAndIncludingMessageId,
+    });
+
+    const existing =
+      result.page.length === 0
+        ? []
+        : await mergedStream(
+            [true, false].flatMap((tool) =>
+              messageStatuses.map((status) =>
+                stream(ctx.db, schema)
+                  .query("messages")
+                  .withIndex("threadId_status_tool_order_stepOrder", (q) =>
+                    q
+                      .eq("threadId", args.targetThreadId)
+                      .eq("status", status)
+                      .eq("tool", tool)
+                      .gte("order", result.page[0].order)
+                      .lte("order", result.page[result.page.length - 1].order),
+                  ),
+              ),
+            ),
+            ["order", "stepOrder"],
+          ).collect();
+
+    await Promise.all(
+      result.page
+        .filter(
+          (m) =>
+            !existing.some(
+              (e) => e.order === m.order && e.stepOrder === m.stepOrder,
+            ),
+        )
+        .map(async (m) => {
+          // update file refs
+          if (m.fileIds) {
+            await changeRefcount(ctx, [], m.fileIds);
+          }
+          let embeddingId: VectorTableId | undefined = undefined;
+          if (m.embeddingId) {
+            const vector = await ctx.db.get(m.embeddingId);
+            assert(vector, `Vector ${m.embeddingId} not found`);
+            const dimension = vector.vector.length;
+            validateVectorDimension(dimension);
+            embeddingId = await insertVector(ctx, dimension, {
+              ...pick(vector, ["model", "table", "vector"]),
+              userId: args.copyUserIdForVectorSearch
+                ? vector.userId
+                : undefined,
+              threadId: args.targetThreadId,
+            });
+          }
+          await ctx.db.insert("messages", {
+            ...omit(m, [
+              "_id",
+              "_creationTime",
+              "threadId",
+              "order",
+              "embeddingId",
+            ]),
+            embeddingId,
+            threadId: args.targetThreadId,
+            order: orderOffset + m.order,
+          });
+        }),
     );
+    return {
+      numCopied: result.page.length,
+      continueCursor: result.continueCursor,
+      isDone: result.isDone,
+    };
+  },
+});
+
+export const cloneThread = action({
+  args: {
+    ...cloneMessageArgs,
+    batchSize: v.optional(v.number()),
+    // how many messages to copy
+    limit: v.optional(v.number()),
+  },
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    let cursor: string | null = null;
+    let copiedSoFar = 0;
+    while (copiedSoFar < (args.limit ?? Infinity)) {
+      const numToCopy = Math.min(
+        args.batchSize ?? DEFAULT_RECENT_MESSAGES,
+        args.limit ?? Infinity - copiedSoFar,
+      );
+      const result: {
+        numCopied: number;
+        continueCursor: string;
+        isDone: boolean;
+      } = await ctx.runMutation(internal.messages.cloneMessageBatch, {
+        ...args,
+        paginationOpts: {
+          cursor,
+          numItems: numToCopy,
+        },
+      });
+      copiedSoFar += result.numCopied;
+      cursor = result.continueCursor;
+      if (result.isDone) {
+        break;
+      }
+    }
+    return copiedSoFar;
+  },
+});
+
+export const listMessagesByThreadIdArgs = {
+  threadId: v.id("threads"),
+  excludeToolMessages: v.optional(v.boolean()),
+  /** What order to sort the messages in. To get the latest, use "desc". */
+  order: v.union(v.literal("asc"), v.literal("desc")),
+  paginationOpts: v.optional(paginationOptsValidator),
+  statuses: v.optional(v.array(vMessageStatus)),
+  upToAndIncludingMessageId: v.optional(v.id("messages")),
+};
+export const listMessagesByThreadId = query({
+  args: listMessagesByThreadIdArgs,
+  handler: async (ctx, args) => {
+    const messages = await listMessagesByThreadIdHandler(ctx, args);
     return { ...messages, page: messages.page.map(publicMessage) };
   },
   returns: vPaginationResult(vMessageDoc),
 });
 
+async function listMessagesByThreadIdHandler(
+  ctx: QueryCtx,
+  args: ObjectType<typeof listMessagesByThreadIdArgs>,
+) {
+  const statuses = args.statuses ?? vMessageStatus.members.map((m) => m.value);
+  const last =
+    args.upToAndIncludingMessageId &&
+    (await ctx.db.get(args.upToAndIncludingMessageId));
+  assert(
+    !last || last.threadId === args.threadId,
+    "upToAndIncludingMessageId must be a message in the thread",
+  );
+  const toolOptions = args.excludeToolMessages ? [false] : [true, false];
+  const order = args.order ?? "desc";
+  const streams = toolOptions.flatMap((tool) =>
+    statuses.map((status) =>
+      stream(ctx.db, schema)
+        .query("messages")
+        .withIndex("threadId_status_tool_order_stepOrder", (q) => {
+          const qq = q
+            .eq("threadId", args.threadId)
+            .eq("status", status)
+            .eq("tool", tool);
+          if (last) {
+            return qq.lte("order", last.order);
+          }
+          return qq;
+        })
+        .order(order)
+        .filterWith(
+          // We allow all messages on the same order.
+          async (m) => !last || m.order <= last.order,
+        ),
+    ),
+  );
+  const messages = await mergedStream(streams, ["order", "stepOrder"]).paginate(
+    args.paginationOpts ?? {
+      numItems: DEFAULT_RECENT_MESSAGES,
+      cursor: null,
+    },
+  );
+  if (messages.page.length === 0) {
+    messages.isDone = true;
+  }
+  return messages;
+}
+
 export const getMessagesByIds = query({
   args: { messageIds: v.array(v.id("messages")) },
   handler: async (ctx, args) => {

package/src/component/vector/index.ts

@@ -35,11 +35,9 @@ export const paginate = query({
     const tableName = getVectorTableName(args.vectorDimension);
     const vectors = await paginator(ctx.db, schema)
       .query(tableName)
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       .withIndex("model_table_threadId" as any, (q) =>
         args.table
-          ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (q.eq("model", args.targetModel) as any).eq("table", args.table)
+          ? (q.eq("model", args.targetModel) as any).eq("table", args.table)
           : q.eq("model", args.targetModel),
       )
       .paginate({

package/src/deltas.ts

@@ -79,7 +79,7 @@ export async function updateFromUIMessageChunks(
   for await (const messagePart of messageStream) {
     assert(
       messagePart.id === message.id,
-      `Expecting to only make one UIMessage in a stream, but have ${JSON.stringify(message)} and created ${JSON.stringify(messagePart)}`,
+      `Expecting to only make one UIMessage in a stream`,
     );
     message = messagePart;
   }

package/src/mapping.ts

@@ -60,8 +60,7 @@ export type SerializeUrlsAndUint8Arrays<T> = T extends URL
     ? ArrayBuffer
     : T extends Array<infer Inner>
       ? Array<SerializeUrlsAndUint8Arrays<Inner>>
-      : // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        T extends Record<string, any>
+      : T extends Record<string, any>
         ? { [K in keyof T]: SerializeUrlsAndUint8Arrays<T[K]> }
         : T;
 
@@ -109,9 +108,7 @@ export async function serializeOrThrow(
   message: ModelMessage | Message,
 ): Promise<SerializedMessage> {
   const { content } = await serializeContent(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     {} as any,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     {} as any,
     message.content,
   );

package/src/react/useDeltaStreams.ts

@@ -10,7 +10,6 @@ import { useState } from "react";
 import { assert } from "convex-helpers";
 
 export function useDeltaStreams<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   Query extends StreamQuery<any> = StreamQuery<object>,
 >(
   query: Query,

package/src/react/useStreamingUIMessages.ts

@@ -13,7 +13,6 @@ import { useDeltaStreams } from "./useDeltaStreams.js";
 
 // Polyfill structuredClone to support readUIMessageStream on ReactNative
 if (!("structuredClone" in globalThis)) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   void import("@ungap/structured-clone" as any).then(
     ({ default: structuredClone }) =>
       (globalThis.structuredClone = structuredClone),
@@ -38,7 +37,6 @@ export function useStreamingUIMessages<
   METADATA = unknown,
   DATA_PARTS extends UIDataTypes = UIDataTypes,
   TOOLS extends UITools = UITools,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   Query extends StreamQuery<any> = StreamQuery<object>,
 >(
   query: Query,

package/src/react/useThreadMessages.ts

@@ -116,10 +116,7 @@ export type ThreadMessagesResult<
  * @returns The messages. If stream is true, it will return a list of messages
  *   that includes both full messages and streaming messages.
  */
-export function useThreadMessages<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Query extends ThreadMessagesQuery<any, any>,
->(
+export function useThreadMessages<Query extends ThreadMessagesQuery<any, any>>(
   query: Query,
   args: ThreadMessagesArgs<Query> | "skip",
   options: {
@@ -154,8 +151,7 @@ export function useThreadMessages<
       args === "skip" ||
       paginated.status === "LoadingFirstPage"
       ? "skip"
-      : // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        ({ ...args, paginationOpts: { cursor: null, numItems: 0 } } as any),
+      : ({ ...args, paginationOpts: { cursor: null, numItems: 0 } } as any),
     { startOrder },
   );
 
@@ -222,10 +218,7 @@ export function useThreadMessages<
  * you want to pass to the query.
  * @returns The streaming messages.
  */
-export function useStreamingThreadMessages<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Query extends StreamQuery<any>,
->(
+export function useStreamingThreadMessages<Query extends StreamQuery<any>>(
   query: Query,
   args:
     | (StreamQueryArgs<Query> & {

package/src/react/useUIMessages.ts

@@ -122,10 +122,7 @@ export type UIMessagesQueryResult<
  *   The streaming messages are materialized as UIMessages. The rest are passed
  *   through from the query.
  */
-export function useUIMessages<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Query extends UIMessagesQuery<any, any>,
->(
+export function useUIMessages<Query extends UIMessagesQuery<any, any>>(
   query: Query,
   args: UIMessagesQueryArgs<Query> | "skip",
   options: {
@@ -153,8 +150,7 @@ export function useUIMessages<
       args === "skip" ||
       paginated.status === "LoadingFirstPage"
       ? "skip"
-      : // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        ({ ...args, paginationOpts: { cursor: null, numItems: 0 } } as any),
+      : ({ ...args, paginationOpts: { cursor: null, numItems: 0 } } as any),
     { startOrder, skipStreamIds: options.skipStreamIds },
   );
 

package/src/test.ts

@@ -1,3 +1,4 @@
+/// <reference types="vite/client" />
 import type { TestConvex } from "convex-test";
 import type { GenericSchema, SchemaDefinition } from "convex/server";
 import schema from "./component/schema.js";
@@ -8,7 +9,7 @@ const modules = import.meta.glob("./component/**/*.ts");
  * @param t - The test convex instance, e.g. from calling `convexTest`.
  * @param name - The name of the component, as registered in convex.config.ts.
  */
-function register(
+export function register(
   t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
   name: string = "agent",
 ) {

package/src/validators.test.ts

@@ -1,10 +1,6 @@
-import type { Infer } from "convex/values";
+import type { GenericId, Infer } from "convex/values";
 import { expectTypeOf, test } from "vitest";
-import type {
-  ContextOptions,
-  OpaqueIds,
-  StorageOptions,
-} from "./client/types.js";
+import type { ContextOptions, StorageOptions } from "./client/types.js";
 import { vContextOptions, vMessageDoc, vStorageOptions } from "./validators.js";
 import type { Doc } from "./component/_generated/dataModel.js";
 
@@ -14,10 +10,21 @@ expectTypeOf<ContextOptions>().toExtend<Infer<typeof vContextOptions>>();
 expectTypeOf<Infer<typeof vStorageOptions>>().toExtend<StorageOptions>();
 expectTypeOf<StorageOptions>().toExtend<Infer<typeof vStorageOptions>>();
 
-type MessageBasedOnSchema = OpaqueIds<
+type MessageBasedOnSchema = IdsToStrings<
   Omit<Doc<"messages">, "files" | "stepId" | "parentMessageId">
 >;
 expectTypeOf<Infer<typeof vMessageDoc>>().toEqualTypeOf<MessageBasedOnSchema>();
 expectTypeOf<MessageBasedOnSchema>().toEqualTypeOf<Infer<typeof vMessageDoc>>();
 
 test("noop", () => {});
+
+type IdsToStrings<T> =
+  T extends GenericId<string>
+    ? string
+    : T extends (infer U)[]
+      ? IdsToStrings<U>[]
+      : T extends ArrayBuffer
+        ? ArrayBuffer
+        : T extends object
+          ? { [K in keyof T]: IdsToStrings<T[K]> }
+          : T;