@convex-dev/agent 0.0.15-alpha.1 → 0.0.16-alpha.0

package/src/client/index.ts

@@ -27,7 +27,7 @@ import { assert } from "convex-helpers";
 import { internalActionGeneric, internalMutationGeneric } from "convex/server";
 import { Infer, v } from "convex/values";
 import { z } from "zod";
-import { api } from "../component/_generated/api.js";
+import { Mounts } from "../component/_generated/api.js";
 import {
   validateVectorDimension,
   type VectorDimension,
@@ -56,9 +56,9 @@ import {
   type Usage,
   vSafeObjectArgs,
   vTextArgs,
+  vThreadStatus,
 } from "../validators.js";
 import type {
-  OpaqueIds,
   RunActionCtx,
   RunMutationCtx,
   RunQueryCtx,
@@ -66,6 +66,7 @@ import type {
 } from "./types.js";
 import schema from "../component/schema.js";
 
+export { extractText, isTool };
 export type { Usage, ProviderMetadata };
 export {
   vUsage,
@@ -77,27 +78,42 @@ export {
   vMessage,
 } from "../validators.js";
 
-export type ThreadDoc = OpaqueIds<
-  { _id: string; _creationTime: number } & Infer<
-    typeof schema.tables.threads.validator
-  >
->;
-export type MessageDoc = OpaqueIds<
-  { _id: string; _creationTime: number } & Infer<
-    typeof schema.tables.messages.validator
-  >
->;
+export const vThreadDoc = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  userId: v.optional(v.string()), // Unset for anonymous
+  title: v.optional(v.string()),
+  summary: v.optional(v.string()),
+  status: vThreadStatus,
+});
+export type ThreadDoc = Infer<typeof vThreadDoc>;
+
+export const vMessageDoc = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  ...schema.tables.messages.validator.fields,
+  // Overwrite all the types that have a v.id validator
+  // Outside of the component, they are strings
+  threadId: v.string(),
+  parentMessageId: v.optional(v.string()),
+  stepId: v.optional(v.string()),
+  embeddingId: v.optional(v.string()),
+  fileId: v.optional(v.string()),
+});
+export type MessageDoc = Infer<typeof vMessageDoc>;
 
 /**
  * Options to configure what messages are fetched as context,
  * automatically with thread.generateText, or directly via search.
  */
 export type ContextOptions = {
+  /** @deprecated Use excludeToolMessages instead. */
+  includeToolCalls?: boolean;
   /**
    * Whether to include tool messages in the context.
    * By default, tool calls and results are not included.
    */
-  includeToolCalls?: boolean;
+  excludeToolMessages?: boolean;
   /**
    * How many recent messages to include. These are added after the search
    * messages, and do not count against the search limit.
@@ -174,8 +190,7 @@ export type UsageHandler = (
 
 export class Agent<AgentTools extends ToolSet> {
   constructor(
-    // public component: UseApi<Mounts>,
-    public component: UseApi<typeof api>,
+    public component: UseApi<Mounts>,
     public options: {
       /**
        * The name for the agent. This will be attributed on each message
@@ -335,9 +350,8 @@ export class Agent<AgentTools extends ToolSet> {
     thread?: Thread<ThreadTools extends undefined ? AgentTools : ThreadTools>;
   }> {
     const threadDoc = await ctx.runMutation(
-      this.component.messages.createThread,
+      this.component.threads.createThread,
       {
-        defaultSystemPrompt: this.options.instructions,
         userId: args?.userId,
         title: args?.title,
         summary: args?.summary,
@@ -417,7 +431,12 @@ export class Agent<AgentTools extends ToolSet> {
       userId: string | undefined;
       threadId: string | undefined;
       messages: CoreMessage[];
-      parentMessageId?: string;
+      /**
+       * If provided, it will search for messages before this message.
+       * Note: if this is far in the past, the search results may be more
+       * limited, as it's post-filtering the results.
+       */
+      beforeMessageId?: string;
       contextOptions: ContextOptions | undefined;
     }
   ): Promise<CoreMessage[]> {
@@ -437,7 +456,7 @@ export class Agent<AgentTools extends ToolSet> {
             ? args.userId
             : undefined,
           threadId: args.threadId,
-          parentMessageId: args.parentMessageId,
+          beforeMessageId: args.beforeMessageId,
           ...(await this.searchOptionsWithDefaults(opts, args.messages)),
         }
       );
