feat(js): add discriminated AgentContext types per handler fixes NV-7509

packages/framework/src/handler.ts

@@ -309,12 +309,12 @@ export class NovuRequestHandler<Input extends any[] = any[], Output = any> {
   }
 
   private async runAgentHandler(registeredAgent: Agent, event: string, ctx: AgentContextImpl): Promise<void> {
-    const handlerMap: Partial<Record<AgentEventEnum, (ctx: AgentContextImpl) => Awaitable<MessageContent | void>>> = {
+    const handlerMap = {
       [AgentEventEnum.ON_MESSAGE]: registeredAgent.handlers.onMessage,
       [AgentEventEnum.ON_REACTION]: registeredAgent.handlers.onReaction,
       [AgentEventEnum.ON_ACTION]: registeredAgent.handlers.onAction,
       [AgentEventEnum.ON_RESOLVE]: registeredAgent.handlers.onResolve,
-    };
+    } as Partial<Record<AgentEventEnum, (ctx: AgentContextImpl) => Awaitable<MessageContent | void>>>;
 
     if (!Object.prototype.hasOwnProperty.call(handlerMap, event)) {
       throw new InvalidActionError(event, AgentEventEnum);

packages/framework/src/index.ts

@@ -4,6 +4,7 @@ export { NovuRequestHandler, type ServeHandlerOptions } from './handler';
 export type {
   Agent,
   AgentAction,
+  AgentActionContext,
   AgentAttachment,
   AgentBridgeRequest,
   AgentContext,
@@ -12,9 +13,12 @@ export type {
   AgentHistoryEntry,
   AgentMessage,
   AgentMessageAuthor,
+  AgentMessageContext,
   AgentPlatformContext,
   AgentReaction,
+  AgentReactionContext,
   AgentReplyPayload,
+  AgentResolveContext,
   AgentSubscriber,
   CardChild,
   CardElement,

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

@@ -5,7 +5,6 @@ import type {
   AddReactionPayload,
   AgentAction,
   AgentBridgeRequest,
-  AgentContext,
   AgentConversation,
   AgentHistoryEntry,
   AgentMessage,
@@ -247,7 +246,7 @@ class ReplyHandleImpl implements ReplyHandle {
   }
 }
 
-export class AgentContextImpl implements AgentContext {
+export class AgentContextImpl {
   readonly event: string;
   readonly action: AgentAction | null;
   readonly message: AgentMessage | null;

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

@@ -1609,4 +1609,5 @@ describe('agent dispatch via NovuRequestHandler', () => {
     expect(JSON.parse(replyCalls[0][1].body).reply.markdown).toBe('Thinking…');
     expect(JSON.parse(replyCalls[1][1].body).reply.markdown).toBe('Final answer');
   });
+
 });

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

@@ -142,11 +142,7 @@ export interface ReplyHandle {
   edit(content: MessageContent, options?: { files?: FileRef[] }): Promise<ReplyHandle>;
 }
 
-export interface AgentContext {
-  readonly event: string;
-  readonly action: AgentAction | null;
-  readonly message: AgentMessage | null;
-  readonly reaction: AgentReaction | null;
+interface AgentContextBase {
   readonly conversation: AgentConversation;
   readonly subscriber: AgentSubscriber | null;
   readonly history: AgentHistoryEntry[];
@@ -207,11 +203,32 @@ export interface AgentContext {
   addReaction(messageId: string, emojiName: Emoji): void;
 }
 
+export interface AgentMessageContext extends AgentContextBase {
+  readonly event: 'onMessage';
+  readonly message: AgentMessage;
+}
+
+export interface AgentActionContext extends AgentContextBase {
+  readonly event: 'onAction';
+  readonly action: AgentAction;
+}
+
+export interface AgentReactionContext extends AgentContextBase {
+  readonly event: 'onReaction';
+  readonly reaction: AgentReaction;
+}
+
+export interface AgentResolveContext extends AgentContextBase {
+  readonly event: 'onResolve';
+}
+
+export type AgentContext = AgentMessageContext | AgentActionContext | AgentReactionContext | AgentResolveContext;
+
 export interface AgentHandlers {
-  onMessage: (ctx: AgentContext) => Awaitable<MessageContent | void>;
-  onReaction?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
-  onAction?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
-  onResolve?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
+  onMessage: (ctx: AgentMessageContext) => Awaitable<MessageContent | void>;
+  onReaction?: (ctx: AgentReactionContext) => Awaitable<MessageContent | void>;
+  onAction?: (ctx: AgentActionContext) => Awaitable<MessageContent | void>;
+  onResolve?: (ctx: AgentResolveContext) => Awaitable<MessageContent | void>;
 }
 
 export interface Agent {

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

@@ -17,6 +17,7 @@ export { agent } from './agent.resource';
 export type {
   Agent,
   AgentAction,
+  AgentActionContext,
   AgentAttachment,
   AgentBridgeRequest,
   AgentContext,
@@ -25,9 +26,12 @@ export type {
   AgentHistoryEntry,
   AgentMessage,
   AgentMessageAuthor,
+  AgentMessageContext,
   AgentPlatformContext,
   AgentReaction,
+  AgentReactionContext,
   AgentReplyPayload,
+  AgentResolveContext,
   AgentSubscriber,
   EditPayload,
   FileRef,