Merge pull request #158 from alibaba/fix/zod-v3

feat: import zod properly

package-lock.json

@@ -11118,8 +11118,13 @@
             "dependencies": {
                 "@page-agent/llms": "1.4.4",
                 "@page-agent/page-controller": "1.4.4",
-                "chalk": "^5.6.2",
+                "chalk": "^5.6.2"
+            },
+            "devDependencies": {
                 "zod": "^4.3.5"
+            },
+            "peerDependencies": {
+                "zod": "^3.25.0 || ^4.0.0"
             }
         },
         "packages/extension": {
@@ -11132,8 +11137,7 @@
                 "@page-agent/page-controller": "1.4.4",
                 "@page-agent/ui": "1.4.4",
                 "ai-motion": "^0.4.8",
-                "chalk": "^5.6.2",
+                "chalk": "^5.6.2"
-                "zod": "^4.3.5"
             },
             "devDependencies": {
                 "@radix-ui/react-hover-card": "^1.1.15",
@@ -11162,6 +11166,9 @@
                 "tailwindcss": "^4.1.14",
                 "tw-animate-css": "^1.4.0",
                 "wxt": "^0.20.18"
+            },
+            "peerDependencies": {
+                "zod": "^3.25.0 || ^4.0.0"
             }
         },
         "packages/llms": {
@@ -11169,8 +11176,13 @@
             "version": "1.4.4",
             "license": "MIT",
             "dependencies": {
-                "chalk": "^5.6.2",
+                "chalk": "^5.6.2"
+            },
+            "devDependencies": {
                 "zod": "^4.3.5"
+            },
+            "peerDependencies": {
+                "zod": "^3.25.0 || ^4.0.0"
             }
         },
         "packages/page-agent": {
@@ -11181,8 +11193,13 @@
                 "@page-agent/llms": "1.4.4",
                 "@page-agent/page-controller": "1.4.4",
                 "@page-agent/ui": "1.4.4",
-                "chalk": "^5.6.2",
+                "chalk": "^5.6.2"
+            },
+            "devDependencies": {
                 "zod": "^4.3.5"
+            },
+            "peerDependencies": {
+                "zod": "^3.25.0 || ^4.0.0"
             }
         },
         "packages/page-controller": {

packages/core/package.json

@@ -44,8 +44,13 @@
     },
     "dependencies": {
         "chalk": "^5.6.2",
-        "zod": "^4.3.5",
         "@page-agent/llms": "1.4.4",
         "@page-agent/page-controller": "1.4.4"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+    },
+    "devDependencies": {
+        "zod": "^4.3.5"
     }
 }

packages/core/src/PageAgentCore.ts

@@ -5,7 +5,7 @@
 import { InvokeError, LLM, type Tool } from '@page-agent/llms'
 import type { BrowserState, PageController } from '@page-agent/page-controller'
 import chalk from 'chalk'
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'

packages/core/src/tools/index.ts

@@ -2,7 +2,7 @@
  * Internal tools for PageAgent.
  * @note Adapted from browser-use
  */
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import type { PageAgentCore } from '../PageAgentCore'
 import { waitFor } from '../utils'

packages/core/src/types.ts

@@ -24,13 +24,14 @@ export interface AgentConfig extends LLMConfig {
 	 *
 	 * @example
 	 * // override internal tool
+	 * import { z } from 'zod/v4'
 	 * import { tool } from 'page-agent'
 	 * const customTools = {
 	 * ask_user: tool({
 	 * 	description:
 	 * 		'Ask the user or parent model a question and wait for their answer. Use this if you need more information or clarification.',
-	 * 	inputSchema: zod.object({
+	 * 	inputSchema: z.object({
-	 * 		question: zod.string(),
+	 * 		question: z.string(),
 	 * 	}),
 	 * 	execute: async function (this: PageAgent, input) {
 	 * 		const answer = await do_some_thing(input.question)

packages/core/src/utils/autoFixer.ts

@@ -1,6 +1,6 @@
 import { InvokeError, InvokeErrorType } from '@page-agent/llms'
 import chalk from 'chalk'
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import type { PageAgentTool } from '../tools'
 

packages/core/vite.config.js

@@ -30,6 +30,7 @@ export default defineConfig({
 			external: [
 				'chalk',
 				'zod',
+				'zod/v4',
 				// all the internal packages
 				/^@page-agent\//,
 			],

packages/extension/package.json

@@ -43,7 +43,9 @@
         "@page-agent/page-controller": "1.4.4",
         "@page-agent/ui": "1.4.4",
         "ai-motion": "^0.4.8",
-        "chalk": "^5.6.2",
+        "chalk": "^5.6.2"
-        "zod": "^4.3.5"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
     }
 }

packages/extension/src/agent/tabTools.ts

@@ -6,7 +6,7 @@
  * - switch_to_tab: Switch to an existing tab
  * - close_tab: Close a tab (optionally switch to another)
  */
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import type { TabsController } from './TabsController'
 

packages/llms/package.json

@@ -37,7 +37,12 @@
         "postpublish": "node -e \"['LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
     },
     "dependencies": {
-        "chalk": "^5.6.2",
+        "chalk": "^5.6.2"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+    },
+    "devDependencies": {
         "zod": "^4.3.5"
     }
 }

packages/llms/src/OpenAIClient.ts

@@ -1,7 +1,7 @@
 /**
  * OpenAI Client implementation
  */
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import { InvokeError, InvokeErrorType } from './errors'
 import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'

packages/llms/src/types.ts

@@ -1,7 +1,7 @@
 /**
  * Core types for LLM integration
  */
-import type * as z from 'zod'
+import type * as z from 'zod/v4'
 
 /**
  * Message format - OpenAI standard (industry standard)

packages/llms/src/utils.ts

@@ -2,7 +2,7 @@
  * Utility functions for LLM integration
  */
 import chalk from 'chalk'
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import type { Tool } from './types'
 

packages/llms/vite.config.js

@@ -25,7 +25,7 @@ export default defineConfig({
 		},
 		outDir: resolve(__dirname, 'dist', 'lib'),
 		rollupOptions: {
-			external: ['chalk', 'zod'],
+			external: ['chalk', 'zod', 'zod/v4'],
 		},
 		minify: false,
 		sourcemap: true,

packages/page-agent/package.json

@@ -48,7 +48,12 @@
         "@page-agent/llms": "1.4.4",
         "@page-agent/page-controller": "1.4.4",
         "@page-agent/ui": "1.4.4",
-        "chalk": "^5.6.2",
+        "chalk": "^5.6.2"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+    },
+    "devDependencies": {
         "zod": "^4.3.5"
     }
 }

packages/page-agent/vite.config.js

@@ -30,6 +30,7 @@ export default defineConfig({
 			external: [
 				'chalk',
 				'zod',
+				'zod/v4',
 				// all the internal packages
 				/^@page-agent\//,
 			],

packages/website/src/pages/docs/features/custom-tools/page.tsx

@@ -16,6 +16,22 @@ export default function CustomTools() {
 			</p>
 
 			<div className="space-y-8">
+				<section>
+					<Heading id="zod-version" className="text-2xl font-bold mb-4">
+						{isZh ? 'Zod 版本' : 'Zod Version'}
+					</Heading>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? 'Page Agent 使用 Zod 定义工具的输入 schema。支持 Zod 3 (>=3.25.0) 和 Zod 4，请从 zod/v4 子路径导入。不支持 Zod Mini。'
+							: 'Page Agent uses Zod for tool input schemas. Both Zod 3 (>=3.25.0) and Zod 4 are supported. Always import from the zod/v4 subpath. Zod Mini is not supported.'}
+					</p>
+					<CodeEditor
+						code={`// Zod 3 (>=3.25.0) or Zod 4
+import { z } from 'zod/v4'`}
+						language="javascript"
+					/>
+				</section>
+
 				<section>
 					<Heading id="define-tools" className="text-2xl font-bold mb-4">
 						{isZh ? '定义工具' : 'Define Tools'}
@@ -27,7 +43,7 @@ export default function CustomTools() {
 					</p>
 
 					<CodeEditor
-						code={`import { z } from 'zod'
+						code={`import { z } from 'zod/v4'
 import { PageAgent, tool } from 'page-agent'
 
 const pageAgent = new PageAgent({