refactor(framework,api): align agent handler + bridge wire on positional (entity, ctx) and action.id (fixes NV-7619)

apps/api/src/app/agents/e2e/mock-agent-handler.ts

@@ -39,7 +39,7 @@ if (!NOVU_SECRET_KEY) {
 }
 
 const echoBot = agent('novu-agent', {
-  onMessage: async ({ message, ctx }) => {
+  onMessage: async (message, ctx) => {
     console.log('\n─────────────────────────────────────────');
     console.log(`[onMessage] from ${ctx.subscriber?.firstName ?? 'unknown'} on ${ctx.platform}`);
     console.log(`Message: ${message.text ?? '(none)'}`);
@@ -128,12 +128,12 @@ const echoBot = agent('novu-agent', {
     await ctx.reply(`Echo: ${userText}`);
   },
 
-  onAction: async ({ actionId, value, ctx }) => {
+  onAction: async (action, ctx) => {
     console.log('\n─────────────────────────────────────────');
-    console.log(`[onAction] action: ${actionId} = ${value ?? '(no value)'}`);
+    console.log(`[onAction] action: ${action.id} = ${action.value ?? '(no value)'}`);
     console.log('─────────────────────────────────────────');
 
-    if (actionId === 'ack') {
+    if (action.id === 'ack') {
       await ctx.reply(
         Card({
           title: 'Incident Acknowledged',
@@ -145,21 +145,21 @@ const echoBot = agent('novu-agent', {
           ],
         })
       );
-    } else if (actionId === 'resolve') {
+    } else if (action.id === 'resolve') {
       ctx.resolve('Incident resolved via action');
       await ctx.reply(`Incident resolved by *${ctx.subscriber?.firstName ?? 'unknown'}*.`);
-    } else if (actionId === 'assign') {
-      await ctx.reply(`On-call assignment updated to *${value}*.`);
-    } else if (actionId === 'escalate') {
+    } else if (action.id === 'assign') {
+      await ctx.reply(`On-call assignment updated to *${action.value}*.`);
+    } else if (action.id === 'escalate') {
       await ctx.reply(
         `**Escalated** — paging the secondary on-call team.\n\n_Triggered by ${ctx.subscriber?.firstName ?? 'unknown'}_`
       );
     } else {
-      await ctx.reply(`Got action: *${actionId}*${value ? ` = ${value}` : ''}`);
+      await ctx.reply(`Got action: *${action.id}*${action.value ? ` = ${action.value}` : ''}`);
     }
   },
 
-  onResolve: async ({ ctx }) => {
+  onResolve: async (ctx) => {
     console.log(`\n[onResolve] Conversation ${ctx.conversation.identifier} closed.`);
     ctx.metadata.set('resolvedAt', new Date().toISOString());
   },

apps/api/src/app/agents/services/agent-inbound-handler.service.ts

@@ -497,7 +497,7 @@ export class AgentInboundHandler {
       participantId,
       participantType,
       platformUserId: userId,
-      firstMessageText: `[action:${action.actionId}]`,
+      firstMessageText: `[action:${action.id}]`,
     });
 
     const serializedThread = thread.toJSON() as unknown as Record<string, unknown>;
@@ -517,7 +517,7 @@ export class AgentInboundHandler {
       integrationIdentifier: config.integrationIdentifier,
       platform: config.platform,
       conversationId: conversation._id,
-      actionId: action.actionId,
+      actionId: action.id,
     });
 
     const [subscriber, history] = await Promise.all([

apps/api/src/app/agents/services/bridge-executor.service.ts

@@ -238,7 +238,7 @@ export class BridgeExecutorService {
     if (message?.id) {
       deliveryId = `${conversation._id}:${message.id}`;
     } else if (action) {
-      deliveryId = `${conversation._id}:${event}:${action.actionId}:${timestamp}`;
+      deliveryId = `${conversation._id}:${event}:${action.id}:${timestamp}`;
     } else if (reaction) {
       deliveryId = `${conversation._id}:${event}:${reaction.messageId}:${timestamp}`;
     } else {

apps/api/src/app/agents/services/chat-sdk.service.ts

@@ -1080,7 +1080,7 @@ export class ChatSdkService implements OnModuleDestroy {
           cached.config,
           event.thread as Thread,
           {
-            actionId: event.actionId,
+            id: event.actionId,
             value: event.value,
             sourceMessageId: event.messageId,
           },

packages/framework/src/handler.ts

@@ -323,41 +323,21 @@ export class NovuRequestHandler<Input extends any[] = any[], Output = any> {
 
     switch (event) {
       case AgentEventEnum.ON_MESSAGE:
-        await replyIfPresent(
-          await registeredAgent.handlers.onMessage({
-            message: ctx.message!,
-            ctx: ctx as unknown as AgentMessageContext,
-          })
-        );
+        await replyIfPresent(await registeredAgent.handlers.onMessage(ctx.message!, ctx as AgentMessageContext));
         break;
       case AgentEventEnum.ON_ACTION:
         if (registeredAgent.handlers.onAction) {
-          await replyIfPresent(
-            await registeredAgent.handlers.onAction({
-              actionId: ctx.action!.actionId,
-              value: ctx.action!.value,
-              ctx: ctx as unknown as AgentActionContext,
-            })
-          );
+          await replyIfPresent(await registeredAgent.handlers.onAction(ctx.action!, ctx as AgentActionContext));
         }
         break;
       case AgentEventEnum.ON_REACTION:
         if (registeredAgent.handlers.onReaction) {
-          await replyIfPresent(
-            await registeredAgent.handlers.onReaction({
-              reaction: ctx.reaction!,
-              ctx: ctx as unknown as AgentReactionContext,
-            })
-          );
+          await replyIfPresent(await registeredAgent.handlers.onReaction(ctx.reaction!, ctx as AgentReactionContext));
         }
         break;
       case AgentEventEnum.ON_RESOLVE:
         if (registeredAgent.handlers.onResolve) {
-          await replyIfPresent(
-            await registeredAgent.handlers.onResolve({
-              ctx: ctx as unknown as AgentResolveContext,
-            })
-          );
+          await replyIfPresent(await registeredAgent.handlers.onResolve(ctx as AgentResolveContext));
         }
         break;
       default:

packages/framework/src/resources/agent/agent.context.ts

@@ -20,6 +20,7 @@ import type {
   Signal,
   TriggerRecipientsPayload,
 } from './agent.types';
+import { AgentEventEnum } from './agent.types';
 
 const MAX_INLINE_FILE_BYTES = 5 * 1024 * 1024;
 const MAX_INLINE_AGGREGATE_FILE_BYTES = 5 * 1024 * 1024;
@@ -247,7 +248,7 @@ class ReplyHandleImpl implements ReplyHandle {
 }
 
 export class AgentContextImpl {
-  readonly event: string;
+  readonly event: AgentEventEnum;
   readonly action: AgentAction | null;
   readonly message: AgentMessage | null;
   readonly reaction: AgentReaction | null;
@@ -276,7 +277,7 @@ export class AgentContextImpl {
   private readonly _poster: ReplyPoster;
 
   constructor(request: AgentBridgeRequest, secretKey: string) {
-    this.event = request.event;
+    this.event = request.event as AgentEventEnum;
     this.action = request.action ?? null;
     this.message = request.message;
     this.reaction = request.reaction;