apps/dashboard/src/components/onboarding/managed-runtime-setup-guide.tsx-111-111 (1)

111-111: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add blank line before return statement.

As per coding guidelines, include a blank line before every return statement.

📐 Proposed fix

   if (!isManagedEnabled) {
+
     return null;
   }

As per coding guidelines: Include a blank line before every return statement.

🤖 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 `@apps/dashboard/src/components/onboarding/managed-runtime-setup-guide.tsx` at
line 111, In the ManagedRuntimeSetupGuide component (in
apps/dashboard/src/components/onboarding/managed-runtime-setup-guide.tsx) there
is no blank line before the return statement; insert a single blank line
immediately above the "return null;" statement so the return is separated from
preceding code, preserving the file's coding guideline of a blank line before
every return.

apps/dashboard/src/components/onboarding/managed-runtime-setup-guide.tsx-36-36 (1)

36-36: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Inconsistent null-safety handling.

Line 36 uses a non-null assertion (!), but line 268 uses optional chaining (anthropicProvider?.displayName), suggesting the provider could be undefined. Since the code already has a fallback on line 268, remove the non-null assertion to handle edge cases gracefully.

🛡️ Proposed fix

-const anthropicProvider = AGENT_RUNTIME_PROVIDERS.find((p) => p.providerId === 'anthropic')!;
+const anthropicProvider = AGENT_RUNTIME_PROVIDERS.find((p) => p.providerId === 'anthropic');

🤖 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 `@apps/dashboard/src/components/onboarding/managed-runtime-setup-guide.tsx` at
line 36, The code currently forces anthropicProvider non-null with a "!" when
finding the provider (const anthropicProvider = AGENT_RUNTIME_PROVIDERS.find((p)
=> p.providerId === 'anthropic')!), but other code (e.g.,
anthropicProvider?.displayName) already treats it as potentially undefined;
remove the non-null assertion so the variable is typed as possibly undefined and
update any usages to handle undefined safely (use optional chaining or a
fallback display string) — locate the find call for anthropicProvider and change
it to not assert non-null, then ensure all references to anthropicProvider (like
displayName) use ?. or a default value.

apps/dashboard/src/components/onboarding/managed-runtime-setup-guide.tsx-301-301 (1)

301-301: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add blank line before return statement.

As per coding guidelines, include a blank line before every return statement.

📐 Proposed fix

   const provider = AGENT_RUNTIME_PROVIDERS.find((p) => p.providerId === providerId);

-  if (!provider) return null;
+  if (!provider) {
+
+    return null;
+  }

As per coding guidelines: Include a blank line before every return statement.

🤖 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 `@apps/dashboard/src/components/onboarding/managed-runtime-setup-guide.tsx` at
line 301, The conditional early-return in the ManagedRuntimeSetupGuide component
("if (!provider) return null;") lacks a blank line before the return; update the
conditional to place a blank line immediately before the return statement (e.g.,
convert to a block or separate the return onto its own line) so there is a blank
line preceding every return in the ManagedRuntimeSetupGuide component.

apps/dashboard/src/components/agents/agent-overview-tab.tsx-68-80 (1)

68-80: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Drift modal recreate/unlink are no-ops — users hit a UX dead-end.

Both callbacks just close the modal, so a user surfaced into this flow because of AGENT_RUNTIME_DRIFT has no path forward from this UI; the comments acknowledge the work is deferred but the buttons still appear functional. At minimum, disable/hide the recreate and unlink controls (or render a "coming soon" inline note) until the corresponding endpoints land, so users don't repeatedly trigger no-op clicks and assume the system is broken.

Want me to wire the AgentRuntimeDriftModal to render disabled CTAs with a tooltip explaining the action is pending until the recreate/unlink endpoints ship?

🤖 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 `@apps/dashboard/src/components/agents/agent-overview-tab.tsx` around lines 68
- 80, The recreate/unlink callbacks on AgentRuntimeDriftModal are no-ops and
leave users stuck; update the usage so the modal shows disabled CTAs or a
"coming soon" note instead of active buttons: either pass explicit props (e.g.,
recreateEnabled={false} unlinkEnabled={false} or
comingSoonMessage="Recreate/unlink pending backend support") to
AgentRuntimeDriftModal, or replace the onRecreate/onUnlink handlers with logic
that opens an inline tooltip/alert explaining the action is pending (instead of
just calling setShowDriftModal(false)). Modify the AgentRuntimeDriftModal
invocation here and ensure the modal component (AgentRuntimeDriftModal) uses
those props to render disabled buttons and a tooltip/message so users aren’t
offered functional-looking but no-op controls.

apps/api/src/app/agents/usecases/delete-agent/delete-agent.usecase.ts-34-34 (1)

34-34: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Silent leak path when managedRuntime is missing on a managed agent.

isManagedAgent requires both runtime === 'managed' AND a truthy managedRuntime. If a row has runtime: 'managed' but managedRuntime is somehow absent (provisioning crashed mid-flight, partial restore, manual edit), this branch falls through to the hard-delete path and the local agent is destroyed without ever attempting the external cleanup. Consider explicitly handling that state — e.g., throw a 422/422-equivalent so the caller can retry provisioning, or log+hard-delete deliberately.

