fix(framework): remove duplicate message from AgentMessageContext fixes NV-7544

[djabarovgeorge]

What changed

Removed the message property from the AgentMessageContext interface to eliminate the confusing duplication between payload.message and payload.ctx.message in the onMessage handler.

Previously, the same AgentMessage object was available at both locations:

onMessage: async ({ message, ctx }) => {
  // payload.message === payload.ctx.message (identical)
}

Now message is exclusively available via payload.message (the destructured first argument). The ctx object retains only conversation state, subscriber info, history, platform context, and action methods (reply, resolve, trigger, metadata, addReaction).

Changes

• agent.types.ts — Removed readonly message: AgentMessage from AgentMessageContext interface
• agent.types.ts — Updated AgentHandlers.onMessage JSDoc to clarify payload.message usage
• README-template.md — Updated agent API docs and code example to use payload.message pattern
• agent.test.ts — Updated test to verify message arrives via payload instead of ctx

Breaking changes

• ctx.message is no longer available in onMessage handlers. Use the destructured message from the payload instead:

  // Before
  onMessage: async ({ ctx }) => { ctx.message.text }
  
  // After
  onMessage: async ({ message, ctx }) => { message.text }

Linear Issue: NV-7544

  

What changed

The message property was removed from the AgentMessageContext interface to eliminate duplication where the message was available both as payload.message and payload.ctx.message in onMessage handlers. The message is now accessed only through the destructured payload parameter, while ctx retains conversation state, subscriber information, history, and action methods.

Affected areas

framework: Updated AgentMessageContext type definition and onMessage handler JSDoc to reflect that message comes from the payload parameter, not the context object. Tests were updated to verify the new parameter shape.

documentation: README template examples updated to show the new handler signature pattern—onMessage: async ({ message, ctx }) => { ... }—and updated code snippets to use message.text instead of ctx.message?.text.

Key technical decisions

• Breaking change: ctx.message is no longer available in onMessage handlers. Code must be updated to access the message through the destructured message parameter instead.

Testing

Existing test was updated to verify that the message arrives through the payload parameter rather than the context object.

[linear-code]

NV-7544 agent - remove ctx.message

[netlify]

✅ Deploy Preview for dashboard-v2-novu-staging canceled.

Name	Link
🔨 Latest commit	9a52629
🔍 Latest deploy log	https://app.netlify.com/projects/dashboard-v2-novu-staging/deploys/69fcbe636e184e00083ab316

[coderabbitai]

📝 Walkthrough

Walkthrough

Agent handler typing is clarified: onMessage receives a destructured { message, ctx } payload instead of ctx alone. Type documentation, tests, and README examples are updated consistently to reflect this contract where message contains the incoming message and ctx provides context methods.

Changes

Agent Handler Payload Restructuring

Layer / File(s)	Summary
Handler Contract Documentation packages/framework/src/resources/agent/agent.types.ts	Comment documentation for onMessage handler parameters is updated to describe payload.message (incoming message) and payload.ctx (conversation history, subscriber, metadata, reply/trigger methods).
Test Verification packages/framework/src/resources/agent/agent.test.ts	Test case updates to capture message separately from ctx and assert capturedMessage.text instead of capturedCtx.message?.text.
Documentation & Examples packages/novu/src/commands/init/templates/app-agent/ts/README-template.md	README documentation and code example are updated to show onMessage receiving { message, ctx } and using message.text directly in the LLM prompt.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• novuhq/novu#11003: Both PRs implement the same breaking change to agent handler signatures, switching callbacks to receive destructured payload { message, ctx } with corresponding test and template updates.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title follows Conventional Commits format with valid type 'fix', valid scope 'framework', lowercase imperative description, and ends with the Linear ticket reference 'NV-7544'.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/framework/src/resources/agent/agent.types.ts (1)

273-276: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Breaking change without deprecation violates package guidelines.

Per the PR description, ctx.message is being removed from AgentMessageContext, which is a breaking change to the public framework API. As per coding guidelines, package symbols should be deprecated with @deprecated JSDoc before removal to give consumers a migration window.

Consider a two-phase approach:

1. Current release: Keep ctx.message but mark it @deprecated with a JSDoc comment directing users to destructure message from the payload
2. Next major release: Remove the deprecated property

This provides a smoother migration path and follows established semver conventions for packages.

As per coding guidelines: "Deprecate symbols with @deprecated JSDoc before removing them from packages" and "Treat all exported symbols in packages as public API; follow semver conventions with breaking changes requiring major bumps."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/framework/src/resources/agent/agent.types.ts` around lines 273 -
276, AgentMessageContext currently removes the publicly exported ctx.message
property which is a breaking change; restore the message property on
AgentMessageContext but mark it with an `@deprecated` JSDoc comment pointing
consumers to destructure message from the payload (e.g., "Use payload.message"
or similar), keeping the existing type/signature so consumers continue to
compile; plan to remove the deprecated message property in the next major
release. Ensure the deprecated JSDoc is attached to the message property in the
AgentMessageContext interface so linters and IDEs surface the deprecation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@packages/framework/src/resources/agent/agent.types.ts`:
- Around line 273-276: AgentMessageContext currently removes the publicly
exported ctx.message property which is a breaking change; restore the message
property on AgentMessageContext but mark it with an `@deprecated` JSDoc comment
pointing consumers to destructure message from the payload (e.g., "Use
payload.message" or similar), keeping the existing type/signature so consumers
continue to compile; plan to remove the deprecated message property in the next
major release. Ensure the deprecated JSDoc is attached to the message property
in the AgentMessageContext interface so linters and IDEs surface the
deprecation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1b38ea78-0f48-4e5a-80fd-15d0b9fc053b

📥 Commits

Reviewing files that changed from the base of the PR and between 6a0ed20 and 4a889a5.

📒 Files selected for processing (3)

• packages/framework/src/resources/agent/agent.test.ts
• packages/framework/src/resources/agent/agent.types.ts
• packages/novu/src/commands/init/templates/app-agent/ts/README-template.md