Exposes the triggers instance from the agent package

example/convex/_generated/api.d.ts

@@ -2559,7 +2559,6 @@ export declare const components: {
         "internal",
         {
           agentName?: string;
-          format?: "UIMessageChunk" | "TextStreamPart";
           model?: string;
           order: number;
           provider?: string;
@@ -2624,7 +2623,6 @@ export declare const components: {
         },
         Array<{
           agentName?: string;
-          format?: "UIMessageChunk" | "TextStreamPart";
           model?: string;
           order: number;
           provider?: string;

example/convex/chat/basic.ts

@@ -1,12 +1,18 @@
 // See the docs at https://docs.convex.dev/agents/messages
 import { components, internal } from "../_generated/api";
 import { action, internalAction, mutation, query } from "../_generated/server";
+import { triggers } from "@convex-dev/agent";
 import { listMessages, saveMessage } from "@convex-dev/agent";
 import { v } from "convex/values";
 import { agent } from "../agents/simple";
 import { authorizeThreadAccess } from "../threads";
 import { paginationOptsValidator } from "convex/server";
 
+triggers.register('messages', async (ctx, change) => {
+  console.log('[example/chat/basic] trigger fired', change.operation, change.id);
+});
+
+
 /**
  * OPTION 1 (BASIC):
  * Generating via a single action call

package.json

@@ -62,6 +62,11 @@
       "@convex-dev/component-source": "./src/component/convex.config.ts",
       "types": "./dist/component/convex.config.d.ts",
       "default": "./dist/component/convex.config.js"
+    },
+    "./triggers": {
+      "@convex-dev/component-source": "./src/component/triggers.ts",
+      "types": "./dist/component/triggers.d.ts",
+      "default": "./dist/component/triggers.js"
     }
   },
   "peerDependencies": {

src/client/index.ts

@@ -185,6 +185,7 @@ export type {
   Thread,
   UsageHandler,
 };
+export { triggers } from "../component/triggers.js";
 
 export class Agent<
   /**
@@ -1670,3 +1671,4 @@ function errorToString(error: unknown): string {
   }
   return String(error);
 }
+

src/component/_generated/api.d.ts

@@ -13,6 +13,7 @@ import type * as files from "../files.js";
 import type * as messages from "../messages.js";
 import type * as streams from "../streams.js";
 import type * as threads from "../threads.js";
+import type * as triggers from "../triggers.js";
 import type * as users from "../users.js";
 import type * as vector_index from "../vector/index.js";
 import type * as vector_tables from "../vector/tables.js";
@@ -37,6 +38,7 @@ declare const fullApi: ApiFromModules<{
   messages: typeof messages;
   streams: typeof streams;
   threads: typeof threads;
+  triggers: typeof triggers;
   users: typeof users;
   "vector/index": typeof vector_index;
   "vector/tables": typeof vector_tables;

src/component/apiKeys.ts

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

src/component/convex.config.ts

@@ -1,3 +1,3 @@
 import { defineComponent } from "convex/server";
 
-export default defineComponent("agent");
+export default defineComponent("agent");

src/component/files.ts

@@ -1,6 +1,7 @@
 import { paginator } from "convex-helpers/server/pagination";
 import type { Id } from "./_generated/dataModel.js";
-import { mutation, type MutationCtx, query } from "./_generated/server.js";
+import { mutation } from "./triggers.js";
+import { query, type MutationCtx } from "./_generated/server.js";
 import { schema, v } from "./schema.js";
 import { paginationOptsValidator } from "convex/server";
 import type { Infer } from "convex/values";

src/component/messages.ts

@@ -23,13 +23,9 @@ import {
 import { api, internal } from "./_generated/api.js";
 import type { Doc, Id } from "./_generated/dataModel.js";
 import {
-  action,
-  internalQuery,
-  mutation,
-  type MutationCtx,
-  query,
-  type QueryCtx,
-} from "./_generated/server.js";
+  mutation
+} from "./triggers.js";
+import { action, internalQuery, type MutationCtx, query, type QueryCtx } from "./_generated/server.js";
 import { schema, v } from "./schema.js";
 import { insertVector, searchVectors } from "./vector/index.js";
 import {
@@ -288,7 +284,7 @@ async function addMessagesHandler(
     if (message.fileIds) {
       await changeRefcount(ctx, [], message.fileIds);
     }
-    // TODO: delete the associated stream data for the order/stepOrder
+        // TODO: delete the associated stream data for the order/stepOrder
     toReturn.push((await ctx.db.get(messageId))!);
   }
   return { messages: toReturn.map(publicMessage) };

src/component/streams.ts

@@ -8,13 +8,8 @@ import {
 } from "../validators.js";
 import { api, internal } from "./_generated/api.js";
 import type { Doc, Id } from "./_generated/dataModel.js";
-import {
-  internalMutation,
-  mutation,
-  type MutationCtx,
-  query,
-  action,
-} from "./_generated/server.js";
+import { mutation, internalMutation } from "./triggers.js";
+import { action, type MutationCtx, query } from "./_generated/server.js";
 import schema from "./schema.js";
 import { stream } from "convex-helpers/server/stream";
 import { mergedStream } from "convex-helpers/server/stream";

src/component/threads.ts

@@ -9,11 +9,10 @@ import { api, internal } from "./_generated/api.js";
 import type { Doc } from "./_generated/dataModel.js";
 import {
   action,
-  internalMutation,
-  mutation,
-  type MutationCtx,
   query,
+  type MutationCtx,
 } from "./_generated/server.js";
+import { mutation, internalMutation } from "./triggers.js";
 import { deleteMessage } from "./messages.js";
 import { schema, v } from "./schema.js";
 import { deleteStreamsPageForThreadId } from "./streams.js";

src/component/triggers.ts

@@ -0,0 +1,23 @@
+/* eslint-disable no-restricted-imports */
+import { mutation as rawMutation, internalMutation as rawInternalMutation } from "./_generated/server.js";
+/* eslint-enable no-restricted-imports */
+import type { DataModel } from "./_generated/dataModel.js";
+import { Triggers } from "convex-helpers/server/triggers";
+import { customCtx, customMutation } from "convex-helpers/server/customFunctions";
+
+// Simple, canonical trigger setup following convex-helpers docs.
+// Provide a global singleton so importing from different module paths shares registrations.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const triggers: Triggers<DataModel> = new Triggers<DataModel>();
+
+
+// Wrap the built-in mutation builders so that any ctx.db.* write calls fire triggers.
+export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));
+export const internalMutation = customMutation(
+  rawInternalMutation,
+  customCtx(triggers.wrapDB),
+);
+
+// Export the triggers instance so apps can call triggers.register("messages", ...)
+// This is the same instance that wraps the mutations above
+export { triggers };

src/component/users.ts

@@ -6,14 +6,8 @@ import type { ObjectType } from "convex/values";
 import { vPaginationResult } from "../validators.js";
 import { internal } from "./_generated/api.js";
 import type { Id } from "./_generated/dataModel.js";
-import {
-  action,
-  internalMutation,
-  internalQuery,
-  mutation,
-  type MutationCtx,
-  query,
-} from "./_generated/server.js";
+import { mutation, internalMutation } from "./triggers.js";
+import { action, internalQuery, type MutationCtx, query } from "./_generated/server.js";
 import { deleteMessage } from "./messages.js";
 import { deleteStreamsPageForThreadId } from "./streams.js";
 import { schema, v } from "./schema.js";

src/component/vector/index.ts

@@ -2,12 +2,8 @@ import { paginator } from "convex-helpers/server/pagination";
 import { mergedStream, stream } from "convex-helpers/server/stream";
 import { v } from "convex/values";
 import type { Id } from "../_generated/dataModel.js";
-import {
-  type ActionCtx,
-  mutation,
-  type MutationCtx,
-  query,
-} from "../_generated/server.js";
+import { mutation } from "../triggers.js";
+import { query, type ActionCtx, type MutationCtx } from "../_generated/server.js";
 import schema from "../schema.js";
 import {
   type EmbeddingsWithoutDenormalizedFields,