-    const isManagedAgent = agent.runtime === 'managed' && agent.managedRuntime;
-
-    if (isManagedAgent) {
+    if (agent.runtime === 'managed') {
+      if (!agent.managedRuntime) {
+        this.logger.warn(
+          { agentId: agent._id },
+          'Managed agent missing managedRuntime metadata; performing local-only delete'
+        );
+      }
+      // Soft-delete: mark as pending external deletion, then clean up provider-side async

🤖 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 `@apps/api/src/app/agents/usecases/delete-agent/delete-agent.usecase.ts` at
line 34, The current check using isManagedAgent (const isManagedAgent =
agent.runtime === 'managed' && agent.managedRuntime) silently falls through to
hard-delete when runtime === 'managed' but managedRuntime is missing; add an
explicit branch that detects agent.runtime === 'managed' &&
!agent.managedRuntime and handle it deterministically (e.g., throw a
422/unprocessable error or log and choose hard-delete) before using
isManagedAgent so callers can retry provisioning or you can record the anomalous
state; update the delete logic in delete-agent.usecase.ts to reference
agent.runtime and agent.managedRuntime directly to implement this explicit
error/decision path.

apps/api/src/app/agents/usecases/get-agent-runtime-config/get-agent-runtime-config.usecase.ts-48-49 (1)

48-49: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Validate apiKey before instantiating the provider.

ProvisionManagedAgent explicitly throws when apiKey is missing (lines 31-33 there), but here a missing/empty key is asserted away with ! and silently passed into getAgentRuntimeProvider, surfacing as an opaque SDK error rather than a clear 422. Mirror the validation for consistency.

-    const decryptedCredentials = decryptCredentials(integration.credentials);
-    const runtimeProvider = getAgentRuntimeProvider(providerId, decryptedCredentials.apiKey!);
+    const decryptedCredentials = decryptCredentials(integration.credentials);
+    if (!decryptedCredentials.apiKey) {
+      throw new UnprocessableEntityException(
+        `Runtime integration for agent "${command.identifier}" has no API key configured.`
+      );
+    }
+    const runtimeProvider = getAgentRuntimeProvider(providerId, decryptedCredentials.apiKey);

🤖 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
`@apps/api/src/app/agents/usecases/get-agent-runtime-config/get-agent-runtime-config.usecase.ts`
around lines 48 - 49, The code calls getAgentRuntimeProvider(providerId,
decryptedCredentials.apiKey!) without validating the apiKey; replicate the
validation used in ProvisionManagedAgent by checking decryptedCredentials.apiKey
(and treating empty string as missing) and throw or return a 422-style error
before calling getAgentRuntimeProvider so missing keys produce a clear
validation error; update the logic around decryptCredentials and the call-site
for getAgentRuntimeProvider to validate apiKey and only pass a non-empty string.

apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.usecase.ts-31-33 (1)

31-33: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use UnprocessableEntityException (not NotFoundException) when the integration lacks an API key.

The integration was found; its configuration is invalid. Returning a 404 here misleads the dashboard's error-to-UI mapping (which already treats 404 as "not found, please re-create") and conflates two distinct failure modes.

-import { Injectable, NotFoundException } from '@nestjs/common';
+import { Injectable, NotFoundException, UnprocessableEntityException } from '@nestjs/common';
...
-    if (!apiKey) {
-      throw new NotFoundException(`Integration "${command.integrationId}" has no API key configured.`);
-    }
+    if (!apiKey) {
+      throw new UnprocessableEntityException(
+        `Integration "${command.integrationId}" has no API key configured.`
+      );
+    }

🤖 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
`@apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.usecase.ts`
around lines 31 - 33, The code currently throws NotFoundException when an
integration exists but has no API key; update the check in
provision-managed-agent.usecase.ts to throw UnprocessableEntityException instead
(keep the existing message or adjust to indicate invalid configuration), and
ensure you import UnprocessableEntityException from `@nestjs/common` and remove
NotFoundException if it becomes unused; update any related tests/handlers
expecting a 404 to expect a 422 for this validation case.

apps/api/src/app/agents/usecases/update-agent-runtime-config/update-agent-runtime-config.usecase.ts-47-48 (1)

47-48: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Same apiKey! non-null assertion as in GetAgentRuntimeConfig.

Apply the same validation suggested for the GET use case here so missing credentials surface as a clean 422 instead of a downstream SDK error.

🤖 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
`@apps/api/src/app/agents/usecases/update-agent-runtime-config/update-agent-runtime-config.usecase.ts`
around lines 47 - 48, The code uses a non-null assertion on
integration.credentials.apiKey when calling getAgentRuntimeProvider in
update-agent-runtime-config.usecase.ts; mirror the GET use case validation by
checking decryptCredentials(integration.credentials) and ensuring apiKey exists
before calling getAgentRuntimeProvider(providerId, apiKey). If apiKey is
missing, throw/return the same 422 validation error used in
GetAgentRuntimeConfig (i.e., produce a clear 422 response rather than letting
the SDK error surface) and remove the trailing `!` on apiKey.

apps/api/src/app/agents/usecases/handle-agent-reply/handle-agent-reply.usecase.ts (1)

42-44: TODO appropriately marks future work for managed agent execution.

The comment clearly defers message-time execution to a future PR. When implementing this, note that the agent entity will need to be fetched earlier in the method (currently fetched at line 149), and the fetch projection must include the runtime and managedRuntime fields (currently only fetches _id, name, identifier at line 155).

Would you like me to open a tracking issue that outlines the implementation prerequisites (early agent fetch, field inclusion, branching logic, runtime provider integration) to make this TODO more actionable for the runtime team?

🤖 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
`@apps/api/src/app/agents/usecases/handle-agent-reply/handle-agent-reply.usecase.ts`
around lines 42 - 44, Update the TODO branch so the code fetches the agent
entity earlier in handle-agent-reply.usecase.ts (before routing logic) and
include the runtime and managedRuntime fields in the query projection in
addition to _id, name, identifier; then add a branch: if (agent.runtime ===
'managed') call the runtime provider via
IAgentRuntimeProvider.runConversationTurn(externalAgentId, userMessage) (passing
the agent.managedRuntime/external id as required) and short-circuit the
self-hosted bridge path, otherwise continue current routing; ensure variable
names match existing symbols (agent, runtime, managedRuntime, externalAgentId,
userMessage, IAgentRuntimeProvider.runConversationTurn).

packages/shared/src/consts/providers/agent-runtime-providers.ts (1)

26-42: ⚡ Quick win

Prefer immutable exported provider collections.

AGENT_RUNTIME_PROVIDERS and AGENT_RUNTIME_PROVIDER_IDS are currently mutable exports. Making these readonly reduces accidental cross-module mutation risk.

Suggested refactor

-export const AGENT_RUNTIME_PROVIDERS: AgentRuntimeProvider[] = [
+export const AGENT_RUNTIME_PROVIDERS: ReadonlyArray<AgentRuntimeProvider> = [
   {
     providerId: AgentRuntimeProviderIdEnum.Anthropic,
     displayName: 'Claude (Anthropic)',
@@
-];
+];
 
-export const AGENT_RUNTIME_PROVIDER_IDS = new Set(AGENT_RUNTIME_PROVIDERS.map((p) => p.providerId));
+export const AGENT_RUNTIME_PROVIDER_IDS: ReadonlySet<AgentRuntimeProviderIdEnum> = new Set(
+  AGENT_RUNTIME_PROVIDERS.map((p) => p.providerId)
+);

As per coding guidelines: “Keep packages/shared free of runtime side-effects since it is imported by both Node.js services and browser bundles.”

🤖 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/shared/src/consts/providers/agent-runtime-providers.ts` around lines
26 - 42, AGENT_RUNTIME_PROVIDERS and AGENT_RUNTIME_PROVIDER_IDS are exported
mutable collections; change them to readonly to prevent cross-module mutation
by: update the type of AGENT_RUNTIME_PROVIDERS to
ReadonlyArray<AgentRuntimeProvider> (or add the `readonly` modifier) and
AGENT_RUNTIME_PROVIDER_IDS to ReadonlySet<AgentRuntimeProviderIdEnum>, and make
the runtime values immutable (e.g., use Object.freeze on the array and its
objects or construct a ReadonlySet) so both the TypeScript types and the runtime
values are immutable; refer to the AGENT_RUNTIME_PROVIDERS and
AGENT_RUNTIME_PROVIDER_IDS symbols to locate and apply these changes.

libs/application-generic/src/agent-runtimes/agent-runtime-capabilities-parity.spec.ts (1)

13-19: ⚡ Quick win

Run this parity check through the real factory and compare the whole capability object.

This helper duplicates provider registration, so agent-runtime.factory.ts can drift without the test noticing. The per-field assertions also miss newly added capability flags. Reusing getAgentRuntimeProvider and asserting instance.capabilities with toEqual closes both gaps.

Suggested refactor

 import { AGENT_RUNTIME_PROVIDERS, AgentRuntimeProviderIdEnum } from '@novu/shared';
-import { createAnthropicProvider } from './anthropic/anthropic-agent-runtime.provider';
+import { getAgentRuntimeProvider } from './agent-runtime.factory';
 import type { IAgentRuntimeProvider } from './i-agent-runtime-provider';
@@
 function getProviderInstance(id: AgentRuntimeProviderIdEnum): IAgentRuntimeProvider {
-  switch (id) {
-    case AgentRuntimeProviderIdEnum.Anthropic:
-      return createAnthropicProvider('test-key');
-    default:
-      throw new Error(`No concrete provider registered for ${id}. Add it to this test.`);
-  }
+  return getAgentRuntimeProvider(id, 'test-key');
 }
@@
-      it('capabilities.mcpServers matches the catalog', () => {
-        expect(instance.capabilities.mcpServers).toBe(catalogEntry.capabilities.mcpServers);
-      });
-
-      it('capabilities.tools matches the catalog', () => {
-        expect(instance.capabilities.tools).toBe(catalogEntry.capabilities.tools);
-      });
-
-      it('capabilities.model matches the catalog', () => {
-        expect(instance.capabilities.model).toBe(catalogEntry.capabilities.model);
-      });
-
-      it('capabilities.systemPrompt matches the catalog', () => {
-        expect(instance.capabilities.systemPrompt).toBe(catalogEntry.capabilities.systemPrompt);
+      it('capabilities match the catalog', () => {
+        expect(instance.capabilities).toEqual(catalogEntry.capabilities);
       });

Also applies to: 35-49

🤖 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
`@libs/application-generic/src/agent-runtimes/agent-runtime-capabilities-parity.spec.ts`
around lines 13 - 19, The test helper getProviderInstance duplicates provider
creation and can drift from the real registry; instead call the real factory
function getAgentRuntimeProvider with AgentRuntimeProviderIdEnum.Anthropic to
obtain the provider instance, then replace the per-field capability assertions
with a single deep equality assertion comparing instance.capabilities to the
expected capability object (use toEqual) so the whole capability shape from
agent-runtime.factory.ts is validated; update the other occurrence (lines 35-49)
similarly to reuse getAgentRuntimeProvider and assert instance.capabilities with
toEqual.

apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.usecase.ts (1)

37-45: 💤 Low value

validateCredentials + createAgent is two upstream calls where one usually suffices.

createAgent will surface 401 just as well as validateCredentials, and you're paying double rate-limit budget for every managed-agent creation. Consider relying on createAgent and mapping its 401 to your AgentRuntimeUnauthorizedError, dropping the explicit pre-flight unless it has a meaningful side benefit (e.g., probing scopes that createAgent doesn't reveal).

🤖 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
`@apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.usecase.ts`
around lines 37 - 45, Remove the redundant pre-flight call to
runtimeProvider.validateCredentials and instead rely on
runtimeProvider.createAgent to surface authorization failures; catch a
401/unauthorized response from createAgent in the provision flow and map it to
AgentRuntimeUnauthorizedError (or rethrow as that type) so we preserve behavior
without the extra upstream call; update the logic in
provision-managed-agent.usecase.ts around the runtimeProvider.createAgent call
(and any surrounding try/catch) to perform this mapping and delete the
validateCredentials invocation.

apps/dashboard/src/components/agents/agent-runtime-config-section.tsx (1)

35-36: 💤 Low value

Type-narrowing nit on the runtime error.

The RuntimeErrorPanel casts error to Record<string, unknown> | null, then accesses err?.code. Since the runtime error utility module already exports typed helpers, exposing a small getRuntimeErrorCode(error: unknown): string from @/utils/agent-runtime-errors and reusing it both here and at lines 110-114 would remove the duplicated as unknown as ladder and centralize the contract. Optional.

🤖 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 `@apps/dashboard/src/components/agents/agent-runtime-config-section.tsx` around
lines 35 - 36, Replace the ad-hoc cast and property access in RuntimeErrorPanel
with a dedicated helper: add or re-export getRuntimeErrorCode(error: unknown):
string in the agent-runtime-errors util and call it from RuntimeErrorPanel
(instead of casting to Record<string, unknown> and reading err?.code) and also
use it where similar logic exists around lines 110-114; this centralizes the
type-narrowing and ensures you return a default code like
'AGENT_RUNTIME_UNKNOWN' from getRuntimeErrorCode when the error shape is
unexpected.

apps/api/src/app/agents/usecases/create-agent/create-agent.usecase.ts (1)

59-66: 💤 Low value

Avoid the extra round-trip; have ProvisionManagedAgent return what's needed.

ProvisionManagedAgent.execute already knows the persisted runtime and managedRuntime values it just wrote. Returning them (or the updated doc) avoids this extra findOne('*'). Optional polish.

🤖 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 `@apps/api/src/app/agents/usecases/create-agent/create-agent.usecase.ts` around
lines 59 - 66, The extra findOne('*') round-trip should be removed by having
ProvisionManagedAgent.execute return the persisted values (either the updated
agent document or at least the runtime and managedRuntime it wrote); update
ProvisionManagedAgent.execute's signature to return those values, change the
caller in create-agent.usecase.ts (the code that currently calls
agentRepository.findOne with _id and '*') to use the returned
runtime/managedRuntime or returned updatedAgent instead, and adjust any related
types/interfaces (and tests) accordingly so no additional repository fetch is
needed.

apps/dashboard/src/components/agents/agent-overview-tab.tsx (1)

21-31: ⚡ Quick win

Extract runtime mode string literal to a named constant in packages/shared.

The string 'managed' is duplicated across 9+ files (agent-overview-tab.tsx, agent-runtime-config-section.tsx, plus create-agent, delete-agent, get-agent-runtime-config, update-agent-runtime-config, and provision-managed-agent files). Introduce a named constant—either an enum like AgentRuntimeMode alongside AgentRuntimeProviderIdEnum, or a const like AGENT_RUNTIME_MODES = { MANAGED: 'managed', SELF_HOSTED: 'self-hosted' } in packages/shared—to prevent silent typos and enable searchability across the codebase.

🤖 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 `@apps/dashboard/src/components/agents/agent-overview-tab.tsx` around lines 21
- 31, The codebase uses the string literal 'managed' in multiple places (e.g.,
the isManagedRuntime check in agent-overview-tab.tsx) which risks typos and
duplication; add a central constant or enum in packages/shared (for example
AgentRuntimeMode or AGENT_RUNTIME_MODES with MANAGED and SELF_HOSTED values),
export it, and replace all occurrences of the literal 'managed' across
components and API modules (agent-overview-tab.tsx,
agent-runtime-config-section.tsx, create-agent, delete-agent,
get-agent-runtime-config, update-agent-runtime-config, provision-managed-agent)
to reference the new constant (update the isManagedRuntime assignment to compare
against the exported enum/const instead of the raw string).

apps/api/src/app/agents/agents.controller.ts (1)

132-134: ⚡ Quick win

Avoid unsafe cast for provider catalog response.

Line 133 uses as AgentRuntimeProviderResponseDto[], which can hide contract drift between shared catalog shape and DTO shape.

💡 Suggested fix

   listAgentRuntimeProviders(): AgentRuntimeProviderResponseDto[] {
-    return AGENT_RUNTIME_PROVIDERS as AgentRuntimeProviderResponseDto[];
+    return [...AGENT_RUNTIME_PROVIDERS];
   }

🤖 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 `@apps/api/src/app/agents/agents.controller.ts` around lines 132 - 134, The
return uses an unsafe cast of AGENT_RUNTIME_PROVIDERS to
AgentRuntimeProviderResponseDto[], which can hide contract drift; update
listAgentRuntimeProviders to explicitly map/validate each entry from
AGENT_RUNTIME_PROVIDERS into an AgentRuntimeProviderResponseDto (e.g., map over
AGENT_RUNTIME_PROVIDERS and construct objects containing only the DTO fields or
run a validation/transform such as class-transformer/class-validator or a type
guard) so the function (listAgentRuntimeProviders) returns a guaranteed-correct
AgentRuntimeProviderResponseDto[] rather than relying on a raw "as" cast.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

packages/shared/src/dto/agent/managed-runtime.dto.ts (1)

52-59: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

AgentMcpServerDto.authToken is still exposed on the read DTO.

This concern was raised previously and remains unaddressed in the current code: an authToken?: string field on a DTO that flows into both read and write paths makes it easy for MCP auth tokens to leak through API responses, logs, or analytics events. Split into a read DTO that exposes only hasAuthToken: boolean (or masked metadata) and a separate write DTO that accepts authToken?: string for updates.

🤖 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/shared/src/dto/agent/managed-runtime.dto.ts` around lines 52 - 59,
AgentMcpServerDto currently exposes authToken and must be split into separate
read/write DTOs: keep a read-only shape (e.g., AgentMcpServerReadDto) that
replaces authToken with a boolean hasAuthToken (or masked metadata) and a
write/update shape (e.g., AgentMcpServerWriteDto) that accepts authToken?:
string for incoming requests. Replace usages of AgentMcpServerDto in
response/serialization paths with AgentMcpServerReadDto and use
AgentMcpServerWriteDto for controllers/services that accept or persist
authToken; ensure any mapping code (serializers or constructors that currently
reference AgentMcpServerDto.authToken) only sets hasAuthToken on read DTOs and
only reads/writes authToken from the write DTO.

libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts (1)

55-71: ⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Still using bracket notation on APIError.headers — request-id and Retry-After are being dropped.

This was raised in a prior review and remains unresolved. APIError.headers in @anthropic-ai/sdk is a Headers instance, so err.headers?.['request-id'] and err.headers?.['retry-after'] always evaluate to undefined. The SDK also exposes err.requestID directly. As written:

• The requestId arg passed into every error class is always undefined — request-id is never logged or surfaced.
• parseRetryAfter always falls through to its 60_000 default, so 429s lose their actual Retry-After hint and the API/dashboard's Retry-After-aware retry logic gets the wrong value.

🩹 Proposed fix

     if (err instanceof APIError) {
-      const requestId = err.headers?.['request-id'] as string | undefined;
+      const requestId = err.requestID ?? err.headers?.get('request-id') ?? undefined;

       if (err.status === 401) {
         throw new AgentRuntimeUnauthorizedError(err.message, PROVIDER_ID, requestId);
       }
       if (err.status === 403) {
         throw new AgentRuntimeForbiddenError(err.message, PROVIDER_ID, requestId);
       }
       if (err.status === 404) {
         throw new AgentRuntimeNotFoundError(err.message, PROVIDER_ID, requestId);
       }
       if (err.status === 429) {
-        const retryAfterMs = parseRetryAfter(err.headers?.['retry-after'] as string | undefined);
+        const retryAfterMs = parseRetryAfter(err.headers?.get('retry-after') ?? undefined);

         throw new AgentRuntimeRateLimitedError(err.message, PROVIDER_ID, retryAfterMs, requestId);
       }

`@anthropic-ai/sdk` 0.95.1 APIError headers Headers object requestID property

🤖 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
`@libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts`
around lines 55 - 71, The code is reading request-id and retry-after using
bracket notation on APIError.headers which is a Headers instance, so change to
read requestId from err.requestID (set requestId = err.requestID as string |
undefined) and read retry-after via the Headers.get method (call
parseRetryAfter(err.headers?.get('retry-after') as string | undefined)); then
pass that requestId into the
AgentRuntimeUnauthorizedError/AgentRuntimeForbiddenError/AgentRuntimeNotFoundError/AgentRuntimeRateLimitedError
constructors (and pass the parsed retryAfterMs to AgentRuntimeRateLimitedError)
while keeping PROVIDER_ID unchanged.

libs/application-generic/src/agent-runtimes/i-agent-runtime-provider.ts (1)

10-32: ⚡ Quick win

Use interface instead of type for backend type definitions.

CreateAgentInput, CreateAgentResult, and UpdateAgentRuntimeConfigInput should be declared as interface on the backend to match the rest of the contract (which already uses interface IAgentRuntimeProvider).

♻️ Proposed change

-export type CreateAgentInput = {
+export interface CreateAgentInput {
   name: string;
   model?: string;
   systemPrompt?: string;
   /** Builtin tool type strings, e.g. 'web_search', 'bash' */
   tools?: string[];
   /** MCP server catalog entries resolved to {name, url} pairs */
   mcpServers?: Array<{ name: string; url: string }>;
   /** Skills to attach to the agent at creation time. Maximum 20. */
   skills?: AgentSkillDto[];
-};
+}

-export type CreateAgentResult = {
+export interface CreateAgentResult {
   externalAgentId: string;
-};
+}

-export type UpdateAgentRuntimeConfigInput = {
+export interface UpdateAgentRuntimeConfigInput {
   model?: string;
   systemPrompt?: string;
   mcpServers?: AgentMcpServerDto[];
   tools?: AgentToolDto[];
   skills?: AgentSkillDto[];
-};
+}

As per coding guidelines: "On the backend: use interface for type definitions; on the frontend: use type for type definitions".

🤖 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 `@libs/application-generic/src/agent-runtimes/i-agent-runtime-provider.ts`
around lines 10 - 32, Replace the three backend type aliases with interfaces to
match the existing contract style: convert CreateAgentInput, CreateAgentResult,
and UpdateAgentRuntimeConfigInput from "type" to "interface" declarations,
preserving all property names, optional markers, and nested types (e.g.,
AgentSkillDto, AgentMcpServerDto, AgentToolDto) so consumers of
IAgentRuntimeProvider see consistent interface types; ensure JSDoc/comments
(like the tools and mcpServers descriptions) remain above the corresponding
interface properties.

apps/dashboard/src/components/agents/create-agent-dialog.tsx (1)

250-262: 💤 Low value

Optional: extract the hard-coded model and providerId: 'anthropic' strings.

'claude-opus-4-5' (line 253) and 'anthropic' (line 251) are duplicated in agents-list.tsx and the provider catalog. Consider pulling them from the shared AGENT_RUNTIME_PROVIDERS entry (default model) and AgentRuntimeProviderIdEnum.Anthropic so a model bump only needs to be made in one place.

🤖 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 `@apps/dashboard/src/components/agents/create-agent-dialog.tsx` around lines
250 - 262, Replace hard-coded provider and model strings in the create-agent
payload with the shared constants: use AgentRuntimeProviderIdEnum.Anthropic
(instead of 'anthropic') to set providerId and pull the default model from
AGENT_RUNTIME_PROVIDERS (e.g.,
AGENT_RUNTIME_PROVIDERS[AgentRuntimeProviderIdEnum.Anthropic].defaultModel)
instead of 'claude-opus-4-5'; update the block that assigns body.managedRuntime
(and any related mapping for skills) to reference these constants so future
model/provider changes are centralized.

packages/shared/src/consts/providers/claude-skills.ts (1)

64-157: 💤 Low value

Optional: track CLAUDE_OPENSOURCE_SKILLS as a parked TODO so it doesn't quietly rot.

CLAUDE_OPENSOURCE_SKILLS is defined (~90 lines) but neither exported nor included in CLAUDE_ANTHROPIC_SKILLS, so it ships as dead bytes until the /v1/skills upload flow lands. Consider either:

• Adding a // TODO(NV-XXXX): reference next to the comment on line 156 so the link to the follow-up work is grep-able, or
• Stripping the constant until the upload feature is implemented and reintroducing it then.

Either approach prevents accidental drift between this list and the upstream anthropics/skills repo.

🤖 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/shared/src/consts/providers/claude-skills.ts` around lines 64 - 157,
CLAUDE_OPENSOURCE_SKILLS is defined but unused and will rot; either add a
grep-able TODO or remove it: locate the CLAUDE_OPENSOURCE_SKILLS constant and
either (a) add a comment like "// TODO(NV-XXXX): track open-source skills list
until /v1/skills upload is implemented" immediately above or next to the
declaration so it’s searchable, or (b) delete the CLAUDE_OPENSOURCE_SKILLS block
and reintroduce it when the upload flow exists; ensure CLAUDE_ANTHROPIC_SKILLS
(and any reference to CLAUDE_PREBUILT_SKILLS) remains unchanged.

apps/dashboard/src/components/agents/agents-list.tsx (1)

95-106: ⚡ Quick win

Hard-coded integration name collides for users with multiple managed agents.

Every managed-runtime agent in an environment creates an integration named "Anthropic (managed agents)". From the integrations list this becomes indistinguishable noise (and there's no link back to which agent the credential belongs to). Consider scoping the name with the agent identifier or name, e.g.:

-            name: 'Anthropic (managed agents)',
+            name: `Anthropic — ${body.name}`,

That keeps it human-readable and traceable. Same comment applies if/when more managed providers are added.

🤖 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 `@apps/dashboard/src/components/agents/agents-list.tsx` around lines 95 - 106,
Integration names are being hard-coded to "Anthropic (managed agents)" which
collides when multiple managed agents exist; update the createIntegration call
(the object passed to createIntegration in agents-list.tsx) to include a unique,
human-readable identifier by incorporating the agent's name or id (e.g., append
agent.name or agent._id into the name field) so each created integration is
traceable back to its agent, and ensure the chosen field (agent.name or
agent._id) is available in scope and safely stringified/escaped before
concatenation.

libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts (1)

116-189: ⚖️ Poor tradeoff

Remove unnecessary as any casts for typed access to beta.agents API.

The provider casts client as any for create (line 116), retrieve (line 151), and update (line 189), but uses the typed surface for archive (line 139). The inconsistency indicates the casts are defensive or residual from prototyping. Since beta.agents.archive() works without casting, the typed API is accessible for all methods.

Removing the as any casts will:

• Allow TypeScript to catch payload-shape changes at compile time rather than runtime
• Eliminate implicit any types on method returns (e.g., agent.model, agent.skills)
• Be consistent across all beta.agents methods

Verify that your TypeScript configuration or IDE correctly infers types for beta.agents.create, retrieve, and update in @anthropic-ai/[email protected], then drop the casts.

🤖 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
`@libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts`
around lines 116 - 189, The file uses defensive casts like (client as
any).beta.agents.create/retrieve/update while archive uses the typed client;
remove the unnecessary "as any" casts and call client.beta.agents.create,
client.beta.agents.retrieve and client.beta.agents.update directly so TypeScript
can infer the correct request/response types (adjust any downstream usages that
assumed implicit any on agent.model/agent.skills to match the SDK types); ensure
buildClient returns the correctly typed client so the compiler recognizes
beta.agents methods without casting.

apps/api/src/app/agents/e2e/managed-agent.e2e.ts (1)

30-42: ⚡ Quick win

Use the runtime integration channel in this fixture.

The managed-runtime flow stores Anthropic credentials as an agent-runtime integration, but this setup inserts an IN_APP integration. That means the suite will not catch bugs in channel-specific lookup or validation.

Suggested fix

-    channel: ChannelTypeEnum.IN_APP,
+    channel: ChannelTypeEnum.AGENT_RUNTIME,

Based on PR objectives: the PR adds ChannelTypeEnum.AGENT_RUNTIME for managed runtime integrations.

🤖 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 `@apps/api/src/app/agents/e2e/managed-agent.e2e.ts` around lines 30 - 42, The
fixture creates an integration with ChannelTypeEnum.IN_APP but the
managed-runtime flow expects ChannelTypeEnum.AGENT_RUNTIME; update the
integration object in the test (the call to integrationRepository.create where
providerId is AgentRuntimeProviderIdEnum.Anthropic and name 'Anthropic Runtime
E2E' / identifier `anthropic-runtime-e2e-${Date.now()}`) to set channel:
ChannelTypeEnum.AGENT_RUNTIME so the test uses the runtime integration path and
validates channel-specific lookup/validation logic.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

apps/api/src/app/agents/usecases/create-agent/create-agent.usecase.ts (1)

43-44: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Defense-in-depth: still silently downgrades runtime: 'managed' to a self-hosted insert when managedRuntime is absent.

isManaged = command.runtime === 'managed' && command.managedRuntime evaluates to false when runtime === 'managed' but managedRuntime is missing, so the code falls through to the plain agentRepository.create(...) branch on line 127 and silently persists a self-hosted agent labeled as managed-in-intent. The DTO @ValidateIf should normally catch this, but until create-agent.command.ts is fixed (@Type(() => Object) and the type-only import still neuter the nested validator), this is reachable. Throw UnprocessableEntityException explicitly here.

Suggested fix

-import { ConflictException, Injectable } from '@nestjs/common';
+import { ConflictException, Injectable, UnprocessableEntityException } from '@nestjs/common';
@@
-    const isManaged = command.runtime === 'managed' && command.managedRuntime;
+    if (command.runtime === 'managed' && !command.managedRuntime) {
+      throw new UnprocessableEntityException('managedRuntime is required when runtime is "managed".');
+    }
+    const isManaged = command.runtime === 'managed';

As per coding guidelines: apps/api/**: Check for proper error handling and input validation.

🤖 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 `@apps/api/src/app/agents/usecases/create-agent/create-agent.usecase.ts` around
lines 43 - 44, The current isManaged calculation can silently downgrade
runtime:'managed' when managedRuntime is missing; update the logic in
create-agent.usecase.ts to explicitly validate this: if command.runtime ===
'managed' and !command.managedRuntime, throw an UnprocessableEntityException
with a clear message instead of falling through to agentRepository.create; keep
the existing isManaged flag (e.g., const isManaged = command.runtime ===
'managed' && !!command.managedRuntime) but add the explicit guard before any
repository create calls to prevent persisting a mis-labeled agent.

apps/api/src/app/agents/usecases/create-agent/create-agent.command.ts (1)

15-15: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Nested DTO validation for managedRuntime is still broken.

The class is still imported as a type-only symbol on line 15, and @Type(() => Object) on line 43 does not trigger class-transformer to instantiate ManagedRuntimeDto. As a result @ValidateNested() walks a plain object and the inner @IsEnum/@IsString/etc. decorators on ManagedRuntimeDto never run, so invalid providerId, integrationId, or externalAgentId shapes pass through unchecked.

Suggested fix

-import type { ManagedRuntimeDto } from '../../dtos/agent-runtime-config.dto';
+import { ManagedRuntimeDto } from '../../dtos/agent-runtime-config.dto';
@@
   `@ValidateIf`((o) => o.runtime === 'managed')
   `@IsObject`()
   `@ValidateNested`()
-  `@Type`(() => Object)
+  `@Type`(() => ManagedRuntimeDto)
   managedRuntime?: ManagedRuntimeDto;

Also applies to: 40-44

🤖 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 `@apps/api/src/app/agents/usecases/create-agent/create-agent.command.ts` at
line 15, The nested DTO validation fails because ManagedRuntimeDto is imported
as a type-only symbol and the property decorator uses `@Type`(() => Object), so
class-transformer never instantiates ManagedRuntimeDto and `@ValidateNested`()
walks a plain object; fix by importing ManagedRuntimeDto as a runtime value
(remove the type-only import) and change the property decorator for
managedRuntime to `@Type`(() => ManagedRuntimeDto) alongside `@ValidateNested`(), so
class-transformer will create a ManagedRuntimeDto instance and inner decorators
(e.g., `@IsEnum/`@IsString) will run; apply the same change to the other
managedRuntime occurrences around the existing decorators.

apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.command.ts (1)

1-1: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

providerId still lacks enum validation.

providerId is only decorated with @IsNotEmpty(), so any non-empty string (e.g. "foo") survives DTO validation and is forwarded to getAgentRuntimeProvider. Add @IsEnum(AgentRuntimeProviderIdEnum) and promote the import from a type-only import so the enum is available at runtime.

Suggested fix

-import type { AgentRuntimeProviderIdEnum, AgentSkillDto } from '@novu/shared';
+import { AgentRuntimeProviderIdEnum } from '@novu/shared';
+import type { AgentSkillDto } from '@novu/shared';
 import { Type } from 'class-transformer';
-import { IsArray, IsNotEmpty, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { IsArray, IsEnum, IsNotEmpty, IsOptional, IsString, ValidateNested } from 'class-validator';
@@
   `@IsNotEmpty`()
+  `@IsEnum`(AgentRuntimeProviderIdEnum)
   providerId: AgentRuntimeProviderIdEnum;

Also applies to: 22-23

🤖 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
`@apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.command.ts`
at line 1, The providerId field lacks enum validation; change the type-only
import of AgentRuntimeProviderIdEnum to a runtime import (remove the "type"
modifier) so the enum is available at runtime, and add the class-validator
decorator `@IsEnum`(AgentRuntimeProviderIdEnum) to the providerId property (in the
DTO used by provision-managed-agent.command and the related DTO on lines 22-23)
instead of only `@IsNotEmpty`(), so invalid strings are rejected before calling
getAgentRuntimeProvider.

libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts (2)

224-230: 💤 Low value

parseRetryAfter ignores the HTTP‑date form of Retry-After.

Per RFC 9110, Retry-After may be either delta-seconds or an HTTP-date. parseFloat will return NaN for the date form and silently fall back to 60s, which is fine as a safety net but can grossly under- or over-state the actual wait. If you want to honor a 429/503 hint accurately, parse the date branch as well (Date.parse(header) - Date.now()), clamped to a non-negative value.

🤖 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
`@libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts`
around lines 224 - 230, The parseRetryAfter function currently treats the header
only as delta-seconds; update parseRetryAfter(header: string | undefined) to
also handle the HTTP-date form: if parseFloat(header) yields NaN, attempt a date
parse (const ms = Date.parse(header) - Date.now()), ensure the result is a
non-negative integer (Math.max(0, Math.round(ms))), and return that value in
milliseconds; if the date parse is invalid fall back to the existing 60_000 ms
default. Ensure you reference parseRetryAfter in
anthropic-agent-runtime.provider.ts and preserve the original return type and
fallback semantics.

---

306-327: 💤 Low value

buildToolsPayload always emits at least one entry, so the length > 0 guards in createAgent/updateConfig are dead code.

buildToolsPayload unconditionally pushes the agent_toolset_20260401 entry on line 315 before considering MCP servers, so its return array is never empty. The toolsPayload.length > 0 checks at lines 124 and 198 will therefore always be true. This isn't itself broken, but it's misleading and hides the side effect that every create/patch implicitly resets the builtin toolset. Either drop the dead guards or short‑circuit buildToolsPayload to return [] when both inputs are absent so the gates become meaningful.

🤖 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
`@libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts`
around lines 306 - 327, buildToolsPayload currently always pushes the
agent_toolset_20260401 entry so callers' guards (toolsPayload.length > 0) in
createAgent/updateConfig are dead; fix by short‑circuiting buildToolsPayload to
return [] when both toolTypes is null/empty and mcpServers is null/empty (i.e.
check if (!toolTypes || toolTypes.length===0) && (!mcpServers ||
mcpServers.length===0) then return []), otherwise build the payload as before
(refer to buildToolsPayload, CLAUDE_BUILTIN_TOOLS, and the callers
createAgent/updateConfig).

apps/dashboard/src/components/agents/create-agent-dialog.tsx (1)

254-263: ⚡ Quick win

integrationId: '' is sent from the dialog and must be overwritten by the caller.

Both submission branches set managedRuntime.integrationId to an empty string. The dialog itself never creates an integration, so this implicitly requires the caller (e.g., agents-list.tsx) to create the integration first and overwrite integrationId (or strip it) before forwarding to the API. This is easy to break silently if a new caller is added. Consider omitting integrationId here and letting the caller add it, so the type system catches the missing value rather than shipping a placeholder.

Also applies to: 273-287

🤖 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 `@apps/dashboard/src/components/agents/create-agent-dialog.tsx` around lines
254 - 263, The dialog currently always sets managedRuntime.integrationId to an
empty string in both submission branches (see the body object built when
isExistingMode and the other branch around lines 273-287), which forces callers
to overwrite it; instead remove integrationId from the dialog payload when it's
empty and only include managedRuntime.integrationId when a non-empty value is
provided (e.g., check externalIntegrationId or a local integrationId field and
conditionally add that property), so callers must explicitly supply an
integrationId and the type system will catch missing values.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

packages/shared/src/dto/agent/managed-runtime.dto.ts (1)

57-64: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Don't expose raw MCP auth tokens in a shared read DTO.

AgentRuntimeConfigDto is a cross-layer response shape, so carrying authToken here makes secret leakage into UI state and logging paths far too easy. Split this into a safe read DTO (hasAuthToken or masked metadata) and a separate write DTO for updates.

🤖 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/shared/src/dto/agent/managed-runtime.dto.ts` around lines 57 - 64,
AgentMcpServerDto currently includes a raw authToken which can leak secrets via
cross-layer responses; change the public/shared response shape by removing
authToken from AgentMcpServerDto and replace it with a safe indicator (e.g.,
hasAuthToken: boolean or masked metadata) and create a separate write/update DTO
(e.g., AgentMcpServerUpdateDto or AgentMcpServerWriteDto) that contains the
authToken for create/update flows; update all references/uses of
AgentMcpServerDto and any consumers (including where AgentRuntimeConfigDto
embeds MCP server info) to use the new safe read DTO for responses and the write
DTO for input paths so the secret is never emitted in read payloads or logs.

apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.usecase.ts (2)

185-202: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Check the agent update result before treating provisioning as persisted.

agentRepository.update() can return { matched: 0 } without throwing. In that case the upstream agent is already created/adopted, but no local document stores externalAgentId, so the provider resource is orphaned.

🤖 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
`@apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.usecase.ts`
around lines 185 - 202, The agent update call in
provision-managed-agent.usecase.ts uses this.agentRepository.update(...) but
doesn't inspect the returned result; because update() can return { matched: 0 }
without throwing, ensure you capture the update result, check matched/modified
(e.g., const result = await this.agentRepository.update(...)), and if matched
=== 0 (or modified === 0) treat provisioning as not persisted: either throw an
error to abort the flow or perform cleanup by deleting the created provider
resource using externalAgentId via the provider client (and/or rollback any
created integration), ensuring you pass the same session/options when performing
cleanup or throwing so you don't leave an orphaned externalAgentId.

---

155-159: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Reject unknown MCP server IDs instead of sending empty URLs upstream.

Falling back to { name: serverId, url: '' } turns invalid input into a provider-side failure after provisioning has already started. Validate against CLAUDE_MCP_SERVERS and fail fast with a clear 400.

As per coding guidelines: apps/api/**: Check for proper error handling and input validation.

🤖 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
`@apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.usecase.ts`
around lines 155 - 159, The current mapping of command.mcpServers creates
entries with empty URLs for unknown IDs; instead validate against
CLAUDE_MCP_SERVERS and fail fast: in the provision flow where resolvedMcpServers
is built (the mapping over command.mcpServers in
provision-managed-agent.usecase.ts), for each serverId look up
CLAUDE_MCP_SERVERS.find(s => s.id === serverId) and if not found throw a 400 Bad
Request (e.g., throw new BadRequestException or HttpException) with a clear
message listing the invalid serverId(s); only return the mapped array when all
IDs are valid and handle the case where command.mcpServers is undefined/null by
leaving resolvedMcpServers undefined or empty as intended.

libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts (3)

59-74: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use Headers.get() when normalizing Anthropic errors.

APIError.headers is a Headers object, so bracket access here leaves requestId and retry-after undefined. That breaks request correlation and drops the 429 backoff hint.

In `@anthropic-ai/sdk` v0.95.1, is APIError.headers a Headers object, and should request-id / retry-after be read with headers.get(...) instead of bracket notation?

🤖 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
`@libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts`
around lines 59 - 74, The code assumes APIError.headers is a plain object and
uses bracket access for request-id and retry-after, but APIError.headers is a
Headers instance; replace bracket access with Headers.get(...) to read values
(e.g., use err.headers?.get('request-id') for requestId and
err.headers?.get('retry-after') for parseRetryAfter), then pass those retrieved
strings into AgentRuntimeUnauthorizedError / AgentRuntimeForbiddenError /
AgentRuntimeNotFoundError / AgentRuntimeRateLimitedError (and into
parseRetryAfter) so request correlation and 429 backoff hints work correctly in
anthropic-agent-runtime.provider.ts where APIError, parseRetryAfter, and the
AgentRuntime* error constructors are used.

---

114-135: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Don't retry provider-side create calls without idempotency.

withRetry wraps both beta.agents.create and beta.environments.create. If the first write succeeds but the response is lost, the retry can provision a second upstream resource and Novu will persist only the retry result.

In `@anthropic-ai/sdk` v0.95.1, do beta.agents.create and beta.environments.create support request-level idempotencyKey, and are retries without it safe for resource creation?

Also applies to: 216-233

🤖 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
`@libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts`
around lines 114 - 135, The createAgent method is wrapping the non-idempotent
upstream call (client.beta.agents.create) inside withRetry which can duplicate
resources if the first request succeeded but the response was lost; update
createAgent (and the similar beta.environments.create call) to either stop using
withRetry for the provider-side create path or, if the Anthropic SDK supports a
request-level idempotency key for beta.agents.create / beta.environments.create,
pass a stable idempotencyKey (derived from input or a persisted mapping) to the
SDK call so retries are safe—locate the calls in createAgent and the environment
creation block, remove the retry wrapper or add idempotencyKey handling and
ensure normaliseError still runs on unretriable failures.

---

193-202: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

A one-sided PATCH currently clears the untouched tool configuration.

When patch.mcpServers is set without patch.tools, buildToolsPayload(undefined, ...) disables every builtin tool. The inverse case rebuilds updatePayload.tools without existing MCP toolsets, so they get removed even though the caller didn't patch them.

🤖 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
`@libs/application-generic/src/agent-runtimes/anthropic/anthropic-agent-runtime.provider.ts`
around lines 193 - 202, The PATCH logic currently calls buildToolsPayload with
undefined when only one side (patch.tools or patch.mcpServers) is provided,
which removes untouched tool configuration; to fix, when computing toolTypes and
mcpServers for buildToolsPayload in anthropic-agent-runtime.provider.ts, merge
the incoming patch values with the existing runtime's current values instead of
passing undefined: derive currentToolTypes = patch.tools ?
patch.tools.map(t=>t.name) : existingRuntime.tools?.map(t=>t.name) and
currentMcpServers = patch.mcpServers ?
patch.mcpServers.map(s=>({name:s.name,url:s.url})) :
existingRuntime.mcp_servers?.map(s=>({name:s.name,url:s.url})), then call
buildToolsPayload(currentToolTypes, currentMcpServers) and only assign
updatePayload.tools if (patch.tools !== undefined || patch.mcpServers !==
undefined) && toolsPayload.length > 0 so untouched toolsets are preserved when
the caller did not patch them.

apps/api/src/app/agents/agents.controller.ts (1)

123-134: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Gate /agents/runtime-providers behind the managed-runtime flag.

This route still returns the provider catalog for any authenticated tenant with AGENT_READ, so disabled tenants can discover managed-runtime metadata directly via the API.

🤖 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 `@apps/api/src/app/agents/agents.controller.ts` around lines 123 - 134, The
listAgentRuntimeProviders route currently returns AGENT_RUNTIME_PROVIDERS for
any user with AGENT_READ; update listAgentRuntimeProviders to first check the
tenant's managed-runtime feature flag (via the request/tenant context or the
FeatureFlagService used elsewhere) and if the managed-runtime flag is disabled
for that tenant return a ForbiddenException or NotFoundException (matching
existing pattern for hiding disabled features) instead of the provider list;
keep the RequirePermissions(PermissionsEnum.AGENT_READ) decorator but gate the
actual response using the managed-runtime check before returning
AGENT_RUNTIME_PROVIDERS.

apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.command.ts (1)

22-23: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Validate providerId as an enum, not just a non-empty value.

@IsNotEmpty() still accepts arbitrary strings here, so unsupported provider IDs can get through command validation and fail later in the provisioning flow. Add @IsEnum(AgentRuntimeProviderIdEnum).

In class-validator 0.14.1, does `@IsNotEmpty`() validate enum membership, or is `@IsEnum`(...) required to reject invalid enum values?

🤖 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
`@apps/api/src/app/agents/usecases/provision-managed-agent/provision-managed-agent.command.ts`
around lines 22 - 23, The providerId property uses only `@IsNotEmpty`() so invalid
strings can pass validation; update the ProvisionManagedAgentCommand (property
providerId) to also use `@IsEnum`(AgentRuntimeProviderIdEnum) so only valid enum
members are accepted, and add the corresponding import for IsEnum from
class-validator; keep `@IsNotEmpty`() if you want both non-empty and enum checks
but ensure IsEnum(AgentRuntimeProviderIdEnum) is present to enforce membership.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

libs/dal/src/repositories/agent/agent.schema.ts (2)

31-34: ⚡ Quick win

Consider adding a default value for runtime.

The runtime field has no default, which means existing agents will have undefined runtime. Per the entity documentation, absence is treated as 'self-hosted' for backward compatibility, but this implicit behavior creates ambiguity in queries and application logic.

Adding default: 'self-hosted' would make the data model explicit and simplify query predicates (e.g., finding all self-hosted agents wouldn't need { $or: [{ runtime: 'self-hosted' }, { runtime: { $exists: false } }] }).

📝 Proposed fix to add explicit default

 runtime: {
   type: Schema.Types.String,
   enum: ['self-hosted', 'managed'],
+  default: 'self-hosted',
 },

Based on past review comments: scopsy previously asked "Wonder if we should default here?" on this field.

🤖 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 `@libs/dal/src/repositories/agent/agent.schema.ts` around lines 31 - 34, The
runtime field in the Agent schema currently has type: Schema.Types.String and
enum ['self-hosted','managed'] but no default, leaving old documents undefined;
update the runtime schema definition (the runtime property in agent.schema.ts)
to include default: 'self-hosted' so new records are explicit and queries no
longer need to special-case missing runtime values.

---

60-61: ⚡ Quick win

Add indexes for runtime-based queries.

The schema currently indexes _environmentId and identifier+_environmentId, but there are no indexes on the new runtime or managedRuntime.providerId fields. If the application queries agents by runtime type (e.g., "find all managed agents") or by provider (e.g., "find all Anthropic agents"), these queries will require collection scans.

🔍 Proposed indexes for common runtime queries

 agentSchema.index({ _environmentId: 1 });
 agentSchema.index({ identifier: 1, _environmentId: 1 }, { unique: true });
+agentSchema.index({ runtime: 1, _environmentId: 1 });
+agentSchema.index({ 'managedRuntime.providerId': 1, _environmentId: 1 }, { sparse: true });

Note: The managedRuntime.providerId index should be sparse since only managed-runtime agents will have this field.

As per coding guidelines: "Review with focus on data integrity and query performance. Check for proper MongoDB indexes on new queries."

🤖 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 `@libs/dal/src/repositories/agent/agent.schema.ts` around lines 60 - 61, The
schema is missing indexes for runtime-based queries; add indexes via
agentSchema.index to cover queries on the runtime field and on
managedRuntime.providerId (use a sparse index for managedRuntime.providerId
since only managed agents have it) so lookups like "find by runtime" and "find
by managedRuntime.providerId" avoid collection scans; update the file to add
agentSchema.index({ runtime: 1 }) and agentSchema.index({
"managedRuntime.providerId": 1 }, { sparse: true }) alongside the existing
indexes.

apps/api/src/app/agents/usecases/delete-agent/delete-agent.usecase.ts (1)

70-96: ⚖️ Poor tradeoff

Transaction ordering exposes a small inconsistency window.

The provider delete (line 95) executes before the local transaction begins (line 39). If the provider delete succeeds but the local transaction fails (e.g., database unavailable), the external agent is deleted but the local record remains.

While Mongoose transactions can be retried and will eventually succeed, this creates a brief inconsistency where the provider agent is gone but Novu still shows it.

Consider moving the provider delete inside the transaction scope if the runtime provider SDK supports idempotent deletes. This ensures atomicity: both succeed or both fail together. However, this increases transaction duration and may not be worth the complexity if provider SDKs don't handle idempotency well.

await this.agentRepository.withTransaction(async (session) => {
  // Delete from provider first (may throw and abort transaction)
  if (agent.runtime === 'managed' && agent.managedRuntime && shouldDeleteFromProvider) {
    await this.deleteFromProvider(agent.managedRuntime, command);
  }
  
  // Then clean up locally
  await this.cleanupNovuEmail.cleanupForAgent(agent._id, command.environmentId, command.organizationId, session);
  // ... rest of transaction
});

As per coding guidelines: "Check for proper error handling" and "Review with focus on data integrity" (libs/dal patterns).

🤖 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 `@apps/api/src/app/agents/usecases/delete-agent/delete-agent.usecase.ts` around
lines 70 - 96, The provider delete currently runs outside the DB transaction and
can leave the external agent removed while the local delete fails; move the call
to deleteFromProvider(...) into the agentRepository.withTransaction(...)
callback before the local cleanup so both operations occur inside the same
transaction scope (use the same session passed to
cleanupNovuEmail.cleanupForAgent and other repository calls); ensure runtime
provider deletes are idempotent or handle delete errors to abort the transaction
(references: deleteFromProvider, agentRepository.withTransaction,
cleanupNovuEmail.cleanupForAgent, DeleteAgentCommand, managedRuntime).

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes