fix: support Zod 3.25.56 alongside Zod 4

Preserve retry defaults and JSON Schema optional fields with older Zod
permalinks. Keep AI schema types optional for Zod-only consumers without
losing tool payload inference.

Author: carderne

.changeset/zod-4-support.md

@@ -9,6 +9,6 @@
 "@trigger.dev/schema-to-json": minor
 ---
 
-Add Zod 4 support. You can now use Zod 3.25.76+ or Zod 4.
+Add Zod 4 support. You can now use Zod 3.25.56+ or Zod 4.
 
 Zod remains a runtime dependency of packages that execute schemas, so existing and new installations continue to receive it automatically. The matching peer dependency range allows package managers to reuse either a compatible Zod 3 or Zod 4 installation from your project.

packages/cli-v3/src/utilities/commandError.test.ts

@@ -3,7 +3,7 @@ import { formatCommandError } from "./commandError.js";
 
 const expectedMessage = `Your installed Zod version is not supported by Trigger.dev.
 
-Trigger.dev requires zod@^3.25.76 or zod@^4.0.0. Upgrade Zod, reinstall your dependencies, and try again.`;
+Trigger.dev requires zod@^3.25.56 or zod@^4.0.0. Upgrade Zod, reinstall your dependencies, and try again.`;
 
 describe("formatCommandError", () => {
   it("explains when the installed Zod package does not export zod/v4", () => {

packages/cli-v3/src/utilities/commandError.ts

@@ -1,6 +1,6 @@
 const UNSUPPORTED_ZOD_MESSAGE = `Your installed Zod version is not supported by Trigger.dev.
 
-Trigger.dev requires zod@^3.25.76 or zod@^4.0.0. Upgrade Zod, reinstall your dependencies, and try again.`;
+Trigger.dev requires zod@^3.25.56 or zod@^4.0.0. Upgrade Zod, reinstall your dependencies, and try again.`;
 
 export function formatCommandError(error: unknown): string {
   if (isUnsupportedZodError(error)) {

packages/core/package.json

@@ -229,7 +229,7 @@
     "std-env": "^3.8.1",
     "tinyexec": "^0.3.2",
     "uncrypto": "^0.1.3",
-    "zod": "^3.25.76 || ^4.0.0",
+    "zod": "^3.25.56 || ^4.0.0",
     "zod-validation-error": "^5.0.0"
   },
   "devDependencies": {
@@ -240,6 +240,7 @@
     "@types/humanize-duration": "^3.27.1",
     "ai": "^6.0.0",
     "ai-v7": "npm:ai@7.0.0-canary.159",
+    "zod-v3-floor": "npm:zod@3.25.56",
     "defu": "^6.1.4",
     "esbuild": "^0.23.0",
     "rimraf": "^6.0.1",
@@ -677,6 +678,6 @@
   "types": "./dist/commonjs/index.d.ts",
   "module": "./dist/esm/index.js",
   "peerDependencies": {
-    "zod": "^3.25.76 || ^4.0.0"
+    "zod": "^3.25.56 || ^4.0.0"
   }
 }

packages/core/src/v3/schemas/fetch.ts

@@ -25,7 +25,9 @@ export const FetchRetryHeadersStrategy = z.object({
       "iso_8601_duration_openai_variant",
     ])
     .default("unix_timestamp")
-    .optional(),
+    .optional()
+    // Early Zod 4 permalinks skip defaults inside optional schemas.
+    .overwrite((value) => value ?? "unix_timestamp"),
 });
 
 export type FetchRetryHeadersStrategy = z.infer<typeof FetchRetryHeadersStrategy>;

packages/core/src/v3/schemas/schemaCompositionCompatibility.test.ts

