feat(framework): add @novu/framework/ai-sdk agent plugin fixes NV-8117 (#11656)

Author: ChmaraX

apps/api/src/app/agents/conversation-runtime/reply/agent-reply.controller.ts

@@ -12,18 +12,18 @@ import { HandleAgentReply } from './handle-agent-reply/handle-agent-reply.usecas
 @Controller('/agents')
 @ApiExcludeController()
 export class AgentReplyController {
-  constructor(private handleAgentReplyUsecase: HandleAgentReply) {}
+  constructor(private handleAgentReply: HandleAgentReply) {}
 
   @Post('/:agentId/reply')
   @HttpCode(HttpStatus.OK)
   @RequireAuthentication()
   @ExternalApiAccessible()
-  async handleAgentReply(
+  async handleAgentReplyHandler(
     @UserSession() user: UserSessionData,
     @Param('agentId') agentId: string,
     @Body() body: AgentReplyPayloadDto
   ) {
-    return this.handleAgentReplyUsecase.execute(
+    return this.handleAgentReply.execute(
       HandleAgentReplyCommand.create({
         userId: user._id,
         environmentId: user.environmentId,

packages/framework/ai-sdk/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../dist/cjs/ai-sdk/index.cjs",
+  "types": "../dist/cjs/ai-sdk/index.d.cts"
+}

packages/framework/cards/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../dist/cjs/cards.cjs",
+  "types": "../dist/cjs/cards.d.cts"
+}

packages/framework/package.json

@@ -29,6 +29,8 @@
     "jsx-runtime",
     "jsx-dev-runtime",
     "validators",
+    "ai-sdk",
+    "cards",
     "README.md"
   ],
   "scripts": {
@@ -204,12 +206,33 @@
         "types": "./dist/esm/validators.d.ts",
         "default": "./dist/esm/validators.js"
       }
+    },
+    "./ai-sdk": {
+      "require": {
+        "types": "./dist/cjs/ai-sdk/index.d.cts",
+        "default": "./dist/cjs/ai-sdk/index.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/ai-sdk/index.d.ts",
+        "default": "./dist/esm/ai-sdk/index.js"
+      }
+    },
+    "./cards": {
+      "require": {
+        "types": "./dist/cjs/cards.d.cts",
+        "default": "./dist/cjs/cards.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/cards.d.ts",
+        "default": "./dist/esm/cards.js"
+      }
     }
   },
   "peerDependencies": {
     "@nestjs/common": ">=10.0.0",
     "@sveltejs/kit": ">=1.27.3",
     "@vercel/node": ">=2.15.9",
+    "ai": "^6.0.0",
     "aws-lambda": ">=1.0.7",
     "express": ">=4.19.2",
     "h3": ">=1.8.1",
@@ -242,6 +265,9 @@
     "next": {
       "optional": true
     },
+    "ai": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     },
@@ -260,6 +286,7 @@
     "@types/pluralize": "^0.0.33",
     "@types/sanitize-html": "2.11.0",
     "@vercel/node": "^2.15.9",
+    "ai": "^6.0.208",
     "aws-lambda": "^1.0.7",
     "express": "^4.19.2",
     "h3": "^1.11.1",
@@ -274,11 +301,11 @@
     "zod-to-json-schema": "^3.23.3"
   },
   "dependencies": {
-    "chat": "4.30.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^2.1.1",
     "better-ajv-errors": "^1.2.0",
     "chalk": "^4.1.2",
+    "chat": "4.30.0",
     "cross-fetch": "^4.0.0",
     "json-schema-to-ts": "^3.0.0",
     "jsonrepair": "^3.13.1",

packages/framework/src/ai-sdk/ai-sdk-agent.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { AgentMessageContext } from '../resources/agent/agent.types';
+import { agent } from './ai-sdk-agent';
+import type { AiSdkResult } from './types';
+
+function fakeCtx() {
+  const reply = vi.fn().mockResolvedValue({ messageId: 'm', platformThreadId: 'p' });
+
+  return { reply } as unknown as AgentMessageContext & { reply: ReturnType<typeof vi.fn> };
+}
+
+describe('agent', () => {
+  it('accepts a bare function as onMessage and returns an Agent with the given id', () => {
+    const a = agent('support', async () => 'hi');
+    expect(a.id).toBe('support');
+    expect(typeof a.handlers.onMessage).toBe('function');
+  });
+
+  it('accepts an object of handlers', () => {
+    const a = agent('support', {
+      onMessage: async () => undefined,
+      onAction: async () => undefined,
+    });
+    expect(typeof a.handlers.onMessage).toBe('function');
+    expect(typeof a.handlers.onAction).toBe('function');
+  });
+
+  it('throws when onMessage is missing', () => {
+    // @ts-expect-error intentionally invalid
+    expect(() => agent('support', {})).toThrow(/onMessage/);
+  });
+
+  it('passes through string returns for runtime replyIfPresent', async () => {
+    const supportAgent = agent('support', async () => 'hello');
+    const ctx = fakeCtx();
+
+    const result = await supportAgent.handlers.onMessage({} as never, ctx);
+
+    expect(result).toBe('hello');
+    expect(ctx.reply).not.toHaveBeenCalled();
+  });
+
+  it('auto-delivers AI SDK results and returns void', async () => {
+    const supportAgent = agent('support', async () => ({
+      text: Promise.resolve('model reply'),
+      textStream: (async function* () {})(),
+    }));
+    const ctx = fakeCtx();
+
+    const result = await supportAgent.handlers.onMessage({} as never, ctx);
+
+    expect(result).toBeUndefined();
+    expect(ctx.reply).toHaveBeenCalledWith('model reply');
+  });
+
+  it('auto-delivers generateText-style results', async () => {
+    const supportAgent = agent(
+      'support',
+      async () =>
+        ({
+          text: 'done',
+          steps: [],
+        }) as AiSdkResult
+    );
+    const ctx = fakeCtx();
+
+    await supportAgent.handlers.onMessage({} as never, ctx);
+
+    expect(ctx.reply).toHaveBeenCalledWith('done');
+  });
+});

packages/framework/src/ai-sdk/ai-sdk-agent.ts

@@ -0,0 +1,36 @@
+import { agent as frameworkAgent } from '../resources/agent/agent.resource';
+import type { Agent } from '../resources/agent/agent.types';
+import { deliverResult, isAiSdkResult } from './reply-mapper';
+import type { AiSdkAgentHandlers } from './types';
+
+type AiSdkMessageHandler = AiSdkAgentHandlers['onMessage'];
+
+function normalize(id: string, handlers: AiSdkMessageHandler | AiSdkAgentHandlers): AiSdkAgentHandlers {
+  const normalized = typeof handlers === 'function' ? { onMessage: handlers } : handlers;
+  if (typeof normalized.onMessage !== 'function') {
+    throw new Error(`agent('${id}') requires an onMessage handler`);
+  }
+
+  return normalized;
+}
+
+export function agent(id: string, handlers: AiSdkMessageHandler | AiSdkAgentHandlers): Agent {
+  const h = normalize(id, handlers);
+
+  return frameworkAgent(id, {
+    onMessage: async (message, ctx) => {
+      const result = await h.onMessage(message, ctx);
+
+      if (isAiSdkResult(result)) {
+        await deliverResult(result, ctx);
+
+        return;
+      }
+
+      return result;
+    },
+    ...(h.onAction && { onAction: h.onAction }),
+    ...(h.onReaction && { onReaction: h.onReaction }),
+    ...(h.onResolve && { onResolve: h.onResolve }),
+  });
+}

packages/framework/src/ai-sdk/history-mapper.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { toModelMessages } from './history-mapper';
+
+describe('toModelMessages', () => {
+  it('maps agent role to assistant and others to user, in order', () => {
+    const result = toModelMessages([
+      { role: 'user', type: 'message', content: 'hi', createdAt: '1' },
+      { role: 'agent', type: 'message', content: 'hello!', createdAt: '2' },
+    ]);
+
+    expect(result).toEqual([
+      { role: 'user', content: 'hi' },
+      { role: 'assistant', content: 'hello!' },
+    ]);
+  });
+
+  it('maps bridge sender roles (subscriber/agent) to user/assistant', () => {
+    const result = toModelMessages([
+      { role: 'subscriber', type: 'message', content: 'hi', createdAt: '1' },
+      { role: 'agent', type: 'message', content: 'hello!', createdAt: '2' },
+    ]);
+
+    expect(result).toEqual([
+      { role: 'user', content: 'hi' },
+      { role: 'assistant', content: 'hello!' },
+    ]);
+  });
+
+  it('skips system/metadata (signalData) entries', () => {
+    const result = toModelMessages([
+      { role: 'system', type: 'signal', content: '', signalData: { type: 'metadata' }, createdAt: '1' },
+      { role: 'user', type: 'message', content: 'q', createdAt: '2' },
+    ]);
+
+    expect(result).toEqual([{ role: 'user', content: 'q' }]);
+  });
+
+  it('skips signal-type entries and empty content', () => {
+    const result = toModelMessages([
+      { role: 'system', type: 'signal', content: 'Conversation resolved', createdAt: '1' },
+      { role: 'user', type: 'message', content: '   ', createdAt: '2' },
+      { role: 'user', type: 'message', content: 'real question', createdAt: '3' },
+    ]);
+
+    expect(result).toEqual([{ role: 'user', content: 'real question' }]);
+  });
+
+  it('prepends a system message when provided', () => {
+    const result = toModelMessages([], 'You are support.');
+
+    expect(result[0]).toEqual({ role: 'system', content: 'You are support.' });
+  });
+
+  it('prefixes sender name when multiple distinct human senders exist', () => {
+    const result = toModelMessages([
+      { role: 'user', type: 'message', content: 'one', senderName: 'Alice', createdAt: '1' },
+      { role: 'user', type: 'message', content: 'two', senderName: 'Bob', createdAt: '2' },
+    ]);
+
+    expect(result).toEqual([
+      { role: 'user', content: 'Alice: one' },
+      { role: 'user', content: 'Bob: two' },
+    ]);
+  });
+});

packages/framework/src/ai-sdk/history-mapper.ts

@@ -0,0 +1,50 @@
+import type { ModelMessage } from 'ai';
+import type { AgentHistoryEntry } from '../resources/agent/agent.types';
+
+function isAssistantRole(role: string): boolean {
+  return role === 'agent' || role === 'assistant';
+}
+
+function distinctHumanSenders(history: AgentHistoryEntry[]): number {
+  const names = new Set<string>();
+  for (const entry of history) {
+    if (!isAssistantRole(entry.role) && entry.role !== 'system' && entry.senderName) {
+      names.add(entry.senderName);
+    }
+  }
+
+  return names.size;
+}
+
+/**
+ * Map Novu conversation history into AI SDK `ModelMessage[]`.
+ * v1 is text-only: tool-call/tool-result replay from richContent is intentionally
+ * not reconstructed. System/metadata entries (carrying `signalData`) are skipped.
+ *
+ * The current inbound message is already appended to `history` by Novu before the
+ * bridge fires — do not append the handler's `message` arg again.
+ *
+ * TODO: hook up full tool calls and system messages
+ */
+export function toModelMessages(history: AgentHistoryEntry[], system?: string): ModelMessage[] {
+  const messages: ModelMessage[] = [];
+  if (system) {
+    messages.push({ role: 'system', content: system });
+  }
+
+  const multiSender = distinctHumanSenders(history) > 1;
+
+  for (const entry of history) {
+    if (entry.signalData || entry.role === 'system' || entry.type === 'signal' || !entry.content.trim()) {
+      continue;
+    }
+
+    const isAssistant = isAssistantRole(entry.role);
+    const text =
+      !isAssistant && multiSender && entry.senderName ? `${entry.senderName}: ${entry.content}` : entry.content;
+
+    messages.push({ role: isAssistant ? 'assistant' : 'user', content: text });
+  }
+
+  return messages;
+}

packages/framework/src/ai-sdk/index.ts

@@ -0,0 +1,3 @@
+export { agent } from './ai-sdk-agent';
+export { toModelMessages } from './history-mapper';
+export type { AiSdkAgentHandlers, AiSdkResult } from './types';