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

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,
@@ -174,8 +174,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
@@ -337,7 +336,6 @@ export class Agent<AgentTools extends ToolSet> {
     const threadDoc = await ctx.runMutation(
       this.component.messages.createThread,
       {
-        defaultSystemPrompt: this.options.instructions,
         userId: args?.userId,
         title: args?.title,
         summary: args?.summary,
@@ -460,13 +458,21 @@ export class Agent<AgentTools extends ToolSet> {
           statuses: ["success"],
         }
       );
-      contextMessages.push(...page.filter((m) => !included?.has(m._id)));
+      contextMessages.push(
+        // Reverse since we fetched in descending order
+        ...page.filter((m) => !included?.has(m._id)).reverse()
+      );
     }
-    return contextMessages
-      .sort((a, b) =>
-        a.order === b.order ? a.stepOrder - b.stepOrder : a.order - b.order
-      )
-      .map((m) => deserializeMessage(m.message!));
+
+    // Sort the raw MessageDocs by order and stepOrder
+    const sortedDocs = contextMessages.sort((a, b) =>
+      a.order === b.order ? a.stepOrder - b.stepOrder : a.order - b.order
+    );
+
+    // Ensure we don't include tool messages without a corresponding tool call
+    return filterOutOrphanedToolMessages(sortedDocs).map((m) =>
+      deserializeMessage(m.message!)
+    );
   }
 
   /**
@@ -700,14 +706,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 +723,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;
@@ -801,7 +810,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 +821,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 +830,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;
@@ -886,28 +898,23 @@ 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,
@@ -924,7 +931,7 @@ 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,
@@ -936,7 +943,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 +969,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 {
@@ -1028,18 +1038,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>({
@@ -1227,18 +1240,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 +1276,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;
       },
@@ -1273,6 +1313,34 @@ export class Agent<AgentTools extends ToolSet> {
   }
 }
 
+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;
+}
+
+
 export type ToolCtx = RunActionCtx & {
   userId?: string;
   threadId?: string;
@@ -1373,6 +1441,21 @@ function wrapTools(
   return output;
 }
 
+type Options = {
+  /**
+   * 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;
+};
+
 type TextArgs<
   AgentTools extends ToolSet,
   TOOLS extends ToolSet | undefined = undefined,
@@ -1403,20 +1486,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 +1519,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 +1550,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 +1581,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 +1616,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 +1645,8 @@ interface Thread<DefaultTools extends ToolSet> {
       TOOLS,
       OUTPUT,
       OUTPUT_PARTIAL
-    >
+    >,
+    options?: Options
   ): Promise<
     GenerateTextResult<TOOLS extends undefined ? DefaultTools : TOOLS, OUTPUT> &
       ThreadOutputMetadata
@@ -1621,7 +1672,8 @@ interface Thread<DefaultTools extends ToolSet> {
       TOOLS,
       OUTPUT,
       PARTIAL_OUTPUT
-    >
+    >,
+    options?: Options
   ): Promise<
     StreamTextResult<
       TOOLS extends undefined ? DefaultTools : TOOLS,
@@ -1640,7 +1692,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 +1706,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 +1720,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
   >;

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

@@ -1692,7 +1692,6 @@ export type Mounts = {
       "public",
       {
         patch: {
-          defaultSystemPrompt?: string;
           status?: "active" | "archived";
           summary?: string;
           title?: string;

package/src/component/messages.ts

@@ -80,14 +80,7 @@ export const updateThread = mutation({
   args: {
     threadId: v.id("threads"),
     patch: v.object(
-      partial(
-        pick(vThread.fields, [
-          "title",
-          "summary",
-          "defaultSystemPrompt",
-          "status",
-        ])
-      )
+      partial(pick(vThread.fields, ["title", "summary", "status"]))
     ),
   },
   handler: async (ctx, args) => {

package/src/component/schema.ts

@@ -16,12 +16,11 @@ import vectorTables, { vVectorId } from "./vector/tables.js";
 export const schema = defineSchema({
   threads: defineTable({
     userId: v.optional(v.string()), // Unset for anonymous
-    // TODO: is this bubbling up in continue?
-    defaultSystemPrompt: v.optional(v.string()),
     title: v.optional(v.string()),
     summary: v.optional(v.string()),
     status: vThreadStatus,
     // DEPRECATED
+    defaultSystemPrompt: v.optional(v.string()),
     parentThreadIds: v.optional(v.array(v.id("threads"))),
     order: /*DEPRECATED*/ v.optional(v.number()),
   }).index("userId", ["userId"]),