@convex-dev/agent 0.0.14-alpha.1 → 0.0.14-alpha.3

package/src/client/index.ts

@@ -53,7 +53,7 @@ import {
   type ProviderMetadata,
   type ProviderOptions,
   type SearchOptions,
-  Usage,
+  type Usage,
   vSafeObjectArgs,
   vTextArgs,
 } from "../validators.js";
@@ -66,6 +66,16 @@ import type {
 } from "./types.js";
 import schema from "../component/schema.js";
 
+export {
+  vUsage,
+  vProviderMetadata,
+  vUserMessage,
+  vAssistantMessage,
+  vToolMessage,
+  vSystemMessage,
+  vMessage,
+} from "../validators.js";
+
 export type ThreadDoc = OpaqueIds<
   { _id: string; _creationTime: number } & Infer<
     typeof schema.tables.threads.validator
@@ -261,6 +271,11 @@ export class Agent<AgentTools extends ToolSet> {
        * The summary of the thread. Not currently used.
        */
       summary?: string;
+      /**
+       * The usage handler to use for this thread. Overrides any handler
+       * set in the agent constructor.
+       */
+      usageHandler?: UsageHandler;
     }
   ): Promise<{
     threadId: string;
@@ -282,6 +297,7 @@ export class Agent<AgentTools extends ToolSet> {
       parentThreadIds?: string[];
       title?: string;
       summary?: string;
+      usageHandler?: UsageHandler;
     }
   ): Promise<{
     threadId: string;
@@ -293,6 +309,7 @@ export class Agent<AgentTools extends ToolSet> {
       parentThreadIds?: string[];
       title?: string;
       summary?: string;
+      usageHandler?: UsageHandler;
     }
   ): Promise<{
     threadId: string;
@@ -314,6 +331,7 @@ export class Agent<AgentTools extends ToolSet> {
     const { thread } = await this.continueThread(ctx, {
       threadId: threadDoc._id,
       userId: args?.userId,
+      usageHandler: args?.usageHandler,
     });
     return {
       threadId: threadDoc._id,
@@ -321,14 +339,6 @@ export class Agent<AgentTools extends ToolSet> {
     };
   }
 
-  /**
-   * Continues a thread using this agent. Note: threads can be continued
-   * by different agents. This is a convenience around calling the various
-   * generate and stream functions with explicit userId and threadId parameters.
-   * @param ctx The ctx object passed to the action handler
-   * @param { threadId, userId }: the thread and user to associate the messages with.
-   * @returns Functions bound to the userId and threadId on a `{thread}` object.
-   */
   /**
    * Continues a thread using this agent. Note: threads can be continued
    * by different agents. This is a convenience around calling the various
@@ -339,13 +349,7 @@ export class Agent<AgentTools extends ToolSet> {
    */
   async continueThread(
     ctx: RunActionCtx,
-    {
-      threadId,
-      userId,
-    }: {
-      /**
-       * The associated thread created by {@link createThread}
-       */
+    args: {
       /**
        * The associated thread created by {@link createThread}
        */
@@ -355,34 +359,28 @@ export class Agent<AgentTools extends ToolSet> {
        * relevant messages from the same user as context for the LLM calls.
        */
       userId?: string;
+      /**
+       * The usage handler to use for this thread. Overrides any handler
+       * set in the agent constructor.
+       */
+      usageHandler?: UsageHandler;
     }
   ): Promise<{
     thread: Thread<AgentTools>;
   }> {
     return {
       thread: {
-        threadId,
-        generateText: this.generateText.bind(this, ctx, { userId, threadId }),
-        streamText: this.streamText.bind(this, ctx, { userId, threadId }),
-        generateObject: this.generateObject.bind(this, ctx, {
-          userId,
-          threadId,
-        }),
-        streamObject: this.streamObject.bind(this, ctx, { userId, threadId }),
+        threadId: args.threadId,
+        generateText: this.generateText.bind(this, ctx, args),
+        streamText: this.streamText.bind(this, ctx, args),
+        generateObject: this.generateObject.bind(this, ctx, args),
+        streamObject: this.streamObject.bind(this, ctx, args),
       } as Thread<AgentTools>,
     };
   }
 
   /**
-   *
-   * @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
-   */
-  /**
-   *
+   * 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.
@@ -651,9 +649,15 @@ export class Agent<AgentTools extends ToolSet> {
     {
       userId,
       threadId,
+      usageHandler,
     }: {
       userId?: string;
       threadId?: string;
+      /**
+       * The usage handler to use for this thread. Overrides any handler
+       * set in the agent constructor.
+       */
+      usageHandler?: UsageHandler;
     },
     args: TextArgs<
       AgentTools,
@@ -673,6 +677,7 @@ export class Agent<AgentTools extends ToolSet> {
       args.saveOutputMessages ??
       this.options.storageOptions?.saveOutputMessages;
     const model = aiArgs.model ?? this.options.chat;
+    const trackUsage = usageHandler ?? this.options.usageHandler;
     try {
       const result = (await generateText({
         // Can be overridden
@@ -691,8 +696,8 @@ export class Agent<AgentTools extends ToolSet> {
               step,
             });
           }
-          if (this.options.usageHandler && step.usage) {
-            await this.options.usageHandler(ctx, {
+          if (trackUsage && step.usage) {
+            await trackUsage(ctx, {
               userId,
               threadId,
               agentName: this.options.name,
@@ -737,7 +742,11 @@ export class Agent<AgentTools extends ToolSet> {
     PARTIAL_OUTPUT = never,
   >(
     ctx: RunActionCtx,
-    { userId, threadId }: { userId?: string; threadId?: string },
+    {
+      userId,
+      threadId,
+      usageHandler,
+    }: { userId?: string; threadId?: string; usageHandler?: UsageHandler },
     args: TextArgs<
       AgentTools,
       TOOLS,
@@ -756,6 +765,7 @@ export class Agent<AgentTools extends ToolSet> {
       args.saveOutputMessages ??
       this.options.storageOptions?.saveOutputMessages;
     const model = aiArgs.model ?? this.options.chat;
+    const trackUsage = usageHandler ?? this.options.usageHandler;
     const result = streamText({
       // Can be overridden
       maxSteps: this.options.maxSteps,
@@ -789,8 +799,8 @@ export class Agent<AgentTools extends ToolSet> {
             step,
           });
         }
-        if (this.options.usageHandler && step.usage) {
-          await this.options.usageHandler(ctx, {
+        if (trackUsage && step.usage) {
+          await trackUsage(ctx, {
             userId,
             threadId,
             agentName: this.options.name,
@@ -889,7 +899,11 @@ export class Agent<AgentTools extends ToolSet> {
    */
   async generateObject<T>(
     ctx: RunActionCtx,
-    { userId, threadId }: { userId?: string; threadId?: string },
+    {
+      userId,
+      threadId,
+      usageHandler,
+    }: { userId?: string; threadId?: string; usageHandler?: UsageHandler },
     args: OurObjectArgs<T>
   ): Promise<GenerateObjectResult<T> & GenerationOutputMetadata> {
     const { args: aiArgs, messageId } = await this.saveMessagesAndFetchContext(
@@ -897,6 +911,7 @@ export class Agent<AgentTools extends ToolSet> {
       { ...args, userId, threadId }
     );
     const model = aiArgs.model ?? this.options.chat;
+    const trackUsage = usageHandler ?? this.options.usageHandler;
     const saveOutputMessages =
       args.saveOutputMessages ??
       this.options.storageOptions?.saveOutputMessages;
@@ -913,8 +928,8 @@ export class Agent<AgentTools extends ToolSet> {
         await this.saveObject(ctx, { threadId, messageId, result });
       }
       result.messageId = messageId;
-      if (this.options.usageHandler && result.usage) {
-        await this.options.usageHandler(ctx, {
+      if (trackUsage && result.usage) {
+        await trackUsage(ctx, {
           userId,
           threadId,
           agentName: this.options.name,
@@ -950,7 +965,11 @@ export class Agent<AgentTools extends ToolSet> {
    */
   async streamObject<T>(
     ctx: RunActionCtx,
-    { userId, threadId }: { userId?: string; threadId?: string },
+    {
+      userId,
+      threadId,
+      usageHandler,
+    }: { userId?: string; threadId?: string; usageHandler?: UsageHandler },
     args: OurStreamObjectArgs<T>
   ): Promise<
     StreamObjectResult<DeepPartial<T>, T, never> & GenerationOutputMetadata
@@ -961,6 +980,7 @@ export class Agent<AgentTools extends ToolSet> {
       { ...args, userId, threadId }
     );
     const model = aiArgs.model ?? this.options.chat;
+    const trackUsage = usageHandler ?? this.options.usageHandler;
     const saveOutputMessages =
       args.saveOutputMessages ??
       this.options.storageOptions?.saveOutputMessages;
@@ -994,8 +1014,8 @@ export class Agent<AgentTools extends ToolSet> {
             },
           });
         }
-        if (this.options.usageHandler && result.usage) {
-          await this.options.usageHandler(ctx, {
+        if (trackUsage && result.usage) {
+          await trackUsage(ctx, {
             userId,
             threadId,
             agentName: this.options.name,

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

@@ -155,11 +155,11 @@ export type Mounts = {
               };
           model?: string;
           provider?: string;
-          providerMetadata?: Record<string, any>;
+          providerMetadata?: Record<string, Record<string, any>>;
           reasoning?: string;
           sources?: Array<{
             id: string;
-            providerMetadata?: Record<string, any>;
+            providerMetadata?: Record<string, Record<string, any>>;
             sourceType: "url";
             title?: string;
             url: string;
@@ -313,7 +313,7 @@ export type Mounts = {
           reasoning?: string;
           sources?: Array<{
             id: string;
-            providerMetadata?: Record<string, any>;
+            providerMetadata?: Record<string, Record<string, any>>;
             sourceType: "url";
             title?: string;
             url: string;
@@ -466,7 +466,7 @@ export type Mounts = {
           reasoning?: string;
           sources?: Array<{
             id: string;
-            providerMetadata?: Record<string, any>;
+            providerMetadata?: Record<string, Record<string, any>>;
             sourceType: "url";
             title?: string;
             url: string;
@@ -623,11 +623,11 @@ export type Mounts = {
                 };
             model?: string;
             provider?: string;
-            providerMetadata?: Record<string, any>;
+            providerMetadata?: Record<string, Record<string, any>>;
             reasoning?: string;
             sources?: Array<{
               id: string;
-              providerMetadata?: Record<string, any>;
+              providerMetadata?: Record<string, Record<string, any>>;
               sourceType: "url";
               title?: string;
               url: string;
@@ -661,7 +661,7 @@ export type Mounts = {
               | "unknown";
             isContinued: boolean;
             logprobs?: any;
-            providerMetadata?: Record<string, any>;
+            providerMetadata?: Record<string, Record<string, any>>;
             providerOptions?: Record<string, any>;
             reasoning?: string;
             reasoningDetails?: Array<any>;
@@ -805,7 +805,7 @@ export type Mounts = {
             };
             sources?: Array<{
               id: string;
-              providerMetadata?: Record<string, any>;
+              providerMetadata?: Record<string, Record<string, any>>;
               sourceType: "url";
               title?: string;
               url: string;
@@ -871,7 +871,7 @@ export type Mounts = {
             | "unknown";
           isContinued: boolean;
           logprobs?: any;
-          providerMetadata?: Record<string, any>;
+          providerMetadata?: Record<string, Record<string, any>>;
           providerOptions?: Record<string, any>;
           reasoning?: string;
           reasoningDetails?: Array<any>;
@@ -1015,7 +1015,7 @@ export type Mounts = {
           };
           sources?: Array<{
             id: string;
-            providerMetadata?: Record<string, any>;
+            providerMetadata?: Record<string, Record<string, any>>;
             sourceType: "url";
             title?: string;
             url: string;
@@ -1294,7 +1294,7 @@ export type Mounts = {
           reasoning?: string;
           sources?: Array<{
             id: string;
-            providerMetadata?: Record<string, any>;
+            providerMetadata?: Record<string, Record<string, any>>;
             sourceType: "url";
             title?: string;
             url: string;
@@ -1504,7 +1504,7 @@ export type Mounts = {
         reasoning?: string;
         sources?: Array<{
           id: string;
-          providerMetadata?: Record<string, any>;
+          providerMetadata?: Record<string, Record<string, any>>;
           sourceType: "url";
           title?: string;
           url: string;
@@ -1662,7 +1662,7 @@ export type Mounts = {
         reasoning?: string;
         sources?: Array<{
           id: string;
-          providerMetadata?: Record<string, any>;
+          providerMetadata?: Record<string, Record<string, any>>;
           sourceType: "url";
           title?: string;
           url: string;

package/src/validators.ts

@@ -5,8 +5,12 @@ import { vVectorDimension } from "./component/vector/tables";
 
 const providerOptions = v.optional(v.record(v.string(), v.any()));
 export type ProviderOptions = Infer<typeof providerOptions>;
+const providerMetadata = v.optional(
+  v.record(v.string(), v.record(v.string(), v.any()))
+);
+export { providerMetadata as vProviderMetadata };
+export type ProviderMetadata = Infer<typeof providerMetadata>;
 const experimental_providerMetadata = providerOptions;
-export type ProviderMetadata = Infer<typeof experimental_providerMetadata>;
 
 export const vThreadStatus = v.union(
   v.literal("active"),
@@ -161,7 +165,7 @@ export const vSource = v.object({
   id: v.string(),
   url: v.string(),
   title: v.optional(v.string()),
-  providerMetadata: providerOptions,
+  providerMetadata,
 });
 
 export const vRequest = v.object({
@@ -238,7 +242,7 @@ export const vMessageWithMetadata = v.object({
   finishReason: v.optional(vFinishReason),
   model: v.optional(v.string()),
   provider: v.optional(v.string()),
-  providerMetadata: v.optional(v.record(v.string(), v.any())),
+  providerMetadata,
   sources: v.optional(v.array(vSource)),
   reasoning: v.optional(v.string()),
   usage: v.optional(vUsage),
@@ -261,7 +265,7 @@ export const vStep = v.object({
   finishReason: vFinishReason,
   isContinued: v.boolean(),
   logprobs: v.optional(v.any()),
-  providerMetadata: providerOptions,
+  providerMetadata,
   providerOptions,
   reasoning: v.optional(v.string()),
   reasoningDetails: v.optional(v.array(v.any())),
@@ -295,7 +299,7 @@ export const vObjectResult = v.object({
   object: v.any(),
   error: v.optional(v.string()),
   warnings: v.optional(v.array(vLanguageModelV1CallWarning)),
-  providerMetadata: providerOptions,
+  providerMetadata,
   experimental_providerMetadata,
 });
 export type ObjectResult = Infer<typeof vObjectResult>;