@convex-dev/agent 0.1.6-alpha.1 → 0.1.7-alpha.0

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/agent/issues"
   },
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.7-alpha.0",
   "license": "Apache-2.0",
   "keywords": [
     "convex",
@@ -18,16 +18,15 @@
   "type": "module",
   "scripts": {
     "example": "npm run setup && cd example && npm run dev",
-    "dev": "run-p 'build:watch' 'example'",
-    "setup": "npm i && npm run build && cd example && npm i",
+    "dev": "run-p 'example' 'build:watch'",
+    "setup": "node setup.cjs",
     "build": "npm run build:esm && npm run build:cjs",
     "build:watch": "cd src && npx chokidar '../tsconfig.json' '*.ts' 'react/**/*.ts' 'component/**/*.ts' 'client/**/*.ts' -c 'npm run build' --initial",
     "build:esm": "tsc --project ./esm.json && npm run copy:dts:esm && echo '{\\n  \"type\": \"module\"\\n}' > dist/esm/package.json",
     "build:cjs": "tsc --project ./commonjs.json && npm run copy:dts:cjs && echo '{\\n  \"type\": \"commonjs\"\\n}' > dist/commonjs/package.json",
-    "copy:dts:esm": "rsync -a --include='*/' --include='*.d.ts' --exclude='*' src/ dist/esm/",
-    "copy:dts:cjs": "rsync -a --include='*/' --include='*.d.ts' --exclude='*' src/ dist/commonjs/",
+    "copy:dts:esm": "cpy 'src/**/*.d.ts' 'dist/esm/' --parents",
+    "copy:dts:cjs": "cpy 'src/**/*.d.ts' 'dist/commonjs/' --parents",
     "typecheck": "tsc --noEmit",
-    "prepare": "npm run build",
     "prepack": "node node10stubs.mjs",
     "postpack": "node node10stubs.mjs --cleanup",
     "alpha": "rm -rf dist && npm run build && npm run test && npm version prerelease --preid alpha && npm publish --tag alpha && git push --tags",
@@ -90,9 +89,9 @@
     }
   },
   "peerDependencies": {
-    "ai": "^4.3.4",
+    "ai": "^4.3.16",
     "convex": "^1.23.0",
-    "convex-helpers": "^0.1.78",
+    "convex-helpers": "^0.1.91",
     "react": "^18.3.1 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -101,12 +100,15 @@
     }
   },
   "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
     "@eslint/js": "^9.9.1",
     "@types/node": "^18.19.86",
     "@types/react": "^19.1.1",
     "chokidar-cli": "^3.0.0",
-    "convex-helpers": "^0.1.89",
+    "convex": "^1.24.8",
+    "convex-helpers": "^0.1.92",
     "convex-test": "^0.0.37",
+    "cpy-cli": "^5.0.0",
     "eslint": "^9.24.0",
     "eslint-plugin-jsx-a11y": "^6.8.0",
     "eslint-plugin-react": "^7.34.0",

package/src/client/_generated/_ignore.ts

@@ -0,0 +1 @@
+// This is only here so convex-test can detect a _generated folder

package/src/client/files.ts

@@ -0,0 +1,167 @@
+import type { FilePart, ImagePart } from "ai";
+import type { Id } from "../component/_generated/dataModel.js";
+import type { ActionCtx, AgentComponent, QueryCtx } from "./types.js";
+import type { RunMutationCtx } from "@convex-dev/prosemirror-sync";
+
+export const MAX_FILE_SIZE = 1024 * 64;
+
+type File = {
+  url: string;
+  fileId: string;
+  storageId: Id<"_storage">;
+  hash: string;
+  filename: string | undefined;
+};
+
+/**
+ * Store a file in the file storage and return the URL and fileId.
+ * @param ctx A ctx object from an action.
+ * @param component The agent component.
+ * @param blob The blob to store.
+ * @param filename The filename to store.
+ * @param sha256 The sha256 hash of the file. If not provided, it will be
+ *   computed. However, to ensure no corruption during transfer, you can
+ *   calculate this on the client to enforce integrity.
+ * @returns The URL, fileId, and storageId of the stored file.
+ */
+export async function storeFile(
+  ctx: ActionCtx | RunMutationCtx,
+  component: AgentComponent,
+  blob: Blob,
+  filename?: string,
+  sha256?: string
+): Promise<{
+  file: File;
+  filePart: FilePart;
+  imagePart: ImagePart | undefined;
+}> {
+  if (!("runAction" in ctx)) {
+    throw new Error(
+      "You're trying to save a file that's too large in a mutation. " +
+        "You can store the file in file storage from an action first, then pass a URL instead. " +
+        "To have the agent component track the file, you can use `saveFile` from an action then use the fileId with getFile in the mutation. " +
+        "Read more in the docs."
+    );
+  }
+  const hash =
+    sha256 ||
+    Array.from(
+      new Uint8Array(
+        await crypto.subtle.digest("SHA-256", await blob.arrayBuffer())
+      )
+    )
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  const reused = await ctx.runMutation(component.files.useExistingFile, {
+    hash,
+    filename,
+  });
+  if (reused) {
+    const url = (await ctx.storage.getUrl(reused.storageId))!;
+    return {
+      ...getParts(url, blob.type, filename),
+      file: {
+        url,
+        fileId: reused.fileId,
+        storageId: reused.storageId as Id<"_storage">,
+        hash,
+        filename,
+      },
+    };
+  }
+  const newStorageId = await ctx.storage.store(blob);
+  if (sha256) {
+    const metadata = await ctx.storage.getMetadata(newStorageId);
+    if (metadata?.sha256 !== sha256) {
+      throw new Error("Hash mismatch: " + metadata?.sha256 + " != " + sha256);
+    }
+  }
+  const { fileId, storageId } = await ctx.runMutation(component.files.addFile, {
+    storageId: newStorageId,
+    hash,
+    filename,
+    mimeType: blob.type,
+  });
+  const url = (await ctx.storage.getUrl(storageId as Id<"_storage">))!;
+  if (storageId !== newStorageId) {
+    // We're re-using another file's storageId
+    // Because we try to reuse the file above, this should be very very rare
+    // and only in the case of racing to check then store the file.
+    await ctx.storage.delete(newStorageId);
+  }
+  return {
+    ...getParts(url, blob.type, filename),
+    file: {
+      url,
+      fileId,
+      storageId: storageId as Id<"_storage">,
+      hash,
+      filename,
+    },
+  };
+}
+
+/**
+ * Get file metadata from the component.
+ * This also returns filePart (and imagePart if the file is an image),
+ * which are useful to construct a CoreMessage like
+ * ```ts
+ * const { filePart, imagePart } = await getFile(ctx, components.agent, fileId);
+ * const message: UserMessage = {
+ *   role: "user",
+ *   content: [imagePart ?? filePart],
+ * };
+ * ```
+ * @param ctx A ctx object from an action or query.
+ * @param component The agent component, usually `components.agent`.
+ * @param fileId The fileId of the file to get.
+ * @returns The file metadata and content parts.
+ */
+export async function getFile(
+  ctx: ActionCtx | QueryCtx,
+  component: AgentComponent,
+  fileId: string
+) {
+  const file = await ctx.runQuery(component.files.get, { fileId });
+  if (!file) {
+    throw new Error(`File not found in component: ${fileId}`);
+  }
+  const url = await ctx.storage.getUrl(file.storageId as Id<"_storage">);
+  if (!url) {
+    throw new Error(`File not found in storage: ${file.storageId}`);
+  }
+  return {
+    ...getParts(url, file.mimeType, file.filename),
+    file: {
+      fileId,
+      url,
+      storageId: file.storageId as Id<"_storage">,
+      hash: file.hash,
+      filename: file.filename,
+    },
+  };
+}
+
+function getParts(
+  url: string,
+  mimeType: string,
+  filename: string | undefined
+): {
+  filePart: FilePart;
+  imagePart: ImagePart | undefined;
+} {
+  const filePart: FilePart = {
+    type: "file",
+    data: new URL(url),
+    mimeType,
+    filename,
+  };
+  const imagePart: ImagePart | undefined = mimeType.startsWith("image/")
+    ? {
+        type: "image",
+        image: new URL(url),
+        mimeType,
+      }
+    : undefined;
+  return { filePart, imagePart };
+}