@@ -447,15 +466,16 @@ export class Agent<AgentTools extends ToolSet> {
     }
     if (args.threadId && opts.recentMessages !== 0) {
       const { page } = await ctx.runQuery(
-        this.component.messages.getThreadMessages,
+        this.component.messages.listMessagesByThreadId,
         {
           threadId: args.threadId,
-          isTool: opts.includeToolCalls ? undefined : false,
+          excludeToolMessages:
+            opts.includeToolCalls === true ? false : opts.excludeToolMessages,
           paginationOpts: {
             numItems: opts.recentMessages ?? DEFAULT_RECENT_MESSAGES,
             cursor: null,
           },
-          parentMessageId: args.parentMessageId,
+          beforeMessageId: args.beforeMessageId,
           order: "desc",
           statuses: ["success"],
         }
@@ -538,13 +558,8 @@ export class Agent<AgentTools extends ToolSet> {
        */
       pending?: boolean;
       /**
-       * The message that this is responding to.
-       */
-      parentMessageId?: string;
-      /**
-       * Whether to mark all pending messages in the thread as failed.
-       * This is used to recover from a failure via a retry that wipes the slate clean.
-       * Defaults to true.
+       * If true, it will fail any pending steps.
+       * Defaults to false.
        */
       failPendingSteps?: boolean;
     }
@@ -569,9 +584,8 @@ export class Agent<AgentTools extends ToolSet> {
             message: serializeMessage(m),
           }) as MessageWithMetadata
       ),
-      failPendingSteps: args.failPendingSteps ?? true,
+      failPendingSteps: args.failPendingSteps ?? false,
       pending: args.pending ?? false,
