@convex-dev/agent 0.2.11-alpha.3 → 0.2.11

package/src/client/types.ts

@@ -1,8 +1,8 @@
 import type {
+  FlexibleSchema,
   InferSchema,
   ModelMessage,
   ProviderOptions,
-  Schema,
 } from "@ai-sdk/provider-utils";
 import type { JSONValue } from "@ai-sdk/provider";
 import type {
@@ -17,13 +17,9 @@ import type {
   streamObject,
   streamText,
   StreamTextResult,
-  ToolChoice,
   ToolSet,
-  RepairTextFunction,
-  TelemetrySettings,
   CallSettings,
-  Prompt,
-  Experimental_DownloadFunction,
+  generateObject,
 } from "ai";
 import type {
   Auth,
@@ -38,7 +34,7 @@ import type {
   WithoutSystemFields,
 } from "convex/server";
 import type { GenericId } from "convex/values";
-import type { Mounts } from "../component/_generated/api.js";
+import type { api } from "../component/_generated/api.js";
 import type {
   MessageDoc,
   ProviderMetadata,
@@ -47,8 +43,48 @@ import type {
   ThreadDoc,
 } from "../validators.js";
 import type { StreamingOptions } from "./streaming.js";
-import type * as z3 from "zod/v3";
-import type * as z4 from "zod/v4";
+
+export type AgentPrompt = {
+  /**
+   * System message to include in the prompt. Overwrites Agent instructions.
+   */
+  system?: string;
+  /**
+   * A prompt. It can be either a text prompt or a list of messages.
+   * If used with `promptMessageId`, it will be used in place of that
+   * prompt message and no input messages will be saved.
+   * Otherwise, if used with the storageOptions "promptAndOutput" (default),
+   * it will be the only message saved.
+   * If a string is provided, it will be a user message.
+   */
+  prompt?: string | Array<ModelMessage> | undefined;
+  /**
+   * A list of messages to use as context before the prompt.
+   * If used with `prompt`, these will precede the prompt.
+   * If used with the storageOptions "promptAndOutput" (default),
+   * none of these messages will be saved.
+   */
+  messages?: Array<ModelMessage> | undefined;
+  /**
+   * If provided, it uses this existing message to anchor the prompt:
+   * - The specified message will be included, unless `prompt` is also
+   *   provided, in which case that will be inserted in place of this
+   *   specified message.
+   * - Recent and search messages will not include messages after this
+   *   message's order.
+   * - If there are already responses on the same order,
+   *   for example, tool calls and responses,
+   *   those will be included automatically.
+   *
+   * Note: if this is provided, no input messages will be saved by default.
+   */
+  promptMessageId?: string | undefined;
+  /**
+   * The model to use for the LLM calls. This will override the languageModel
+   * specified in the Agent config.
+   */
+  model?: LanguageModel;
+};
 
 export type Config = {
   /**
@@ -295,7 +331,7 @@ export type RawRequestResponseHandler = (
   },
 ) => void | Promise<void>;
 
-export type AgentComponent = UseApi<Mounts>;
+export type AgentComponent = UseApi<typeof api>;
 
 export type TextArgs<
   AgentTools extends ToolSet,
@@ -310,31 +346,14 @@ export type TextArgs<
       OUTPUT_PARTIAL
     >
   >[0],
-  "toolChoice" | "tools" | "model"
+  "model" | "prompt" | "messages"
 > & {
-  /**
-   * If provided, this message will be used as the "prompt" for the LLM call,
-   * instead of the prompt or messages.
-   * This is useful if you want to first save a user message, then use it as
-   * the prompt for the LLM call in another call.
-   */
-  promptMessageId?: string;
-  /**
-   * The model to use for the LLM calls. This will override the model specified
-   * in the Agent constructor.
-   */
-  model?: LanguageModel;
   /**
    * The tools to use for the tool calls. This will override tools specified
    * in the Agent constructor or createThread / continueThread.
    */
   tools?: TOOLS;
-  /**
-   * The tool choice to use for the tool calls. This must be one of the tools
-   * specified in the tools array. e.g. {toolName: "getWeather", type: "tool"}
-   */
-  toolChoice?: ToolChoice<TOOLS extends undefined ? AgentTools : TOOLS>;
-};
+} & AgentPrompt;
 
 export type StreamingTextArgs<
   AgentTools extends ToolSet,
@@ -349,147 +368,50 @@ export type StreamingTextArgs<
       OUTPUT_PARTIAL
     >
   >[0],
-  "toolChoice" | "tools" | "model"
+  "model" | "prompt" | "messages"
 > & {
-  /**
-   * If provided, this message will be used as the "prompt" for the LLM call,
-   * instead of the prompt or messages.
-   * This is useful if you want to first save a user message, then use it as
-   * the prompt for the LLM call in another call.
-   */
-  promptMessageId?: string;
-  /**
-   * The model to use for the tool calls. This will override the model specified
-   * in the Agent constructor.
-   */
-  model?: LanguageModel;
   /**
    * The tools to use for the tool calls. This will override tools specified
    * in the Agent constructor or createThread / continueThread.
    */
   tools?: TOOLS;
-  /**
-   * The tool choice to use for the tool calls. This must be one of the tools
-   * specified in the tools array. e.g. {toolName: "getWeather", type: "tool"}
-   */
-  toolChoice?: ToolChoice<TOOLS extends undefined ? AgentTools : TOOLS>;
-};
+} & AgentPrompt;
 
 export type ObjectMode = "object" | "array" | "enum" | "no-schema";
-export type ObjectSchema = z3.Schema | z4.core.$ZodType | Schema;
-export type DefaultObjectSchema = z4.core.$ZodType<JSONValue>;
 
-/**
- * Due to some issues with the type inference of the ai sdk, we need to
- * manually type the arguments for the generateObject function.
- * This is a workaround to allow the model to be optional.
- */
 export type GenerateObjectArgs<
-  SCHEMA extends ObjectSchema = DefaultObjectSchema,
+  SCHEMA extends FlexibleSchema<unknown> = FlexibleSchema<JSONValue>,
   OUTPUT extends ObjectMode = InferSchema<SCHEMA> extends string
     ? "enum"
     : "object",
   RESULT = OUTPUT extends "array"
     ? Array<InferSchema<SCHEMA>>
     : InferSchema<SCHEMA>,
-> = Omit<CallSettings, "stopSequences"> &
-  Partial<Prompt> & {
-    /**
-     * If provided, this message will be used as the "prompt" for the LLM call,
-     * instead of the prompt or messages.
-     * This is useful if you want to first save a user message, then use it as
-     * the prompt for the LLM call in another call.
-     */
-    promptMessageId?: string;
-  } & (OUTPUT extends "enum"
-    ? {
-        /**
-The enum values that the model should use.
-*/
-        enum: Array<RESULT>;
-        mode?: "json";
-        output: "enum";
-      }
-    : OUTPUT extends "no-schema"
-      ? // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-        {}
-      : {
-          /**
-The schema of the object that the model should generate.
-*/
-          schema: SCHEMA;
-          /**
-Optional name of the output that should be generated.
-Used by some providers for additional LLM guidance, e.g.
-via tool or schema name.
-*/
-          schemaName?: string;
-          /**
-Optional description of the output that should be generated.
-Used by some providers for additional LLM guidance, e.g.
-via tool or schema description.
-*/
-          schemaDescription?: string;
-          /**
-The mode to use for object generation.
-
-The schema is converted into a JSON schema and used in one of the following ways
-
-- 'auto': The provider will choose the best mode for the model.
-- 'tool': A tool with the JSON schema as parameters is provided and the provider is instructed to use it.
-- 'json': The JSON schema and an instruction are injected into the prompt. If the provider supports JSON mode, it is enabled. If the provider supports JSON grammars, the grammar is used.
-
-Please note that most providers do not support all modes.
-
-Default and recommended: 'auto' (best mode for the model).
-*/
-          mode?: "auto" | "json" | "tool";
-        }) & {
-    output?: OUTPUT;
-    /**
-The language model to use.
-   */
-    model?: LanguageModel;
-    /**
-A function that attempts to repair the raw output of the model
-to enable JSON parsing.
-   */
-    experimental_repairText?: RepairTextFunction;
-    /**
-Optional telemetry configuration (experimental).
-     */
-    experimental_telemetry?: TelemetrySettings;
-    /**
-Custom download function to use for URLs.
-
-By default, files are downloaded if the model does not support the URL for the given media type.
-     */
-    experimental_download?: Experimental_DownloadFunction | undefined;
-    /**
-Additional provider-specific options. They are passed through
-to the provider from the AI SDK and enable provider-specific
-functionality that can be fully encapsulated in the provider.
-*/
-    providerOptions?: ProviderOptions;
-    /**
-     * Internal. For test use only. May change without notice.
-     */
-    _internal?: { generateId?: () => string; currentDate?: () => Date };
+> = AgentPrompt &
+  Omit<
+    Parameters<typeof generateObject<SCHEMA, OUTPUT, RESULT>>[0],
+    "model" | "prompt" | "messages"
+  > & {
+    schema?: SCHEMA;
+    enum?: Array<RESULT>;
   };
 
 export type StreamObjectArgs<
-  SCHEMA extends ObjectSchema = DefaultObjectSchema,
+  SCHEMA extends FlexibleSchema<unknown> = FlexibleSchema<JSONValue>,
   OUTPUT extends ObjectMode = InferSchema<SCHEMA> extends string
     ? "enum"
     : "object",
   RESULT = OUTPUT extends "array"
     ? Array<InferSchema<SCHEMA>>
     : InferSchema<SCHEMA>,
-> = GenerateObjectArgs<SCHEMA, OUTPUT, RESULT> &
-  Pick<
+> = AgentPrompt &
+  Omit<
     Parameters<typeof streamObject<SCHEMA, OUTPUT, RESULT>>[0],
-    "onError" | "onFinish" | "_internal"
-  >;
+    "model" | "prompt" | "messages"
+  > & {
+    schema?: SCHEMA;
+    enum?: Array<RESULT>;
+  };
 
 export type MaybeCustomCtx<
   CustomCtx,
@@ -561,20 +483,13 @@ export interface Thread<DefaultTools extends ToolSet> {
     OUTPUT = never,
     OUTPUT_PARTIAL = never,
   >(
-    generateTextArgs: TextArgs<
-      TOOLS extends undefined ? DefaultTools : TOOLS,
-      TOOLS,
-      OUTPUT,
-      OUTPUT_PARTIAL
-    > & {
-      /**
-       * If provided, this message will be used as the "prompt" for the LLM call,
-       * instead of the prompt or messages.
-       * This is useful if you want to first save a user message, then use it as
-       * the prompt for the LLM call in another call.
-       */
-      promptMessageId?: string;
-    },
+    generateTextArgs: AgentPrompt &
+      TextArgs<
+        TOOLS extends undefined ? DefaultTools : TOOLS,
+        TOOLS,
+        OUTPUT,
+        OUTPUT_PARTIAL
+      >,
     options?: Options,
   ): Promise<
     GenerateTextResult<TOOLS extends undefined ? DefaultTools : TOOLS, OUTPUT> &
@@ -596,20 +511,13 @@ export interface Thread<DefaultTools extends ToolSet> {
     OUTPUT = never,
     PARTIAL_OUTPUT = never,
   >(
-    streamTextArgs: StreamingTextArgs<
-      TOOLS extends undefined ? DefaultTools : TOOLS,
-      TOOLS,
-      OUTPUT,
-      PARTIAL_OUTPUT
-    > & {
-      /**
-       * If provided, this message will be used as the "prompt" for the LLM call,
-       * instead of the prompt or messages.
-       * This is useful if you want to first save a user message, then use it as
-       * the prompt for the LLM call in another call.
-       */
-      promptMessageId?: string;
-    },
+    streamTextArgs: AgentPrompt &
+      StreamingTextArgs<
+        TOOLS extends undefined ? DefaultTools : TOOLS,
+        TOOLS,
+        OUTPUT,
+        PARTIAL_OUTPUT
+      >,
     options?: Options & {
       /**
        * Whether to save incremental data (deltas) from streaming responses.
@@ -641,7 +549,7 @@ export interface Thread<DefaultTools extends ToolSet> {
    * @returns The result of the generateObject function.
    */
   generateObject<
-    SCHEMA extends ObjectSchema = DefaultObjectSchema,
+    SCHEMA extends FlexibleSchema<unknown> = FlexibleSchema<JSONValue>,
     OUTPUT extends ObjectMode = InferSchema<SCHEMA> extends string
       ? "enum"
       : "object",
@@ -649,15 +557,8 @@ export interface Thread<DefaultTools extends ToolSet> {
       ? Array<InferSchema<SCHEMA>>
       : InferSchema<SCHEMA>,
   >(
-    generateObjectArgs: GenerateObjectArgs<SCHEMA, OUTPUT, RESULT> & {
-      /**
-       * If provided, this message will be used as the "prompt" for the LLM call,
-       * instead of the prompt or messages.
-       * This is useful if you want to first save a user message, then use it as
-       * the prompt for the LLM call in another call.
-       */
-      promptMessageId?: string;
-    },
+    generateObjectArgs: AgentPrompt &
+      GenerateObjectArgs<SCHEMA, OUTPUT, RESULT>,
     options?: Options,
   ): Promise<GenerateObjectResult<RESULT> & ThreadOutputMetadata>;
   /**
@@ -671,7 +572,7 @@ export interface Thread<DefaultTools extends ToolSet> {
    * @returns The result of the streamObject function.
    */
   streamObject<
-    SCHEMA extends ObjectSchema = DefaultObjectSchema,
+    SCHEMA extends FlexibleSchema<unknown> = FlexibleSchema<JSONValue>,
     OUTPUT extends ObjectMode = InferSchema<SCHEMA> extends string
       ? "enum"
       : "object",
@@ -682,15 +583,7 @@ export interface Thread<DefaultTools extends ToolSet> {
     /**
      * The same arguments you'd pass to "ai" sdk {@link streamObject}.
      */
-    streamObjectArgs: StreamObjectArgs<SCHEMA, OUTPUT, RESULT> & {
-      /**
-       * If provided, this message will be used as the "prompt" for the LLM call,
-       * instead of the prompt or messages.
-       * This is useful if you want to first save a user message, then use it as
-       * the prompt for the LLM call in another call.
-       */
-      promptMessageId?: string;
-    },
+    streamObjectArgs: AgentPrompt & StreamObjectArgs<SCHEMA, OUTPUT, RESULT>,
     options?: Options,
   ): Promise<
     ReturnType<typeof streamObject<SCHEMA, OUTPUT, RESULT>> &

package/src/component/messages.ts

@@ -93,7 +93,14 @@ export const deleteByOrder = mutation({
     lastOrder: v.optional(v.number()),
     lastStepOrder: v.optional(v.number()),
   }),
-  handler: async (ctx, args) => {
+  handler: async (
+    ctx,
+    args,
+  ): Promise<{
+    isDone: boolean;
+    lastOrder?: number;
+    lastStepOrder?: number;
+  }> => {
     const messages = await orderedMessagesStream(
       ctx,
       args.threadId,
@@ -770,7 +777,14 @@ export const getMessageSearchFields = query({
     embedding: v.optional(v.array(v.number())),
     embeddingModel: v.optional(v.string()),
   }),
-  handler: async (ctx, args) => {
+  handler: async (
+    ctx,
+    args,
+  ): Promise<{
+    text?: string | undefined;
+    embedding?: number[] | undefined;
+    embeddingModel?: string | undefined;
+  }> => {
     const message = await ctx.db.get(args.messageId);
     const text = message?.text;
     let embedding = undefined;

package/src/component/streams.ts

@@ -414,7 +414,14 @@ export const deleteAllStreamsForThreadIdAsync = mutation({
     streamOrder: v.optional(v.number()),
     deltaCursor: v.optional(v.string()),
   }),
-  handler: async (ctx, args) => {
+  handler: async (
+    ctx,
+    args,
+  ): Promise<{
+    isDone: boolean;
+    streamOrder?: number;
+    deltaCursor?: string;
+  }> => {
     const result = await deleteStreamsPageForThreadId(ctx, args);
     if (!result.isDone) {
       await ctx.scheduler.runAfter(

package/src/test.ts

@@ -1,3 +1,17 @@
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
 import schema from "./component/schema.js";
-const modules = import.meta.glob("./**/*.ts");
-export default { schema, modules };
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @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(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "agent",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };