feat: change maxSteps to 40

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'
@@ -96,7 +96,7 @@ export class PageAgentCore extends EventTarget {
 	constructor(config: PageAgentCoreConfig) {
 		super()
 
-		this.config = { ...config, maxSteps: config.maxSteps || 20 }
+		this.config = { ...config, maxSteps: config.maxSteps || 40 }
 
 		this.#llm = new LLM(this.config)
 		this.tools = new Map(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

@@ -12,7 +12,7 @@ export interface AgentConfig extends LLMConfig {
 
 	/**
 	 * Maximum number of steps the agent can take per task.
-	 * @default 20
+	 * @default 40
 	 */
 	maxSteps?: number
 
@@ -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,9 +1,11 @@
 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'
 
+const log = console.log.bind(console, chalk.yellow('[autoFixer]'))
+
 /**
  * Normalize LLM response and fix common format issues.
  *
@@ -34,7 +36,7 @@ export function normalizeResponse(response: any, tools?: Map<string, PageAgentTo
 
 		// case: sometimes the model only returns the action level
 		if (toolCall.function.name && toolCall.function.name !== 'AgentOutput') {
-			console.log(chalk.yellow(`[normalizeResponse] #1: fixing tool_call`))
+			log(`#1: fixing tool_call`)
 			resolvedArguments = { action: safeJsonParse(resolvedArguments) }
 		}
 	} else {
@@ -47,13 +49,13 @@ export function normalizeResponse(response: any, tools?: Map<string, PageAgentTo
 
 				// case: sometimes the content json includes upper level wrapper
 				if (resolvedArguments?.name === 'AgentOutput') {
-					console.log(chalk.yellow(`[normalizeResponse] #2: fixing tool_call`))
+					log(`#2: fixing tool_call`)
 					resolvedArguments = safeJsonParse(resolvedArguments.arguments)
 				}
 
 				// case: sometimes even 2-levels of wrapping
 				if (resolvedArguments?.type === 'function') {
-					console.log(chalk.yellow(`[normalizeResponse] #3: fixing tool_call`))
+					log(`#3: fixing tool_call`)
 					resolvedArguments = safeJsonParse(resolvedArguments.function.arguments)
 				}
 
@@ -66,7 +68,7 @@ export function normalizeResponse(response: any, tools?: Map<string, PageAgentTo
 					!resolvedArguments?.next_goal &&
 					!resolvedArguments?.thinking
 				) {
-					console.log(chalk.yellow(`[normalizeResponse] #4: fixing tool_call`))
+					log(`#4: fixing tool_call`)
 					resolvedArguments = { action: safeJsonParse(resolvedArguments) }
 				}
 			} else {
@@ -90,7 +92,7 @@ export function normalizeResponse(response: any, tools?: Map<string, PageAgentTo
 
 	// fix incomplete formats
 	if (!resolvedArguments.action) {
-		console.log(chalk.yellow(`[normalizeResponse] #5: fixing tool_call`))
+		log(`#5: fixing tool_call`)
 		resolvedArguments.action = { name: 'wait', input: { seconds: 1 } }
 	}
 
@@ -149,9 +151,7 @@ function validateAction(action: any, tools: Map<string, PageAgentTool>): any {
 			(k) => !(schema.shape as Record<string, z.ZodType>)[k].safeParse(undefined).success
 		)
 		if (requiredKey) {
-			console.log(
+			log(`coercing primitive action input for "${toolName}"`)
-				chalk.yellow(`[normalizeResponse] coercing primitive action input for "${toolName}"`)
-			)
 			value = { [requiredKey]: value }
 		}
 	}

packages/core/src/utils/index.ts

@@ -1,6 +1,6 @@
 import chalk from 'chalk'
 
-export { normalizeResponse } from './autoFixer'
+export * from './autoFixer'
 
 export async function waitFor(seconds: number): Promise<void> {
 	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
@@ -72,11 +72,15 @@ export async function fetchLlmsTxt(url: string): Promise<string | null> {
 		if (res.ok) {
 			result = await res.text()
 			console.log(chalk.green(`[llms.txt] Found (${result.length} chars)`))
+			if (result.length > 1000) {
+				console.log(chalk.yellow(`[llms.txt] Truncating to 1000 chars`))
+				result = truncate(result, 1000)
+			}
 		} else {
-			console.log(chalk.gray(`[llms.txt] ${res.status} for ${endpoint}`))
+			console.debug(chalk.gray(`[llms.txt] ${res.status} for ${endpoint}`))
 		}
 	} catch (e) {
-		console.log(chalk.gray(`[llms.txt] Failed for ${endpoint}`), e)
+		console.debug(chalk.gray(`[llms.txt] not found for ${endpoint}`), e)
 	}
 	llmsTxtCache.set(origin, result)
 	return result

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,13 +2,11 @@
  * 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'
 
-function debug(message: string) {
+const debug = console.debug.bind(console, chalk.gray('[LLM]'))
-	console.debug(chalk.gray('[LLM]'), message)
-}
 
 /**
  * Convert Zod schema to OpenAI tool format

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/advanced/page-agent-core/page.tsx

@@ -181,7 +181,7 @@ const result = await agent.execute('Fill in the form with test data')`}
 						{
 							name: 'maxSteps',
 							type: 'number',
-							defaultValue: '20',
+							defaultValue: '40',
 							description: isZh ? '每个任务的最大步骤数' : 'Maximum number of steps per task',
 						},
 						{

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({