@@ -8,12 +8,15 @@ const require = createRequire(import.meta.url);
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
 
 describe("schema composition compatibility", () => {
-  it("parses Zod 4 parent schemas when the root Zod export resolves to Zod 3", async () => {
-    const result = await build({
-      stdin: {
-        contents: `
+  it.each(["zod", "zod-v3-floor"])(
+    "parses composed schemas with %s and a Zod 3 root",
+    async (zodPackage) => {
+      const result = await build({
+        stdin: {
+          contents: `
           import { ScheduleMetadata, WebhookMetadata } from "./src/v3/schemas/schemas.ts";
           import { WebhookResource } from "./src/v3/schemas/resources.ts";
+          import { FetchRetryHeadersStrategy } from "./src/v3/schemas/fetch.ts";
 
           const verifierArtifact = {
             kind: "preset",
@@ -23,6 +26,12 @@ describe("schema composition compatibility", () => {
           const routingTarget = { type: "task", taskId: "my-task" };
 
           export const parsed = {
+            retry: FetchRetryHeadersStrategy.parse({
+              strategy: "headers",
+              limitHeader: "x-limit",
+              remainingHeader: "x-remaining",
+              resetHeader: "x-reset",
+            }),
             schedule: ScheduleMetadata.parse({
               cron: "0 0 * * *",
               timezone: "UTC",
@@ -43,32 +52,39 @@ describe("schema composition compatibility", () => {
             }),
           };
         `,
-        loader: "ts",
-        resolveDir: packageRoot,
-      },
-      bundle: true,
-      format: "esm",
-      platform: "node",
-      target: "node20",
-      write: false,
-      plugins: [
-        {
-          name: "resolve-root-zod-to-v3",
-          setup(build) {
-            build.onResolve({ filter: /^zod$/ }, () => ({ path: require.resolve("zod/v3") }));
-          },
+          loader: "ts",
+          resolveDir: packageRoot,
         },
-      ],
-    });
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        target: "node20",
+        write: false,
+        plugins: [
+          {
+            name: "resolve-root-zod-to-v3",
+            setup(build) {
+              build.onResolve({ filter: /^zod$/ }, () => ({
+                path: require.resolve(`${zodPackage}/v3`),
+              }));
+              build.onResolve({ filter: /^zod\/v4$/ }, () => ({
+                path: require.resolve(`${zodPackage}/v4`),
+              }));
+            },
+          },
+        ],
+      });
 
-    const bundledModule = await import(
-      `data:text/javascript;base64,${Buffer.from(result.outputFiles[0]!.text).toString("base64")}`
-    );
+      const bundledModule = await import(
+        `data:text/javascript;base64,${Buffer.from(result.outputFiles[0]!.text).toString("base64")}`
+      );
 
-    expect(bundledModule.parsed).toMatchObject({
-      schedule: { window: "10%" },
-      metadata: { id: "my-webhook" },
-      resource: { id: "my-webhook" },
-    });
-  });
+      expect(bundledModule.parsed).toMatchObject({
+        retry: { resetFormat: "unix_timestamp" },
+        schedule: { window: "10%" },
+        metadata: { id: "my-webhook" },
+        resource: { id: "my-webhook" },
+      });
+    }
+  );
 });

packages/core/src/v3/sessionStreams/chatSnapshot.ts

@@ -19,9 +19,7 @@
 
 import { z } from "zod/v4";
 
-import type { UIMessage } from "ai";
-
-export type ChatSnapshotV1<TUIMessage extends UIMessage = UIMessage> = {
+export type ChatSnapshotV1<TUIMessage = unknown> = {
   version: 1;
   savedAt: number;
   messages: TUIMessage[];

packages/core/src/v3/types/tools.test.ts

@@ -0,0 +1,29 @@
+import { jsonSchema } from "ai";
+import { describe, expect, it } from "vitest";
+import { getSchemaParseFn } from "./schemas.js";
+import { convertToolParametersToSchema } from "./tools.js";
+
+describe("AI tool parameter schemas", () => {
+  it("uses the caller's validator and preserves validation failures", async () => {
+    const parameters = jsonSchema<{ count: number }>(
+      { type: "object", properties: { count: { type: "number" } }, required: ["count"] },
+      {
+        validate(value) {
+          if (
+            typeof value === "object" &&
+            value !== null &&
+            "count" in value &&
+            typeof value.count === "number"
+          ) {
+            return { success: true, value: { count: value.count } };
+          }
+          return { success: false, error: new Error("count must be a number") };
+        },
+      }
+    );
+    const parse = getSchemaParseFn(convertToolParametersToSchema(parameters));
+
+    await expect(parse({ count: 3 })).resolves.toEqual({ count: 3 });
+    await expect(parse({ count: "invalid" })).rejects.toThrow("count must be a number");
+  });
+});

packages/core/src/v3/types/tools.ts

@@ -1,11 +1,19 @@
-import type { Schema as AISchema } from "ai";
 import {
   isSchemaZodEsque,
   type AnyZodSchema,
   type inferZodSchemaOutput,
   type Schema,
 } from "./schemas.js";
 
+type ValidationResult<T> = { success: true; value: T } | { success: false; error: Error };
+
+// The structural contract keeps Zod-only consumers independent of the optional AI SDK.
+type AISchema<T> = {
+  _type: T;
+  readonly jsonSchema: unknown;
+  readonly validate?: (value: unknown) => ValidationResult<T> | PromiseLike<ValidationResult<T>>;
+};
+
 export type ToolTaskParameters = AnyZodSchema | AISchema<any>;
 
 export type inferToolParameters<PARAMETERS extends ToolTaskParameters> =

packages/redis-worker/package.json

@@ -27,7 +27,7 @@
     "nanoid": "^5.1.16",
     "p-limit": "^6.2.0",
     "seedrandom": "^3.0.5",
-    "zod": "^3.25.76 || ^4.0.0",
+    "zod": "^3.25.56 || ^4.0.0",
     "cron-parser": "^4.9.0"
   },
   "devDependencies": {
@@ -54,6 +54,6 @@
     }
   },
   "peerDependencies": {
-    "zod": "^3.25.76 || ^4.0.0"
+    "zod": "^3.25.56 || ^4.0.0"
   }
 }