-      parentMessageId: args.parentMessageId,
     });
     return {
       lastMessageId: result.messages.at(-1)!._id,
@@ -592,7 +606,7 @@ export class Agent<AgentTools extends ToolSet> {
       /**
        * The message this step is in response to.
        */
-      messageId: string;
+      parentMessageId: string;
       /**
        * The step to save, possibly including multiple tool calls.
        */
@@ -629,7 +643,7 @@ export class Agent<AgentTools extends ToolSet> {
     await ctx.runMutation(this.component.messages.addStep, {
       userId: args.userId,
       threadId: args.threadId,
-      messageId: args.messageId,
+      parentMessageId: args.parentMessageId,
       step: { step, messages },
       failPendingSteps: false,
     });
@@ -700,14 +714,16 @@ export class Agent<AgentTools extends ToolSet> {
        */
       tools?: ToolSet;
     },
-    args: TextArgs<AgentTools, TOOLS, OUTPUT, OUTPUT_PARTIAL>
+    args: TextArgs<AgentTools, TOOLS, OUTPUT, OUTPUT_PARTIAL>,
+    options?: Options
   ): Promise<
     GenerateTextResult<TOOLS extends undefined ? AgentTools : TOOLS, OUTPUT> &
       GenerationOutputMetadata
   > {
     const { args: aiArgs, messageId } = await this.saveMessagesAndFetchContext(
       ctx,
-      { ...args, userId, threadId }
+      args,
+      { userId, threadId, ...options }
     );
     const toolCtx = { ...ctx, userId, threadId, messageId };
     const tools = wrapTools(
@@ -715,6 +731,7 @@ export class Agent<AgentTools extends ToolSet> {
       args.tools ?? threadTools ?? this.options.tools
     ) as TOOLS extends undefined ? AgentTools : TOOLS;
     const saveOutputMessages =
+      options?.storageOptions?.saveOutputMessages ??
       args.saveOutputMessages ??
       this.options.storageOptions?.saveOutputMessages;
     const model = aiArgs.model ?? this.options.chat;
@@ -732,7 +749,7 @@ export class Agent<AgentTools extends ToolSet> {
             await this.saveStep(ctx, {
               userId,
               threadId,
-              messageId,
+              parentMessageId: messageId,
               step,
             });
           }
@@ -801,7 +818,8 @@ export class Agent<AgentTools extends ToolSet> {
       usageHandler?: UsageHandler;
       tools?: ToolSet;
     },
-    args: StreamingTextArgs<AgentTools, TOOLS, OUTPUT, PARTIAL_OUTPUT>
+    args: StreamingTextArgs<AgentTools, TOOLS, OUTPUT, PARTIAL_OUTPUT>,
+    options?: Options
   ): Promise<
     StreamTextResult<
       TOOLS extends undefined ? AgentTools : TOOLS,
@@ -811,7 +829,8 @@ export class Agent<AgentTools extends ToolSet> {
   > {
     const { args: aiArgs, messageId } = await this.saveMessagesAndFetchContext(
       ctx,
-      { ...args, userId, threadId }
+      args,
+      { userId, threadId, ...options }
     );
     const toolCtx = { ...ctx, userId, threadId, messageId };
     const tools = wrapTools(
@@ -819,6 +838,7 @@ export class Agent<AgentTools extends ToolSet> {
       args.tools ?? threadTools ?? this.options.tools
     ) as TOOLS extends undefined ? AgentTools : TOOLS;
     const saveOutputMessages =
+      options?.storageOptions?.saveOutputMessages ??
       args.saveOutputMessages ??
       this.options.storageOptions?.saveOutputMessages;
     const model = aiArgs.model ?? this.options.chat;
@@ -851,7 +871,7 @@ export class Agent<AgentTools extends ToolSet> {
           await this.saveStep(ctx, {
             userId,
             threadId,
-            messageId,
+            parentMessageId: messageId,
             step,
           });
         }
@@ -886,34 +906,27 @@ export class Agent<AgentTools extends ToolSet> {
     },
   >(
     ctx: RunActionCtx | RunMutationCtx,
+    args: T,
     {
-      id,
       userId,
       threadId,
-      parentMessageId,
-      system,
-      ...args
+      contextOptions,
+      storageOptions,
     }: {
       userId: string | undefined;
       threadId: string | undefined;
-      parentMessageId?: string;
-      contextOptions?: ContextOptions;
-      storageOptions?: StorageOptions;
-    } & T
+    } & Options
   ): Promise<{
     args: T;
     messageId: string | undefined;
   }> {
-    const contextOptions: ContextOptions | Record<string, unknown> =
-      args.contextOptions ?? this.options.contextOptions ?? args;
-    const storageOptions: StorageOptions | Record<string, unknown> =
-      args.storageOptions ?? this.options.storageOptions ?? args;
+    contextOptions ||= this.options.contextOptions ?? (args as ContextOptions);
+    storageOptions ||= this.options.storageOptions ?? (args as StorageOptions);
     const messages = promptOrMessagesToCoreMessages(args);
     const contextMessages = await this.fetchContextMessages(ctx, {
       userId,
       threadId,
       messages,
-      parentMessageId,
       contextOptions,
     });
     let messageId: string | undefined;
@@ -924,11 +937,9 @@ export class Agent<AgentTools extends ToolSet> {
         threadId,
         userId,
         messages: coreMessages,
-        metadata: coreMessages.length === 1 ? [{ id }] : undefined,
+        metadata: coreMessages.length === 1 ? [{ id: args.id }] : undefined,
         pending: true,
-        // We should just fail if you pass in an ID for the message, fail those children
-        // failPendingSteps: true,
-        parentMessageId,
+        failPendingSteps: true,
       });
       messageId = saved.lastMessageId;
     }
@@ -936,7 +947,7 @@ export class Agent<AgentTools extends ToolSet> {
     return {
       args: {
         ...rest,
-        system: system ?? this.options.instructions,
+        system: args.system ?? this.options.instructions,
         messages: [...contextMessages, ...messages],
       } as T,
       messageId,
@@ -962,15 +973,18 @@ export class Agent<AgentTools extends ToolSet> {
       threadId,
       usageHandler,
     }: { userId?: string; threadId?: string; usageHandler?: UsageHandler },
-    args: OurObjectArgs<T>
+    args: OurObjectArgs<T>,
+    options?: Options
   ): Promise<GenerateObjectResult<T> & GenerationOutputMetadata> {
     const { args: aiArgs, messageId } = await this.saveMessagesAndFetchContext(
       ctx,
-      { ...args, userId, threadId }
+      args,
+      { userId, threadId, ...options }
     );
     const model = aiArgs.model ?? this.options.chat;
     const trackUsage = usageHandler ?? this.options.usageHandler;
     const saveOutputMessages =
+      options?.storageOptions?.saveOutputMessages ??
       args.saveOutputMessages ??
       this.options.storageOptions?.saveOutputMessages;
     try {
@@ -983,7 +997,12 @@ export class Agent<AgentTools extends ToolSet> {
       } as any)) as GenerateObjectResult<T> & GenerationOutputMetadata;
 
       if (threadId && messageId && saveOutputMessages !== false) {
-        await this.saveObject(ctx, { threadId, messageId, result, userId });
+        await this.saveObject(ctx, {
+          threadId,
+          parentMessageId: messageId,
+          result,
+          userId,
+        });
       }
       result.messageId = messageId;
       if (trackUsage && result.usage) {
@@ -1028,18 +1047,21 @@ export class Agent<AgentTools extends ToolSet> {
       threadId,
       usageHandler,
     }: { userId?: string; threadId?: string; usageHandler?: UsageHandler },
-    args: OurStreamObjectArgs<T>
+    args: OurStreamObjectArgs<T>,
+    options?: Options
   ): Promise<
     StreamObjectResult<DeepPartial<T>, T, never> & GenerationOutputMetadata
   > {
     // TODO: unify all this shared code between all the generate* and stream* functions
     const { args: aiArgs, messageId } = await this.saveMessagesAndFetchContext(
       ctx,
-      { ...args, userId, threadId }
+      args,
+      { userId, threadId, ...options }
     );
     const model = aiArgs.model ?? this.options.chat;
     const trackUsage = usageHandler ?? this.options.usageHandler;
     const saveOutputMessages =
+      options?.storageOptions?.saveOutputMessages ??
       args.saveOutputMessages ??
       this.options.storageOptions?.saveOutputMessages;
     const stream = streamObject<T>({
@@ -1057,7 +1079,7 @@ export class Agent<AgentTools extends ToolSet> {
           await this.saveObject(ctx, {
             userId,
             threadId,
-            messageId,
+            parentMessageId: messageId,
             result: {
               object: result.object,
               finishReason: "stop",
@@ -1105,7 +1127,7 @@ export class Agent<AgentTools extends ToolSet> {
     args: {
       userId: string | undefined;
       threadId: string;
-      messageId: string;
+      parentMessageId: string;
       result: GenerateObjectResult<unknown>;
       metadata?: Omit<MessageWithMetadata, "message">;
     }
@@ -1134,7 +1156,7 @@ export class Agent<AgentTools extends ToolSet> {
     await ctx.runMutation(this.component.messages.addStep, {
       userId: args.userId,
       threadId: args.threadId,
-      messageId: args.messageId,
+      parentMessageId: args.parentMessageId,
       failPendingSteps: false,
       step: { step, messages },
     });
@@ -1227,18 +1249,30 @@ export class Agent<AgentTools extends ToolSet> {
    * @param spec Configuration for the agent acting as an action, including
    *   {@link ContextOptions} and maxSteps.
    */
-  asTextAction(spec?: { contextOptions?: ContextOptions; maxSteps?: number }) {
+  asTextAction(spec?: {
+    contextOptions?: ContextOptions;
+    maxSteps?: number;
+    storageOptions?: StorageOptions;
+  }) {
     const maxSteps = spec?.maxSteps ?? this.options.maxSteps;
-    const contextOptions =
-      spec?.contextOptions && this.mergedContextOptions(spec.contextOptions);
-
     return internalActionGeneric({
       args: vTextArgs,
       handler: async (ctx, args) => {
+        const { contextOptions, storageOptions, ...rest } = args;
         const value = await this.generateText(
           ctx,
           { userId: args.userId, threadId: args.threadId },
-          { maxSteps, ...args, ...contextOptions, ...args.storageOptions }
+          { maxSteps, ...rest },
+          {
+            contextOptions:
+              contextOptions ??
+              spec?.contextOptions ??
+              this.options.contextOptions,
+            storageOptions:
+              storageOptions ??
+              spec?.storageOptions ??
+              this.options.storageOptions,
+          }
         );
         return value.text;
       },
@@ -1251,21 +1285,36 @@ export class Agent<AgentTools extends ToolSet> {
    * the normal parameters to {@link generateObject}, plus {@link ContextOptions}
    * and maxSteps.
    */
-  asObjectAction<T>(spec: OurObjectArgs<T> & { maxSteps?: number }) {
+  asObjectAction<T>(
+    spec: OurObjectArgs<T> & { maxSteps?: number },
+    options?: {
+      contextOptions?: ContextOptions;
+      storageOptions?: StorageOptions;
+    }
+  ) {
     const maxSteps = spec?.maxSteps ?? this.options.maxSteps;
     return internalActionGeneric({
       args: vSafeObjectArgs,
       handler: async (ctx, args) => {
+        const { contextOptions, storageOptions, ...rest } = args;
         const value = await this.generateObject(
           ctx,
           { userId: args.userId, threadId: args.threadId },
           {
             ...spec,
             maxSteps,
-            ...args,
-            ...this.mergedContextOptions(spec),
-            ...args.storageOptions,
-          } as unknown as OurObjectArgs<unknown>
+            ...rest,
+          } as unknown as OurObjectArgs<unknown>,
+          {
+            contextOptions:
+              contextOptions ??
+              options?.contextOptions ??
+              this.options.contextOptions,
+            storageOptions:
+              storageOptions ??
+              options?.storageOptions ??
+              this.options.storageOptions,
+          }
         );
         return value.object as T;
       },
@@ -1373,6 +1422,17 @@ function wrapTools(
   return output;
 }
 
+type Options = {
+  /**
+   * The context options to use for passing in message history to the LLM.
+   */
+  contextOptions?: ContextOptions;
+  /**
+   * The storage options to use for saving the input and output messages to the thread.
+   */
+  storageOptions?: StorageOptions;
+};
+
 type TextArgs<
   AgentTools extends ToolSet,
   TOOLS extends ToolSet | undefined = undefined,
@@ -1403,20 +1463,7 @@ type TextArgs<
    * specified in the tools array. e.g. {toolName: "getWeather", type: "tool"}
    */
   toolChoice?: ToolChoice<TOOLS extends undefined ? AgentTools : TOOLS>;
-  // Non-AI SDK args
-  /**
-   * The parent message id to use for the tool calls.
-   */
-  parentMessageId?: string;
-  /**
-   * The context options to use for passing in message history to the LLM.
-   */
-  contextOptions?: ContextOptions;
-  /**
-   * The storage options to use for saving the input and output messages to the thread.
-   */
-  storageOptions?: StorageOptions;
-} & ContextOptions &
+} & ContextOptions & // DEPRECATED: pass them in the subsequent parameter instead
   StorageOptions;
 
 type StreamingTextArgs<
@@ -1449,19 +1496,6 @@ type StreamingTextArgs<
    * specified in the tools array. e.g. {toolName: "getWeather", type: "tool"}
    */
   toolChoice?: ToolChoice<TOOLS extends undefined ? AgentTools : TOOLS>;
-  // Non-AI SDK args
-  /**
-   * The parent message id to use for the tool calls.
-   */
-  parentMessageId?: string;
-  /**
-   * The context options to use for passing in message history to the LLM.
-   */
-  contextOptions?: ContextOptions;
-  /**
-   * The storage options to use for saving the input and output messages to the thread.
-   */
-  storageOptions?: StorageOptions;
 } & ContextOptions &
   StorageOptions;
 
@@ -1493,19 +1527,6 @@ type BaseGenerateObjectOptions = StorageOptions &
     experimental_telemetry?: TelemetrySettings;
     providerOptions?: ProviderOptions;
     experimental_providerMetadata?: ProviderMetadata;
-    // Non-AI SDK args
-    /**
-     * The parent message id to use for the object generation.
-     */
-    parentMessageId?: string;
-    /**
-     * The context options to use for passing in message history to the LLM.
-     */
-    contextOptions?: ContextOptions;
-    /**
-     * The storage options to use for saving the input and output messages to the thread.
-     */
-    storageOptions?: StorageOptions;
   };
 
 type GenerateObjectObjectOptions<T extends Record<string, unknown>> =
@@ -1537,6 +1558,8 @@ type GenerateObjectNoSchemaOptions = BaseGenerateObjectOptions & {
   mode?: "json";
 };
 
+// TODO: simplify this to just use the generateObject args, with an optional
+// model and tool/toolChoice types
 type GenerateObjectArgs<T> =
   T extends Record<string, unknown>
     ? GenerateObjectObjectOptions<T>
@@ -1570,6 +1593,10 @@ type ThreadOutputMetadata = GenerationOutputMetadata & {
   messageId: string;
 };
 
+/**
+ * The interface for a thread returned from {@link createThread} or {@link continueThread}.
+ * This is contextual to a thread and/or user.
+ */
 interface Thread<DefaultTools extends ToolSet> {
   /**
    * The target threadId, from the startThread or continueThread initializers.
@@ -1595,7 +1622,8 @@ interface Thread<DefaultTools extends ToolSet> {
       TOOLS,
       OUTPUT,
       OUTPUT_PARTIAL
-    >
+    >,
+    options?: Options
   ): Promise<
     GenerateTextResult<TOOLS extends undefined ? DefaultTools : TOOLS, OUTPUT> &
       ThreadOutputMetadata
@@ -1621,7 +1649,8 @@ interface Thread<DefaultTools extends ToolSet> {
       TOOLS,
       OUTPUT,
       PARTIAL_OUTPUT
-    >
+    >,
+    options?: Options
   ): Promise<
     StreamTextResult<
       TOOLS extends undefined ? DefaultTools : TOOLS,
@@ -1640,7 +1669,8 @@ interface Thread<DefaultTools extends ToolSet> {
    * @returns The result of the generateObject function.
    */
   generateObject<T>(
-    args: OurObjectArgs<T>
+    args: OurObjectArgs<T>,
+    options?: Options
   ): Promise<GenerateObjectResult<T> & ThreadOutputMetadata>;
   /**
    * This behaves like {@link generateObject} from the "ai" package except that
@@ -1653,7 +1683,8 @@ interface Thread<DefaultTools extends ToolSet> {
    * @returns The result of the generateObject function.
    */
   generateObject(
-    args: GenerateObjectNoSchemaOptions
+    args: GenerateObjectNoSchemaOptions,
+    options?: Options
   ): Promise<GenerateObjectResult<JSONValue> & ThreadOutputMetadata>;
   /**
    * This behaves like {@link streamObject} from the "ai" package except that
@@ -1666,7 +1697,8 @@ interface Thread<DefaultTools extends ToolSet> {
    * @returns The result of the streamObject function.
    */
   streamObject<T>(
-    args: OurStreamObjectArgs<T>
+    args: OurStreamObjectArgs<T>,
+    options?: Options
   ): Promise<
     StreamObjectResult<DeepPartial<T>, T, never> & ThreadOutputMetadata
   >;