package/src/client/index.test.ts

@@ -1,5 +1,98 @@
 import { describe, expect, test } from "vitest";
-import { filterOutOrphanedToolMessages, type MessageDoc } from ".";
+import { Agent, filterOutOrphanedToolMessages, type MessageDoc } from ".";
+import type { DataModelFromSchemaDefinition } from "convex/server";
+import {
+  anyApi,
+  queryGeneric,
+  mutationGeneric,
+  actionGeneric,
+} from "convex/server";
+import type {
+  ApiFromModules,
+  ActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+} from "convex/server";
+import { v } from "convex/values";
+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";
+
+const schema = defineSchema({});
+type DataModel = DataModelFromSchemaDefinition<typeof schema>;
+// type DatabaseReader = GenericDatabaseReader<DataModel>;
+const query = queryGeneric as QueryBuilder<DataModel, "public">;
+const mutation = mutationGeneric as MutationBuilder<DataModel, "public">;
+const action = actionGeneric as ActionBuilder<DataModel, "public">;
+
+const agent = new Agent(components.agent, {
+  name: "test",
+  instructions: "You are a test agent",
+  // TODO: get mock model that works in v8
+  chat: mockModel(),
+});
+
+export const testQuery = query({
+  args: { threadId: v.string() },
+  handler: async (ctx, args) => {
+    return await agent.listMessages(ctx, {
+      threadId: args.threadId,
+      paginationOpts: {
+        cursor: null,
+        numItems: 10,
+      },
+      excludeToolMessages: true,
+      statuses: ["success"],
+    });
+  },
+});
+
+export const createThread = mutation({
+  args: {},
+  handler: async (ctx) => {
+    return await agent.createThread(ctx, {
+      userId: "1",
+    });
+  },
+});
+
+export const createAndGenerate = action({
+  args: {},
+  handler: async (ctx) => {
+    const { thread } = await agent.createThread(ctx, {
+      userId: "1",
+    });
+    const result = await thread.generateText({
+      messages: [{ role: "user", content: "Hello" }],
+    });
+    return result.text;
+  },
+});
+
+const testApi: ApiFromModules<{
+  fns: {
+    createAndGenerate: typeof createAndGenerate;
+    createThread: typeof createThread;
+    testQuery: typeof testQuery;
+  };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+}>["fns"] = anyApi["index.test"] as any;
+
+describe("Agent thick client", () => {
+  test("should create a thread", async () => {
+    const t = initConvexTest(schema);
+    const result = await t.mutation(testApi.createThread, {});
+    expect(result.threadId).toBeTypeOf("string");
+  });
+  test("should create a thread and generate text", async () => {
+    const t = initConvexTest(schema);
+    const result = await t.action(testApi.createAndGenerate, {});
+    expect(result).toBeDefined();
+    expect(result).toMatch("This is a sample response");
+  });
+});
 
 describe("filterOutOrphanedToolMessages", () => {
   const call1: MessageDoc = {
@@ -66,3 +159,36 @@ describe("filterOutOrphanedToolMessages", () => {
     expect(filterOutOrphanedToolMessages([response1, call2])).toEqual([call2]);
   });
 });
+
+function mockModel(): LanguageModelV1 {
+  return new MockLanguageModelV1({
+    provider: "mock",
+    modelId: "mock",
+    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)}`,
+    }),
+    doStream: async ({ prompt }) => ({
+      stream: simulateReadableStream({
+        chunkDelayInMs: 50,
+        initialDelayInMs: 100,
+        chunks: [
+          {
+            type: "text-delta",
+            textDelta: `This is a sample response to ${JSON.stringify(prompt)}`,
+          },
+          {
+            type: "finish",
+            finishReason: "stop",
+            logprobs: undefined,
+            usage: { completionTokens: 10, promptTokens: 3 },
+          },
+        ] as LanguageModelV1StreamPart[],
+      }),
+      rawCall: { rawPrompt: null, rawSettings: {} },
+    }),
+  });
+}