fix(core,nestjs): restore scheduled workflow and prefix handling (#16637)

mbenhamd · web-flow · commit b32ba5fde524 · 2026-05-15T12:57:24.000-04:00
## Description This replaces #16113 with the two pieces that are still relevant on latest main. It loads the evented workflow registration from the public `@mastra/core/workflows` barrel so scheduled workflows created from that entry point promote correctly. It also makes the NestJS adapter treat requests outside the configured prefix as non-Mastra routes, including partial prefix matches like `/apiish/agents` when the prefix is `/api`. The query coercion changes from #16113 are intentionally not included because #16268 already fixed that behavior. ## Related issue(s) Fixes #16112 ## Type of change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Code refactoring - [x] Test update ## Checklist - [x] I have linked the related issue(s) in the description above - [x] I have made corresponding changes to the documentation (if applicable) - [x] I have added tests that prove my fix is effective or that my feature works - [ ] I have addressed all Coderabbit comments on this PR  ## ELI5 This PR fixes two bugs: scheduled workflows imported from the public workflows entry now register and promote correctly, and the NestJS adapter only treats requests that truly match the configured prefix as Mastra routes (so similar-but-different paths like `/apiish/agents` are ignored). ## Changes Overview ### Core workflow registration - Ensure evented workflow registration is triggered when consumers import from the public @mastra/core/workflows barrel by referencing the evented creator in packages/core/src/workflows/index.ts (imports createWorkflow from ./evented and keeps a live reference). - Restores promotion of scheduled workflows declared via the public barrel while avoiding ESM initialization cycles. - Tests updated: schedule-promotion.test.ts removed the transitive side-effect import and now relies on createWorkflow from ./index. ### NestJS route prefix enforcement - server-adapters/nestjs/src/utils/route-path.ts - getMastraRoutePath(path, prefix) now returns string | null and returns null when the path is outside the normalized prefix (only exact prefix or prefix + '/' are accepted). - server-adapters/nestjs/src/guards/mastra-route.guard.ts - If getMastraRoutePath returns null, the guard short-circuits (returns true) so Mastra auth/rate-limit logic is skipped for non-Mastra routes. - server-adapters/nestjs/src/controllers/mastra.controller.ts - handleRequest throws NotFoundException when getMastraRoutePath returns falsy; normal request handling proceeds for matched routes and double-slash paths are rejected. - server-adapters/nestjs/src/interceptors/tracing.interceptor.ts - Only attempts route matching when a routePath exists; otherwise matchResult is null to avoid matching on out-of-prefix requests. - Added tests: server-adapters/nestjs/src/__tests__/route-path.test.ts covering prefix normalization, exact-match-to-root mapping, and rejection of out-of-prefix / partial-prefix paths. ### Import refactoring to avoid barrel cycles - Multiple core files updated to import workflow primitives from specific modules (e.g., workflows/workflow, workflows/step, workflows/types) instead of the aggregated workflows barrel to avoid ESM import cycles while preserving runtime behavior and public APIs (several updates across agent, evals, loop, and workflow/evented files). ### Changesets and release notes - .changeset updates to publish patch releases: - @mastra/core: note that scheduled workflows created via the public workflows entry now correctly apply declared schedules. - @mastra/nestjs: note that configured route prefixes are enforced and partial prefix matches are ignored. ### Tests - schedule-promotion tests rely on the public barrel behavior (removed transitive import). - New Vitest suite for getMastraRoutePath validates strict prefix handling and normalization. ### Notes - Query coercion changes from the previously related PR are intentionally excluded because PR #16268 already addressed that behavior. - Classified as a bug fix; fixes issue #16112.  [![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/16637)
diff --git a/.changeset/slow-icons-take.md b/.changeset/slow-icons-take.md
@@ -0,0 +1,5 @@
+---
+'@mastra/nestjs': patch
+---
+
+Fixed NestJS route matching so configured prefixes are enforced and partial prefix matches are ignored. For example, a prefix of `/api` no longer matches `/apiish/agents`; only `/api` and `/api/*` are treated as Mastra routes.
diff --git a/.changeset/social-peaches-teach.md b/.changeset/social-peaches-teach.md
@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Fixed scheduled workflows created from the public @mastra/core/workflows entry point so declared schedules are applied correctly.
diff --git a/packages/core/src/agent/agent.ts b/packages/core/src/agent/agent.ts
@@ -79,8 +79,10 @@ import { makeCoreTool, createMastraProxy, ensureToolProperties, deepMerge } from
 import type { ToolOptions } from '../utils';
 import type { MastraVoice } from '../voice';
 import { DefaultVoice } from '../voice';
-import { createWorkflow, createStep, isProcessor } from '../workflows';
-import type { AnyWorkflow, OutputWriter, Step, WorkflowResult } from '../workflows';
+import type { Step } from '../workflows/step';
+import type { OutputWriter, WorkflowResult } from '../workflows/types';
+import type { AnyWorkflow } from '../workflows/workflow';
+import { createWorkflow, createStep, isProcessor } from '../workflows/workflow';
 import type { AnyWorkspace } from '../workspace';
 import { createWorkspaceTools } from '../workspace';
 import { createSkillTools } from '../workspace/skills';
diff --git a/packages/core/src/agent/workflows/prepare-stream/index.ts b/packages/core/src/agent/workflows/prepare-stream/index.ts
@@ -9,7 +9,7 @@ import { InternalSpans } from '../../../observability';
 import type { RequestContext } from '../../../request-context';
 import { MastraModelOutput } from '../../../stream';
 import type { ToolPayloadTransformPolicy } from '../../../tools';
-import { createWorkflow } from '../../../workflows';
+import { createWorkflow } from '../../../workflows/workflow';
 import type { Workspace } from '../../../workspace/workspace';
 import type { InnerAgentExecutionOptions } from '../../agent.types';
 import type { SaveQueueManager } from '../../save-queue';
diff --git a/packages/core/src/agent/workflows/prepare-stream/map-results-step.ts b/packages/core/src/agent/workflows/prepare-stream/map-results-step.ts
@@ -8,7 +8,7 @@ import { createObservabilityContext } from '../../../observability';
 import type { Span, SpanType } from '../../../observability';
 import { StructuredOutputProcessor } from '../../../processors';
 import type { RequestContext } from '../../../request-context';
-import type { Step } from '../../../workflows';
+import type { Step } from '../../../workflows/step';
 import type { InnerAgentExecutionOptions } from '../../agent.types';
 import type { SaveQueueManager } from '../../save-queue';
 import { getModelOutputForTripwire } from '../../trip-wire';
diff --git a/packages/core/src/agent/workflows/prepare-stream/prepare-memory-step.ts b/packages/core/src/agent/workflows/prepare-stream/prepare-memory-step.ts
@@ -7,7 +7,7 @@ import type { MemoryConfigInternal, StorageThreadType } from '../../../memory/ty
 import { resolveObservabilityContext } from '../../../observability';
 import type { ProcessorState } from '../../../processors/runner';
 import type { RequestContext } from '../../../request-context';
-import { createStep } from '../../../workflows';
+import { createStep } from '../../../workflows/workflow';
 import type { InnerAgentExecutionOptions } from '../../agent.types';
 import { MessageList } from '../../message-list';
 import type { AgentMethodType } from '../../types';
diff --git a/packages/core/src/agent/workflows/prepare-stream/prepare-tools-step.ts b/packages/core/src/agent/workflows/prepare-stream/prepare-tools-step.ts
@@ -4,7 +4,7 @@ import type { StorageThreadType } from '../../../memory/types';
 import type { Span, SpanType } from '../../../observability';
 import { createObservabilityContext } from '../../../observability';
 import type { RequestContext } from '../../../request-context';
-import { createStep } from '../../../workflows';
+import { createStep } from '../../../workflows/workflow';
 import type { InnerAgentExecutionOptions } from '../../agent.types';
 import type { AgentMethodType } from '../../types';
 import type { AgentCapabilities } from './schema';
diff --git a/packages/core/src/agent/workflows/prepare-stream/stream-step.ts b/packages/core/src/agent/workflows/prepare-stream/stream-step.ts
@@ -9,7 +9,7 @@ import { resolveObservabilityContext } from '../../../observability';
 import { RequestContext } from '../../../request-context';
 import { MastraModelOutput } from '../../../stream';
 import type { ToolPayloadTransformPolicy } from '../../../tools';
-import { createStep } from '../../../workflows';
+import { createStep } from '../../../workflows/workflow';
 import type { Workspace } from '../../../workspace/workspace';
 import type { SaveQueueManager } from '../../save-queue';
 import type { CreatedAgentSignal } from '../../signals';
diff --git a/packages/core/src/evals/base.ts b/packages/core/src/evals/base.ts
@@ -28,7 +28,7 @@ import { executeWithContext } from '../observability/utils';
 import { RequestContext } from '../request-context';
 import type { PublicSchema } from '../schema';
 import { toStandardSchema, standardSchemaToJSONSchema } from '../schema';
-import { createWorkflow, createStep } from '../workflows';
+import { createWorkflow, createStep } from '../workflows/workflow';
 import type {
   ScoringSamplingConfig,
   ScorerRunInputForAgent,
diff --git a/packages/core/src/evals/run/index.ts b/packages/core/src/evals/run/index.ts
@@ -7,8 +7,9 @@ import type { ObservabilityContext } from '../../observability';
 import { EntityType, resolveObservabilityContext } from '../../observability';
 import type { RequestContext } from '../../request-context';
 import type { MastraCompositeStore } from '../../storage';
-import { Workflow } from '../../workflows';
-import type { AnyWorkflow, WorkflowResult, WorkflowRunStartOptions, StepResult } from '../../workflows';
+import type { WorkflowResult, WorkflowRunStartOptions, StepResult } from '../../workflows/types';
+import type { AnyWorkflow } from '../../workflows/workflow';
+import { Workflow } from '../../workflows/workflow';
 import type { MastraScorer } from '../base';
 import { extractTrajectory, extractTrajectoryFromTrace, extractWorkflowTrajectory } from '../types';
 import { ScoreAccumulator } from './scorerAccumulator';
diff --git a/packages/core/src/loop/network/index.ts b/packages/core/src/loop/network/index.ts
@@ -21,8 +21,8 @@ import type { ChunkType } from '../../stream';
 import { escapeUnescapedControlCharsInJsonStrings } from '../../stream/base/output-format-handlers';
 import { MastraAgentNetworkStream } from '../../stream/MastraAgentNetworkStream';
 import type { IdGeneratorContext } from '../../types';
-import { createStep, createWorkflow } from '../../workflows';
-import type { Step, SuspendOptions } from '../../workflows';
+import type { Step, SuspendOptions } from '../../workflows/step';
+import { createStep, createWorkflow } from '../../workflows/workflow';
 import { PRIMITIVE_TYPES } from '../types';
 
 /**
@@ -1525,8 +1525,7 @@ export async function createNetworkLoop({
         throw mastraError;
       }
 
-      // @ts-expect-error - bad type
-      const toolId = tool.id;
+      const toolId = 'id' in tool && typeof tool.id === 'string' ? tool.id : inputData.primitiveId;
       // Use safeParseLLMJson to handle malformed JSON from LLM (truncated, unescaped chars, etc.)
       const inputDataToUse = await safeParseLLMJson(inputData.prompt);
       if (inputDataToUse === null) {
diff --git a/packages/core/src/loop/workflows/agentic-execution/background-task-check-step.ts b/packages/core/src/loop/workflows/agentic-execution/background-task-check-step.ts
@@ -1,6 +1,6 @@
 import type { ToolSet } from '@internal/ai-sdk-v5';
 import { ChunkFrom } from '../../../stream/types';
-import { createStep } from '../../../workflows';
+import { createStep } from '../../../workflows/workflow';
 import type { OuterLLMRun } from '../../types';
 import { llmIterationOutputSchema } from '../schema';
 import type { LLMIterationData } from '../schema';
diff --git a/packages/core/src/loop/workflows/agentic-execution/index.ts b/packages/core/src/loop/workflows/agentic-execution/index.ts
@@ -1,6 +1,6 @@
 import type { ToolSet } from '@internal/ai-sdk-v5';
 import { InternalSpans } from '../../../observability';
-import { createWorkflow } from '../../../workflows';
+import { createWorkflow } from '../../../workflows/workflow';
 import type { OuterLLMRun } from '../../types';
 import { llmIterationOutputSchema } from '../schema';
 import type { LLMIterationData } from '../schema';
diff --git a/packages/core/src/loop/workflows/agentic-execution/is-task-complete-step.ts b/packages/core/src/loop/workflows/agentic-execution/is-task-complete-step.ts
@@ -2,7 +2,7 @@ import type { ToolSet } from '@internal/ai-sdk-v5';
 import type { IsTaskCompleteRunResult, MastraDBMessage } from '../../../agent';
 import type { ChunkType } from '../../../stream/types';
 import { ChunkFrom } from '../../../stream/types';
-import { createStep } from '../../../workflows';
+import { createStep } from '../../../workflows/workflow';
 import { runStreamCompletionScorers, formatStreamCompletionFeedback } from '../../network/validation';
 import type { StreamCompletionContext } from '../../network/validation';
 import type { OuterLLMRun } from '../../types';
diff --git a/packages/core/src/loop/workflows/agentic-execution/llm-execution-step.ts b/packages/core/src/loop/workflows/agentic-execution/llm-execution-step.ts
@@ -45,7 +45,7 @@ import { findProviderToolByName, inferProviderExecuted } from '../../../tools/pr
 import type { ToolToConvert } from '../../../tools/tool-builder/builder';
 import { isMastraTool } from '../../../tools/toolchecks';
 import { makeCoreTool } from '../../../utils';
-import { createStep } from '../../../workflows';
+import { createStep } from '../../../workflows/workflow';
 import type { Workspace } from '../../../workspace/workspace';
 import type { LoopConfig, OuterLLMRun } from '../../types';
 import { AgenticRunState } from '../run-state';
diff --git a/packages/core/src/loop/workflows/agentic-execution/llm-mapping-step.ts b/packages/core/src/loop/workflows/agentic-execution/llm-mapping-step.ts
@@ -12,7 +12,7 @@ import {
   withToolPayloadTransformProviderMetadata,
 } from '../../../tools/payload-transform';
 import { findProviderToolByName } from '../../../tools/provider-tool-utils';
-import { createStep } from '../../../workflows';
+import { createStep } from '../../../workflows/workflow';
 import type { OuterLLMRun } from '../../types';
 import { llmIterationOutputSchema, toolCallOutputSchema } from '../schema';
 
diff --git a/packages/core/src/loop/workflows/agentic-execution/tool-call-step.ts b/packages/core/src/loop/workflows/agentic-execution/tool-call-step.ts
@@ -20,8 +20,8 @@ import {
 import { findProviderToolByName } from '../../../tools/provider-tool-utils';
 import type { MastraToolInvocationOptions } from '../../../tools/types';
 import { ensureSerializable } from '../../../utils';
-import type { SuspendOptions } from '../../../workflows';
-import { createStep } from '../../../workflows';
+import type { SuspendOptions } from '../../../workflows/step';
+import { createStep } from '../../../workflows/workflow';
 import type { OuterLLMRun } from '../../types';
 import { ToolNotFoundError } from '../errors';
 import { toolCallInputSchema, toolCallOutputSchema } from '../schema';
diff --git a/packages/core/src/loop/workflows/agentic-loop/index.ts b/packages/core/src/loop/workflows/agentic-loop/index.ts
@@ -5,8 +5,8 @@ import { InternalSpans } from '../../../observability';
 import { safeEnqueue } from '../../../stream/base';
 import type { ChunkType } from '../../../stream/types';
 import { ChunkFrom } from '../../../stream/types';
-import { createWorkflow } from '../../../workflows';
-import type { OutputWriter } from '../../../workflows';
+import type { OutputWriter } from '../../../workflows/types';
+import { createWorkflow } from '../../../workflows/workflow';
 import type { LoopRun } from '../../types';
 import { createAgenticExecutionWorkflow } from '../agentic-execution';
 import { llmIterationOutputSchema } from '../schema';
diff --git a/packages/core/src/workflows/evented/workflow.ts b/packages/core/src/workflows/evented/workflow.ts
@@ -2,10 +2,9 @@ import { randomUUID } from 'node:crypto';
 import { ReadableStream } from 'node:stream/web';
 import type { CoreMessage } from '@internal/ai-sdk-v4';
 import { z } from 'zod/v4';
-import { Agent } from '../../agent';
-import type { MastraDBMessage } from '../../agent';
+import { Agent } from '../../agent/agent';
 import { MessageList, messagesAreEqual } from '../../agent/message-list';
-import type { MessageInput } from '../../agent/message-list';
+import type { MastraDBMessage, MessageInput } from '../../agent/message-list';
 import { isAgentCompatible } from '../../agent/subagent';
 import type { SubAgent } from '../../agent/subagent';
 import { TripWire } from '../../agent/trip-wire';
@@ -34,14 +33,9 @@ import type { InferPublicSchema, InferStandardSchemaOutput, PublicSchema, Standa
 import { WorkflowRunOutput } from '../../stream/RunOutput';
 import type { ChunkType, LanguageModelUsage } from '../../stream/types';
 import { ChunkFrom } from '../../stream/types';
-import { Tool } from '../../tools';
+import { Tool } from '../../tools/tool';
 import type { ToolExecutionContext } from '../../tools/types';
 import type { DynamicArgument } from '../../types';
-import { Workflow, Run } from '../../workflows';
-// Direct import (bypassing the index) avoids a cycle: the index does a
-// side-effect import of `./evented`, so going through it from here would
-// re-enter an in-flight module evaluation and put `eventedCreateWorkflow` in TDZ.
-import type { AgentStepOptions } from '../../workflows';
 import type { ExecutionEngine, ExecutionGraph } from '../../workflows/execution-engine';
 import type { Step } from '../../workflows/step';
 import type {
@@ -62,7 +56,8 @@ import { validateCron } from '../scheduler/cron';
 import type { WorkflowScheduleConfig } from '../scheduler/types';
 import { forwardAgentStreamChunk } from '../stream-utils';
 import type { StreamChunkWriter } from '../stream-utils';
-import { __registerEventedCreateWorkflow } from '../workflow';
+import { Workflow, Run, __registerEventedCreateWorkflow } from '../workflow';
+import type { AgentStepOptions } from '../workflow';
 import { EventedExecutionEngine } from './execution-engine';
 import { isTripwireChunk, createTripWireFromChunk, getTextDeltaFromChunk } from './helpers';
 import type { TripwireChunk } from './helpers';
diff --git a/packages/core/src/workflows/index.ts b/packages/core/src/workflows/index.ts
@@ -6,3 +6,10 @@ export * from './types';
 export * from './utils';
 export * from './scheduler';
 export * from './state-reader';
+
+// Load after the base workflow exports so EventedWorkflow can extend Workflow
+// without hitting an ESM init-time cycle.
+import { createWorkflow as createEventedWorkflow } from './evented';
+
+// Keep a live reference so bundlers do not drop the registration import.
+void createEventedWorkflow;
diff --git a/packages/core/src/workflows/schedule-promotion.test.ts b/packages/core/src/workflows/schedule-promotion.test.ts
@@ -1,10 +1,5 @@
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod/v4';
-// Importing the evented module registers its factory with the default
-// `createWorkflow` registration slot, enabling schedule auto-promotion. In a
-// real app this happens transitively because Mastra itself imports from the
-// evented module.
-import './evented';
 import { createWorkflow as createDefaultWorkflow, createStep } from './index';
 
 describe('createWorkflow (default) — schedule promotion to evented', () => {
diff --git a/packages/core/src/workflows/workflow.ts b/packages/core/src/workflows/workflow.ts
@@ -3,12 +3,14 @@ import { ReadableStream, TransformStream } from 'node:stream/web';
 import type { CoreMessage } from '@internal/ai-sdk-v4';
 import { z } from 'zod/v4';
 import type { MastraPrimitives } from '../action';
-import { Agent } from '../agent';
-import type { AgentExecutionOptions, AgentStreamOptions, MastraDBMessage, SubAgent } from '../agent';
+import { Agent } from '../agent/agent';
+import type { AgentExecutionOptions } from '../agent/agent.types';
 import { MessageList, messagesAreEqual } from '../agent/message-list';
-import type { MessageInput } from '../agent/message-list';
+import type { MastraDBMessage, MessageInput } from '../agent/message-list';
 import { isAgentCompatible } from '../agent/subagent';
+import type { SubAgent } from '../agent/subagent';
 import { TripWire } from '../agent/trip-wire';
+import type { AgentStreamOptions } from '../agent/types';
 import { MastraFGAPermissions } from '../auth/ee';
 import { MastraBase } from '../base';
 import { RequestContext } from '../di';
@@ -46,8 +48,8 @@ import type { StorageListWorkflowRunsInput } from '../storage';
 import { WorkflowRunOutput } from '../stream/RunOutput';
 import type { ChunkType, LanguageModelUsage } from '../stream/types';
 import { ChunkFrom } from '../stream/types';
-import { Tool } from '../tools';
-import type { ToolExecutionContext } from '../tools';
+import { Tool } from '../tools/tool';
+import type { ToolExecutionContext } from '../tools/types';
 import type { DynamicArgument } from '../types';
 import { PUBSUB_SYMBOL, STREAM_FORMAT_SYMBOL } from './constants';
 import { DefaultExecutionEngine } from './default';
diff --git a/server-adapters/nestjs/src/__tests__/auth-rate-limit.test.ts b/server-adapters/nestjs/src/__tests__/auth-rate-limit.test.ts
@@ -52,20 +52,20 @@ describe('NestJS Adapter - Auth and Rate Limiting', () => {
 
     const missingToken = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents',
+      path: '/api/agents',
     });
     expect(missingToken.status).toBe(401);
 
     const invalidToken = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents',
+      path: '/api/agents',
       headers: { authorization: 'Bearer invalid' },
     });
     expect(invalidToken.status).toBe(401);
 
     const validToken = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents',
+      path: '/api/agents',
       headers: { authorization: 'Bearer valid' },
     });
     expect(validToken.status).toBe(200);
@@ -102,7 +102,7 @@ describe('NestJS Adapter - Auth and Rate Limiting', () => {
 
     const disabledResponse = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents?apiKey=valid',
+      path: '/api/agents?apiKey=valid',
     });
     expect(disabledResponse.status).toBe(401);
 
@@ -126,13 +126,13 @@ describe('NestJS Adapter - Auth and Rate Limiting', () => {
 
     const enabledResponse = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents?apiKey=valid',
+      path: '/api/agents?apiKey=valid',
     });
     expect(enabledResponse.status).toBe(200);
 
     const repeatedApiKeyResponse = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents?apiKey=valid&apiKey=ignored',
+      path: '/api/agents?apiKey=valid&apiKey=ignored',
     });
     expect(repeatedApiKeyResponse.status).toBe(200);
   });
@@ -157,13 +157,13 @@ describe('NestJS Adapter - Auth and Rate Limiting', () => {
 
     const first = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents',
+      path: '/api/agents',
     });
     expect(first.status).toBe(200);
 
     const second = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents',
+      path: '/api/agents',
     });
     expect(second.status).toBe(429);
   });
diff --git a/server-adapters/nestjs/src/__tests__/mastra-module.test.ts b/server-adapters/nestjs/src/__tests__/mastra-module.test.ts
@@ -174,7 +174,7 @@ describe('MastraModule', () => {
       // Verify routes are registered without binding to a port
       const response = await executeExpressRequest(expressApp, {
         method: 'GET',
-        path: '/agents',
+        path: '/api/agents',
       });
       expect(response.status).toBe(200);
 
@@ -429,7 +429,7 @@ describe('MastraModule', () => {
 
       const response = await executeExpressRequest(expressApp, {
         method: 'GET',
-        path: '/agents/non-existent-agent',
+        path: '/api/agents/non-existent-agent',
       });
       expect(response.status).toBe(404);
 
@@ -449,7 +449,7 @@ describe('MastraModule', () => {
 
       const response = await executeExpressRequest(expressApp, {
         method: 'GET',
-        path: '/agents/non-existent-agent',
+        path: '/api/agents/non-existent-agent',
       });
       expect(response.status).toBe(404);
 
diff --git a/server-adapters/nestjs/src/__tests__/request-context.test.ts b/server-adapters/nestjs/src/__tests__/request-context.test.ts
@@ -91,7 +91,7 @@ describe('NestJS Adapter - RequestContext parsing', () => {
     const expressApp = app.getHttpAdapter().getInstance() as Application;
     const response = await executeExpressRequest(expressApp, {
       method: 'POST',
-      path: '/agents/test-agent/generate',
+      path: '/api/agents/test-agent/generate',
       body: {
         messages: [{ role: 'user', content: 'hello' }],
         requestContext: { sessionId: 'session-42' },
@@ -124,7 +124,7 @@ describe('NestJS Adapter - RequestContext parsing', () => {
     const expressApp = app.getHttpAdapter().getInstance() as Application;
     const response = await executeExpressRequest(expressApp, {
       method: 'GET',
-      path: '/agents?tag=1&tag=2&requestContext=%7B%22traceId%22%3A%22trace-99%22%7D',
+      path: '/api/agents?tag=1&tag=2&requestContext=%7B%22traceId%22%3A%22trace-99%22%7D',
     });
 
     expect(response.status).toBe(200);
diff --git a/server-adapters/nestjs/src/__tests__/route-path.test.ts b/server-adapters/nestjs/src/__tests__/route-path.test.ts
diff --git a/server-adapters/nestjs/src/__tests__/server-app-access.test.ts b/server-adapters/nestjs/src/__tests__/server-app-access.test.ts
diff --git a/server-adapters/nestjs/src/controllers/mastra.controller.ts b/server-adapters/nestjs/src/controllers/mastra.controller.ts
diff --git a/server-adapters/nestjs/src/guards/mastra-route.guard.ts b/server-adapters/nestjs/src/guards/mastra-route.guard.ts
diff --git a/server-adapters/nestjs/src/interceptors/tracing.interceptor.ts b/server-adapters/nestjs/src/interceptors/tracing.interceptor.ts
diff --git a/server-adapters/nestjs/src/utils/route-path.ts b/server-adapters/nestjs/src/utils/route-path.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@mastra/nestjs': patch
 +---
++
 +Fixed NestJS route matching so configured prefixes are enforced and partial prefix matches are ignored. For example, a prefix of `/api` no longer matches `/apiish/agents`; only `/api` and `/api/*` are treated as Mastra routes.