@convex-dev/agent 0.1.7-alpha.2 → 0.1.8-alpha.0

package/src/client/index.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "vitest";
-import { Agent, filterOutOrphanedToolMessages, type MessageDoc } from ".";
+import {
+  Agent,
+  filterOutOrphanedToolMessages,
+  type MessageDoc,
+} from "./index.js";
 import type { DataModelFromSchemaDefinition } from "convex/server";
 import {
   anyApi,
@@ -18,7 +22,8 @@ import { defineSchema } from "convex/server";
 import { MockLanguageModelV1 } from "ai/test";
 import type { LanguageModelV1, LanguageModelV1StreamPart } from "ai";
 import { simulateReadableStream } from "ai";
-import { components, initConvexTest } from "./setup.test";
+import { components, initConvexTest } from "./setup.test.js";
+import { z } from "zod";
 
 const schema = defineSchema({});
 type DataModel = DataModelFromSchemaDefinition<typeof schema>;
@@ -58,6 +63,16 @@ export const createThread = mutation({
   },
 });
 
+export const createThreadMutation = agent.createThreadMutation();
+export const generateObjectAction = agent.asObjectAction({
+  schema: z.object({
+    prompt: z.any().describe("The prompt passed in"),
+  }),
+});
+export const generateTextAction = agent.asTextAction({});
+export const streamTextAction = agent.asTextAction({ stream: true });
+export const saveMessageMutation = agent.asSaveMessagesMutation();
+
 export const createAndGenerate = action({
   args: {},
   handler: async (ctx) => {
@@ -71,11 +86,87 @@ export const createAndGenerate = action({
   },
 });
 
+export const continueThreadAction = action({
+  args: { threadId: v.string(), userId: v.optional(v.string()) },
+  handler: async (ctx, args) => {
+    const { thread } = await agent.continueThread(ctx, args);
+    return { threadId: thread.threadId };
+  },
+});
+
+export const generateTextWithThread = action({
+  args: {
+    threadId: v.string(),
+    userId: v.optional(v.string()),
+    messages: v.array(v.any()),
+    contextOptions: v.optional(v.any()),
+    storageOptions: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const { thread } = await agent.continueThread(ctx, {
+      threadId: args.threadId,
+      userId: args.userId,
+    });
+    const result = await thread.generateText(
+      { messages: args.messages },
+      {
+        contextOptions: args.contextOptions,
+        storageOptions: args.storageOptions,
+      }
+    );
+    return { text: result.text };
+  },
+});
+
+export const generateObjectWithThread = action({
+  args: {
+    threadId: v.string(),
+    userId: v.optional(v.string()),
+    prompt: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const { thread } = await agent.continueThread(ctx, {
+      threadId: args.threadId,
+      userId: args.userId,
+    });
+    const result = await thread.generateObject({
+      prompt: args.prompt,
+      schema: z.object({ prompt: z.any() }),
+    });
+    return { object: result.object };
+  },
+});
+
+export const fetchContextAction = action({
+  args: {
+    userId: v.optional(v.string()),
+    threadId: v.optional(v.string()),
+    messages: v.array(v.any()),
+    contextOptions: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const context = await agent.fetchContextMessages(ctx, {
+      userId: args.userId,
+      threadId: args.threadId,
+      messages: args.messages,
+      contextOptions: args.contextOptions,
+    });
+    return context;
+  },
+});
+
 const testApi: ApiFromModules<{
   fns: {
     createAndGenerate: typeof createAndGenerate;
     createThread: typeof createThread;
     testQuery: typeof testQuery;
+    continueThreadAction: typeof continueThreadAction;
+    generateTextWithThread: typeof generateTextWithThread;
+    generateObjectWithThread: typeof generateObjectWithThread;
+    fetchContextAction: typeof fetchContextAction;
+    generateTextAction: typeof generateTextAction;
+    generateObjectAction: typeof generateObjectAction;
+    saveMessageMutation: typeof saveMessageMutation;
   };
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 }>["fns"] = anyApi["index.test"] as any;
@@ -90,7 +181,7 @@ describe("Agent thick client", () => {
     const t = initConvexTest(schema);
     const result = await t.action(testApi.createAndGenerate, {});
     expect(result).toBeDefined();
-    expect(result).toMatch("This is a sample response");
+    expect(result).toMatch("Hello");
   });
 });
 
@@ -164,12 +255,14 @@ function mockModel(): LanguageModelV1 {
   return new MockLanguageModelV1({
     provider: "mock",
     modelId: "mock",
+    defaultObjectGenerationMode: "json",
+    // supportsStructuredOutputs: true,
     doGenerate: async ({ prompt }) => ({
       finishReason: "stop",
       usage: { completionTokens: 10, promptTokens: 3 },
       logprobs: undefined,
       rawCall: { rawPrompt: null, rawSettings: {} },
-      text: `This is a sample response to ${JSON.stringify(prompt)}`,
+      text: JSON.stringify({ prompt }),
     }),
     doStream: async ({ prompt }) => ({
       stream: simulateReadableStream({
@@ -192,3 +285,177 @@ function mockModel(): LanguageModelV1 {
     }),
   });
 }
+
+describe("Agent option variations and normal behavior", () => {
+  test("Agent can be constructed with minimal options", () => {
+    const a = new Agent(components.agent, { chat: mockModel() });
+    expect(a).toBeInstanceOf(Agent);
+  });
+
+  test("Agent can be constructed with all options", () => {
+    const a = new Agent(components.agent, {
+      name: "full",
+      chat: mockModel(),
+      instructions: "Test instructions",
+      contextOptions: { recentMessages: 5 },
+      storageOptions: { saveMessages: "all" },
+      maxSteps: 2,
+      maxRetries: 1,
+      usageHandler: async () => {},
+      rawRequestResponseHandler: async () => {},
+    });
+    expect(a.options.name).toBe("full");
+  });
+});
+
+describe("Agent thread management", () => {
+  test("createThread returns threadId (mutation context)", async () => {
+    const t = initConvexTest(schema);
+    const { threadId } = await t.run(async (ctx) =>
+      agent.createThread(ctx, { userId: "2" })
+    );
+    expect(threadId).toBeTypeOf("string");
+  });
+
+  test("continueThread returns thread object", async () => {
+    const t = initConvexTest(schema);
+    const { threadId } = await t.run(async (ctx) =>
+      agent.createThread(ctx, { userId: "3" })
+    );
+    const result = await t.action(testApi.continueThreadAction, {
+      threadId,
+      userId: "3",
+    });
+    expect(result.threadId).toBe(threadId);
+  });
+});
+
+describe("Agent message operations", () => {
+  test("saveMessage and saveMessages store messages", async () => {
+    const t = initConvexTest(schema);
+    const { threadId } = await t.run(async (ctx) =>
+      agent.createThread(ctx, { userId: "4" })
+    );
+    const { messageId } = await t.run(async (ctx) =>
+      agent.saveMessage(ctx, {
+        threadId,
+        userId: "4",
+        message: { role: "user", content: "Hello" },
+      })
+    );
+    expect(messageId).toBeTypeOf("string");
+
+    const { lastMessageId, messages } = await t.run(async (ctx) =>
+      agent.saveMessages(ctx, {
+        threadId,
+        userId: "4",
+        messages: [
+          { role: "user", content: "Hi" },
+          { role: "assistant", content: "Hello!" },
+        ],
+      })
+    );
+    expect(messages.length).toBe(2);
+    expect(lastMessageId).toBe(messages[1]._id);
+  });
+});
+
+describe("Agent text/object generation", () => {
+  test("generateText with custom context and storage options", async () => {
+    const t = initConvexTest(schema);
+    const { threadId } = await t.run(async (ctx) =>
+      agent.createThread(ctx, { userId: "5" })
+    );
+    const result = await t.action(testApi.generateTextWithThread, {
+      threadId,
+      userId: "5",
+      messages: [{ role: "user", content: "Test" }],
+      contextOptions: { recentMessages: 1 },
+      storageOptions: { saveMessages: "all" },
+    });
+    expect(result.text).toMatch(/Test/);
+  });
+
+  test("generateObject returns object", async () => {
+    const t = initConvexTest(schema);
+    const { threadId } = await t.run(async (ctx) =>
+      agent.createThread(ctx, { userId: "6" })
+    );
+    const result = await t.action(testApi.generateObjectWithThread, {
+      threadId,
+      userId: "6",
+      prompt: "Object please",
+    });
+    expect(result.object).toBeDefined();
+  });
+});
+
+describe("Agent-generated mutations/actions/queries", () => {
+  test("createThreadMutation works via t.mutation", async () => {
+    const t = initConvexTest(schema);
+    // This test is for the registered mutation, not the agent method
+    const result = await t.mutation(testApi.createThread, {});
+    expect(result.threadId).toBeTypeOf("string");
+  });
+
+  test("asTextAction and asObjectAction work via t.action", async () => {
+    const t = initConvexTest(schema);
+    const { threadId } = await t.run(async (ctx) =>
+      agent.createThread(ctx, { userId: "8" })
+    );
+    const textResult = await t.action(testApi.generateTextAction, {
+      userId: "8",
+      threadId,
+      messages: [{ role: "user", content: "Say hi" }],
+    });
+    expect(textResult.text).toMatch(/Say hi/);
+
+    const objResult = await t.action(testApi.generateObjectAction, {
+      userId: "8",
+      threadId,
+      messages: [{ role: "user", content: "Give object" }],
+    });
+    expect(objResult.object).toBeDefined();
+  });
+
+  test("asSaveMessagesMutation works via t.mutation", async () => {
+    const t = initConvexTest(schema);
+    const { threadId } = await t.run(async (ctx) =>
+      agent.createThread(ctx, { userId: "9" })
+    );
+    const result = await t.mutation(testApi.saveMessageMutation, {
+      threadId,
+      messages: [
+        {
+          message: { role: "user", content: "Saved via mutation" },
+          // add more metadata fields as needed
+        },
+      ],
+    });
+    expect(result.lastMessageId).toBeDefined();
+    expect(result.messageIds.length).toBe(1);
+  });
+});
+
+describe("Agent context and search options", () => {
+  test("fetchContextMessages returns context messages", async () => {
+    const t = initConvexTest(schema);
+    const { threadId } = await t.run(async (ctx) =>
+      agent.createThread(ctx, { userId: "10" })
+    );
+    await t.run(async (ctx) =>
+      agent.saveMessage(ctx, {
+        threadId,
+        userId: "10",
+        message: { role: "user", content: "Context test" },
+      })
+    );
+    const context = await t.action(testApi.fetchContextAction, {
+      userId: "10",
+      threadId,
+      messages: [{ role: "user", content: "Context test" }],
+      contextOptions: { recentMessages: 1 },
+    });
+    expect(context.length).toBeGreaterThan(0);
+  });
+});

package/src/client/streaming.ts

@@ -8,9 +8,9 @@ import type {
   ProviderOptions,
   StreamDelta,
   TextStreamPart,
-} from "../validators";
-import type { AgentComponent, MessageDoc } from "./index";
-import type { RunActionCtx } from "./types";
+} from "../validators.js";
+import type { AgentComponent, MessageDoc } from "./index.js";
+import type { RunActionCtx } from "./types.js";
 
 export type StreamingOptions = {
   /**

package/src/component/apiKeys.ts

@@ -1,5 +1,5 @@
 import { v } from "convex/values";
-import { mutation, query } from "./_generated/server";
+import { mutation, query } from "./_generated/server.js";
 
 export const issue = mutation({
   args: {

package/src/component/streams.ts

@@ -1,15 +1,19 @@
 import { omit, pick } from "convex-helpers";
 import { v } from "convex/values";
-import { type StreamDelta, vStreamDelta, vStreamMessage } from "../validators";
-import { internal } from "./_generated/api";
-import type { Id } from "./_generated/dataModel";
+import {
+  type StreamDelta,
+  vStreamDelta,
+  vStreamMessage,
+} from "../validators.js";
+import { internal } from "./_generated/api.js";
+import type { Id } from "./_generated/dataModel.js";
 import {
   internalMutation,
   mutation,
   type MutationCtx,
   query,
-} from "./_generated/server";
-import schema from "./schema";
+} from "./_generated/server.js";
+import schema from "./schema.js";
 
 const MAX_DELTAS_PER_REQUEST = 1000;
 const MAX_DELTAS_PER_STREAM = 100;

package/src/mapping.test.ts

@@ -6,13 +6,13 @@ import {
   serializeMessage,
   deserializeMessage,
   serializeContent,
-} from "./mapping";
+} from "./mapping.js";
 import { api } from "./component/_generated/api.js";
-import type { AgentComponent, ActionCtx } from "./client/types";
-import { vMessage } from "./validators";
+import type { AgentComponent, ActionCtx } from "./client/types.js";
+import { vMessage } from "./validators.js";
 import fs from "fs";
 import path from "path";
-import type { SerializedContent } from "./mapping";
+import type { SerializedContent } from "./mapping.js";
 import { validate } from "convex-helpers/validators";
 
 const testAssetsDir = path.join(__dirname, "../test-assets");

package/src/mapping.ts

@@ -15,7 +15,7 @@ import {
   type UserContent,
 } from "ai";
 import { assert } from "convex-helpers";
-import type { MessageWithMetadata } from "./validators";
+import type { MessageWithMetadata } from "./validators.js";
 import type { ActionCtx, AgentComponent } from "./client/types.js";
 import type { RunMutationCtx } from "./client/types.js";
 import { MAX_FILE_SIZE, storeFile } from "./client/files.js";

package/src/react/deltas.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect } from "vitest";
-import { mergeDeltas, applyDeltasToStreamMessage } from "./deltas";
-import type { StreamMessage, StreamDelta, TextStreamPart } from "../validators";
+import { mergeDeltas, applyDeltasToStreamMessage } from "./deltas.js";
+import type {
+  StreamMessage,
+  StreamDelta,
+  TextStreamPart,
+} from "../validators.js";
 import { omit } from "convex-helpers";
 
 function makeStreamMessage(
@@ -287,7 +291,17 @@ describe("mergeDeltas", () => {
     expect(messages1.map((m) => omit(m, ["_creationTime"]))).toEqual(
       messages2.map((m) => omit(m, ["_creationTime"]))
     );
-    expect(streams1).toEqual(streams2);
+    expect(
+      streams1.map((s) => ({
+        ...s,
+        messages: s.messages.map((m) => omit(m, ["_creationTime"])),
+      }))
+    ).toEqual(
+      streams2.map((s) => ({
+        ...s,
+        messages: s.messages.map((m) => omit(m, ["_creationTime"])),
+      }))
+    );
     expect(changed1).toBe(changed2);
     // Inputs should remain unchanged
     expect(streamMessages).toEqual([makeStreamMessage(streamId, 8, 0)]);

package/src/react/deltas.ts

@@ -1,13 +1,13 @@
 import type { TextPart, ToolCallPart, ToolResultPart } from "ai";
-import type { MessageDoc } from "../client";
+import type { MessageDoc } from "../client/index.js";
 import type {
   Message,
   StreamDelta,
   StreamMessage,
   TextStreamPart,
-} from "../validators";
-import type { UIMessage } from "./toUIMessages";
-import { toUIMessages } from "./toUIMessages";
+} from "../validators.js";
+import type { UIMessage } from "./toUIMessages.js";
+import { toUIMessages } from "./toUIMessages.js";
 
 export { toUIMessages, type UIMessage };
 

package/src/react/index.ts

@@ -6,24 +6,24 @@ import {
   type UsePaginatedQueryResult,
   useQuery,
 } from "convex/react";
-import { usePaginatedQuery } from "./usePaginatedQuery";
+import { usePaginatedQuery } from "./usePaginatedQuery.js";
 import type { FunctionArgs } from "convex/server";
 import { useMemo, useState } from "react";
-import type { MessageDoc } from "../client";
-import type { SyncStreamsReturnValue } from "../client/types";
-import type { StreamArgs } from "../validators";
-import type { UIMessage } from "./toUIMessages";
-import { toUIMessages } from "./toUIMessages";
-import { mergeDeltas } from "./deltas";
+import type { MessageDoc } from "../client/index.js";
+import type { SyncStreamsReturnValue } from "../client/types.js";
+import type { StreamArgs } from "../validators.js";
+import type { UIMessage } from "./toUIMessages.js";
+import { toUIMessages } from "./toUIMessages.js";
+import { mergeDeltas } from "./deltas.js";
 import type {
   ThreadQuery,
   ThreadStreamQuery,
   ThreadMessagesArgs,
   ThreadMessagesResult,
-} from "./types";
+} from "./types.js";
 
-export { optimisticallySendMessage } from "./optimisticallySendMessage";
-export { useSmoothText } from "./useSmoothText";
+export { optimisticallySendMessage } from "./optimisticallySendMessage.js";
+export { useSmoothText } from "./useSmoothText.js";
 export { toUIMessages, type UIMessage };
 
 /**

package/src/react/optimisticallySendMessage.ts

@@ -1,7 +1,7 @@
 import { insertAtTop } from "convex/react";
-import type { MessageDoc } from "../client";
+import type { MessageDoc } from "../client/index.js";
 import type { OptimisticLocalStore } from "convex/browser";
-import type { ThreadQuery } from "./types";
+import type { ThreadQuery } from "./types.js";
 
 export function optimisticallySendMessage(
   query: ThreadQuery<unknown, MessageDoc>

package/src/react/toUIMessages.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
-import { toUIMessages } from "./toUIMessages";
-import type { MessageDoc } from "../client";
+import { toUIMessages } from "./toUIMessages.js";
+import type { MessageDoc } from "../client/index.js";
 
 // Helper to create a base message doc
 function baseMessageDoc(overrides: Partial<MessageDoc> = {}): MessageDoc {
@@ -93,12 +93,6 @@ describe("toUIMessages", () => {
           ],
         },
         tool: true,
-        files: [
-          {
-            mimeType: "text/plain",
-            data: "asdfasdfasdf",
-          },
-        ],
         reasoning: "I'm thinking...",
         text: "I'm thinking...",
       }),

package/src/react/toUIMessages.ts

@@ -1,8 +1,8 @@
 import type { ToolInvocationUIPart } from "@ai-sdk/ui-utils";
 import type { UIMessage as AIUIMessage } from "ai";
-import type { MessageDoc } from "../client";
-import { deserializeMessage, toUIFilePart } from "../mapping";
-import type { MessageStatus } from "../validators";
+import type { MessageDoc } from "../client/index.js";
+import { deserializeMessage, toUIFilePart } from "../mapping.js";
+import type { MessageStatus } from "../validators.js";
 
 export type UIMessage = AIUIMessage & {
   key: string;

package/src/react/usePaginatedQuery.ts

@@ -279,7 +279,6 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
       allItems.push(...currResult.page);
     }
     return [allItems, currResult];
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     resultsObject,
     currState.pageKeys,

package/src/shared.ts

@@ -1,5 +1,5 @@
 import type { CoreMessage } from "ai";
-import type { Message } from "./validators";
+import type { Message } from "./validators.js";
 
 export const DEFAULT_RECENT_MESSAGES = 100;
 

package/src/validators.test.ts

@@ -16,9 +16,9 @@ import type {
 } from "ai";
 import type { Infer } from "convex/values";
 import { expectTypeOf, test } from "vitest";
-import type { ContextOptions, StorageOptions } from "./client";
-import type { SerializeUrlsAndUint8Arrays } from "./mapping";
-import type { TextStreamPart } from "./validators";
+import type { ContextOptions, StorageOptions } from "./client/types.js";
+import type { SerializeUrlsAndUint8Arrays } from "./mapping.js";
+import type { TextStreamPart } from "./validators.js";
 import {
   vAssistantContent,
   vAssistantMessage,
@@ -36,7 +36,7 @@ import {
   vToolMessage,
   vUserContent,
   vUserMessage,
-} from "./validators";
+} from "./validators.js";
 
 // type assertion
 type OurUserContent = SerializeUrlsAndUint8Arrays<UserContent>;

package/src/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "edge-runtime",
+  },
+});