chore: require zod 4 for voltagent 3

Author: omeraplak

.changeset/voltagent-3-next.md

@@ -38,7 +38,7 @@ VoltAgent 3 aligns the framework with AI SDK v7, moves the published packages to
 
 ```bash
 pnpm add @voltagent/core@next @voltagent/server-hono@next @voltagent/logger@next
-pnpm add ai@^7 @ai-sdk/openai@^4
+pnpm add ai@^7 @ai-sdk/openai@^4 zod@^4
 ```
 
 If your app uses additional VoltAgent packages, keep all `@voltagent/*` packages on the same major/prerelease line:
@@ -97,6 +97,14 @@ Common provider package upgrades:
 | `@ai-sdk/amazon-bedrock`    | `^5`                  |
 | `@ai-sdk/google-vertex`     | `^5`                  |
 
+### Zod 4-only
+
+VoltAgent 3 requires Zod 4. The framework packages now use `zod@^4` peer ranges, examples and templates install Zod 4, and the old Zod 3 JSON Schema/OpenAPI compatibility fallback has been removed.
+
+```bash
+pnpm add zod@^4
+```
+
 ### Agent usage
 
 The object-style call shape is the preferred API. AI SDK generation options stay at the top level, while VoltAgent runtime concerns live under `voltagent`.
@@ -232,7 +240,8 @@ console.log(result.output);
 2. Set `"type": "module"` and replace CommonJS `require()` calls with ESM imports.
 3. Upgrade all `@voltagent/*` packages together from the `next` channel.
 4. Upgrade `ai` to `^7` and AI SDK provider packages to their v7-compatible majors.
-5. Replace `stepCountIs` with `isStepCount`.
-6. Prefer `result.stream` over `result.fullStream`.
-7. Prefer `output` over `experimental_output`.
-8. Prefer object-style agent calls for new code, with VoltAgent runtime options under `voltagent`.
+5. Upgrade `zod` to `^4`.
+6. Replace `stepCountIs` with `isStepCount`.
+7. Prefer `result.stream` over `result.fullStream`.
+8. Prefer `output` over `experimental_output`.
+9. Prefer object-style agent calls for new code, with VoltAgent runtime options under `voltagent`.

docs/ai-sdk-first-vnext-plan.md

