drop support for zod/v3 in several core packages (#14464)

Co-authored-by: wardpeet <ward@coding-tech.com>
Co-authored-by: Mastra Code (openai/gpt-5.4) <noreply@mastra.ai>

Author: 3 people

.changeset/ten-friends-like.md

@@ -0,0 +1,12 @@
+---
+'@mastra/client-js': patch
+'@mastra/ai-sdk': patch
+'@mastra/react': patch
+'@mastra/server': patch
+'@mastra/core': patch
+'@mastra/schema-compat': patch
+---
+
+Fix Zod v3 and Zod v4 compatibility across public structured-output APIs.
+
+Mastra agent and client APIs accept schemas from either `zod/v3` or `zod/v4`, matching the documented peer dependency range and preserving TypeScript compatibility for both Zod versions.

client-sdks/ai-sdk/src/__tests__/add-tool-result-message-id.test.ts

@@ -23,7 +23,7 @@ import { Mastra } from '@mastra/core/mastra';
 import { createTool } from '@mastra/core/tools';
 import { convertArrayToReadableStream, MockLanguageModelV2 } from 'ai/test';
 import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v4';
 
 import { handleChatStream } from '../chat-route';
 

client-sdks/ai-sdk/src/convert-streams.ts

@@ -10,7 +10,7 @@ import type {
 } from '@internal/ai-v6';
 import type { MastraModelOutput, ChunkType, MastraAgentNetworkStream, WorkflowRunOutput } from '@mastra/core/stream';
 import type { MastraWorkflowStream, Step, WorkflowResult } from '@mastra/core/workflows';
-import type { ZodObject, ZodType } from 'zod';
+import type { ZodObject, ZodType } from 'zod/v4';
 import type { V6UIMessageStream } from './public-types';
 import {
   AgentNetworkToAISDKTransformer,

client-sdks/client-js/src/example.ts

@@ -1,4 +1,4 @@
-import z from 'zod';
+import { z } from 'zod/v4';
 import { MastraClient } from './client';
 // import type { WorkflowRunResult } from './types';
 

client-sdks/client-js/src/resources/agent.test.ts

@@ -2,7 +2,7 @@ import type { ToolsInput } from '@mastra/core/agent';
 import { RequestContext as RequestContextClass } from '@mastra/core/request-context';
 import { createTool } from '@mastra/core/tools';
 import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v4';
 import { MastraClient } from '../client';
 import type { StreamParams, ClientOptions } from '../types';
 import { zodToJsonSchema } from '../utils/zod-to-json-schema';

client-sdks/client-js/src/resources/agent.ts

@@ -18,8 +18,8 @@ import type { FullOutput, MastraModelOutput } from '@mastra/core/stream';
 import type { Tool } from '@mastra/core/tools';
 import { standardSchemaToJSONSchema, toStandardSchema } from '@mastra/schema-compat/schema';
 import type { JSONSchema7 } from 'json-schema';
-import type { ZodType } from 'zod/v3';
 import type {
+  ZodSchema,
   GenerateLegacyParams,
   GetAgentResponse,
   GetToolResponse,
@@ -237,15 +237,15 @@ export class Agent extends BaseResource {
     params: GenerateLegacyParams<undefined> & { output?: never; experimental_output?: never },
   ): Promise<GenerateReturn<any, undefined, undefined>>;
   // Use `any` in overload return types to avoid "Type instantiation is excessively deep" errors
-  async generateLegacy<Output extends JSONSchema7 | ZodType>(
+  async generateLegacy<Output extends JSONSchema7 | ZodSchema>(
     params: GenerateLegacyParams<Output> & { output: Output; experimental_output?: never },
   ): Promise<GenerateReturn<any, any, any>>;
-  async generateLegacy<StructuredOutput extends JSONSchema7 | ZodType>(
+  async generateLegacy<StructuredOutput extends JSONSchema7 | ZodSchema>(
     params: GenerateLegacyParams<StructuredOutput> & { output?: never; experimental_output: StructuredOutput },
   ): Promise<GenerateReturn<any, any, any>>;
   async generateLegacy<
-    Output extends JSONSchema7 | ZodType | undefined = undefined,
-    _StructuredOutput extends JSONSchema7 | ZodType | undefined = undefined,
+    Output extends JSONSchema7 | ZodSchema | undefined = undefined,
+    _StructuredOutput extends JSONSchema7 | ZodSchema | undefined = undefined,
   >(params: GenerateLegacyParams<Output>): Promise<GenerateReturn<any, any, any>> {
     const processedParams = {
       ...params,
@@ -726,7 +726,7 @@ export class Agent extends BaseResource {
    * @param params - Stream parameters including prompt
    * @returns Promise containing the enhanced Response object with processDataStream method
    */
-  async streamLegacy<T extends JSONSchema7 | ZodType | undefined = undefined>(
+  async streamLegacy<T extends JSONSchema7 | ZodSchema | undefined = undefined>(
     params: StreamLegacyParams<T>,
   ): Promise<
     Response & {

client-sdks/client-js/src/resources/agent.vnext.test.ts

@@ -2,7 +2,7 @@ import { APICallError } from '@internal/ai-sdk-v5';
 import { getErrorFromUnknown } from '@mastra/core/error';
 import { createTool } from '@mastra/core/tools';
 import { describe, it, beforeEach, expect, vi } from 'vitest';
-import z from 'zod';
+import { z } from 'zod/v4';
 import { MastraClient } from '../client';
 
 // Mock fetch globally

client-sdks/client-js/src/tools.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v4';
 import { createTool } from './tools';
 
 describe('createTool', () => {

client-sdks/client-js/src/tools.ts

@@ -1,5 +1,5 @@
 import type { ToolCallOptions } from '@internal/ai-sdk-v5';
-import type { z } from 'zod';
+import type { z } from 'zod/v4';
 
 // Client-side tool execution context (simplified version without server dependencies)
 export interface ClientToolExecutionContext<TSchemaIn extends z.ZodSchema | undefined = undefined> {

client-sdks/client-js/src/types.ts

@@ -44,10 +44,13 @@ import type {
   WorkflowRunStatus,
   WorkflowState,
 } from '@mastra/core/workflows';
-import type { PublicSchema } from '@mastra/schema-compat';
+import type { PublicSchema } from '@mastra/schema-compat/schema';
 
 import type { JSONSchema7 } from 'json-schema';
-import type { ZodSchema } from 'zod/v3';
+import type { ZodSchema as ZodSchemaV3 } from 'zod/v3';
+import type { ZodType as ZodTypeV4 } from 'zod/v4';
+
+export type ZodSchema = ZodSchemaV3 | ZodTypeV4;
 
 export interface ClientOptions {
   /** Base URL for API requests */