@@ -24,11 +24,12 @@ This means AI SDK primitives such as `model`, `prompt`, `messages`, `tools`, `ou
 
 ## vNext Platform Decision
 
-Decision: VoltAgent vNext will target AI SDK 7, Node.js 22 or later, and ESM-only package output.
+Decision: VoltAgent vNext will target AI SDK 7, Zod 4, Node.js 22 or later, and ESM-only package output.
 
 This is an explicit compatibility boundary:
 
 - Set the repository and published package engine requirement to `node >=22`.
+- Set published Zod peer ranges to `^4.0.0` and remove Zod 3 fallback code paths.
 - Remove CommonJS runtime exports from vNext packages that depend on AI SDK or packages that depend on those packages.
 - Prefer `"type": "module"` and ESM package exports for new vNext package metadata.
 - Keep TypeScript declaration output for ESM consumers.
@@ -45,6 +46,7 @@ Migration consequence:
 
 - Users on Node.js 20 must stay on the previous VoltAgent major or upgrade Node before adopting vNext.
 - Users using `require("@voltagent/core")` must migrate to ESM imports.
+- Users pinned to Zod 3 must upgrade to Zod 4 before adopting VoltAgent 3.
 - Docs, examples, package exports, and migration guide must call this out clearly.
 
 ## Protected Feature Surface
@@ -932,6 +934,7 @@ Each PR should include focused tests and avoid mixing refactors with behavior ch
 | Model retry/fallback behavior changes                            | High   | Keep VoltAgent retry loop and add retry/fallback tests                                             |
 | CommonJS users break on vNext                                    | High   | Make ESM-only and Node.js 22 requirements explicit in package metadata and migration docs          |
 | Package exports or publint fail after removing CJS output        | High   | Update export maps package-by-package and run `pnpm publint:all`                                   |
+| Zod 3 compatibility fallback hides broken app dependencies       | Medium | Make VoltAgent 3 Zod 4-only in peer deps, examples, templates, docs, and converter code paths      |
 | Third-party providers are not AI SDK 7 compatible                | Medium | Audit third-party providers, document incompatibilities, and isolate unsupported provider builders |
 | Provider dependency decoupling expands scope                     | Medium | Deferred; keep existing router and provider dependency behavior unchanged in this plan             |
 | Server request schemas diverge from core API                     | Medium | Update schemas and processAgentOptions in same slice                                               |
@@ -949,7 +952,7 @@ Each PR should include focused tests and avoid mixing refactors with behavior ch
 - [x] Phase 6 ecosystem packages are updated.
 - [x] Phase 7 docs are available; executable codemods are deferred to a separate follow-up.
 - [x] Phase 8 release gates are green.
-- [ ] Phase 9 AI SDK 7, Node.js 22, ESM-only, and AI SDK-style tool support is complete.
+- [ ] Phase 9 AI SDK 7, Zod 4, Node.js 22, ESM-only, and AI SDK-style tool support is complete.
 
 ## Current Recommendation
 
@@ -964,10 +967,11 @@ Proceed in this order:
 7. Finish docs/codemod decisions and run release gates.
 8. Apply the Node.js 22 and ESM-only package boundary.
 9. Upgrade AI SDK dependencies to v7-compatible ranges.
-10. Run and review AI SDK v7 codemods.
-11. Update the core AI SDK boundary for v7 option, stream, callback, usage, and tool approval changes.
-12. Add AI SDK-style `tool()` and direct `ToolSet` support while preserving VoltAgent tool features.
-13. Update server, protocol, memory, scorer, docs, examples, and templates.
-14. Re-run the full release gates for the AI SDK 7 scope.
+10. Move Zod support to Zod 4-only across peers, examples, templates, and compatibility code.
+11. Run and review AI SDK v7 codemods.
+12. Update the core AI SDK boundary for v7 option, stream, callback, usage, and tool approval changes.
+13. Add AI SDK-style `tool()` and direct `ToolSet` support while preserving VoltAgent tool features.
+14. Update server, protocol, memory, scorer, docs, examples, and templates.
+15. Re-run the full release gates for the AI SDK 7 scope.
 
 This order keeps the vNext direction moving while minimizing the chance of losing existing framework features. Phase 8 was green before the AI SDK 7 scope was added; Phase 9 intentionally reopens the release-gate work for the new runtime and dependency boundary.

examples/base/package.json

@@ -9,7 +9,7 @@
     "@voltagent/logger": "^3.0.0-next.0",
     "@voltagent/server-hono": "^3.0.0-next.0",
     "ai": "^7.0.0",
-    "zod": "^3.25.76"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@types/node": "^24.2.1",

examples/github-repo-analyzer/package.json

@@ -9,7 +9,7 @@
     "@voltagent/logger": "^3.0.0-next.0",
     "@voltagent/server-hono": "^3.0.0-next.0",
     "ai": "^7.0.0",
-    "zod": "^3.25.76"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@types/node": "^24.2.1",

examples/github-star-stories/package.json

@@ -9,7 +9,7 @@
     "@voltagent/serverless-hono": "^3.0.0-next.0",
     "dotenv": "^16.4.5",
     "wrangler": "^3.38.0",
-    "zod": "^3.25.76"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@types/node": "^24.2.1",

examples/next-js-chatbot-starter-template/package.json

@@ -45,7 +45,7 @@
     "tailwind-merge": "^3.3.1",
     "tokenlens": "^1.3.1",
     "use-stick-to-bottom": "^1.1.1",
-    "zod": "^3.25.76"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.4",

examples/with-a2a-server/package.json

@@ -7,7 +7,7 @@
     "@voltagent/logger": "^3.0.0-next.0",
     "@voltagent/server-hono": "^3.0.0-next.0",
     "ai": "^7.0.0",
-    "zod": "^3.25.76"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@types/node": "^24.2.1",

examples/with-ad-creator/package.json

@@ -15,7 +15,7 @@
     "ai": "^7.0.0",
     "dotenv": "^16.4.5",
     "sharp": "^0.34.4",
-    "zod": "^3.25.76"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",

examples/with-agent-tool/package.json

@@ -6,7 +6,7 @@
   "dependencies": {
     "@voltagent/core": "^3.0.0-next.0",
     "ai": "^7.0.0",
-    "zod": "^3.25.76"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@types/node": "^24.2.1",

examples/with-airtable/package.json

@@ -9,7 +9,7 @@
     "@voltagent/sdk": "^3.0.0-next.0",
     "@voltagent/server-hono": "^3.0.0-next.0",
     "ai": "^7.0.0",
-    "zod": "^3.25.76"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@types/node": "^24.2.1",