add support for zod v4 (#1282)

Why 

Adds support for zod 4 while maintaining backwards compatibility with
zod 3

What changed 

- Introduced a zodCompat layer so Stagehand speaks both Zod v3 and v4
natively. Every place that used to import zod/v3, zod-to-json-schema, or
poke at schema internals now routes through the same helpers
(StagehandZodSchema, InferStagehandSchema, toJsonSchema, etc.). That
keeps existing apps on v3 working while letting us upgrade to the v4
ecosystem.
- Swapped all examples, eval tasks, tests, and LLM clients over to
standard zod imports, updated dependencies to accept 3.25.76 || 4.1.8,
and dropped zod-to-json-schema. Tool plumbing (Anthropic/Google CUA) and
custom clients now produce the right JSON Schema regardless of which Zod
flavor the user passes in.
- Tightened typings so structured LLM calls return { data, usage }
directly no more as casts throughout inference or the samples.

Manual testing
To make sure nothing regressed, I ran:
Custom OpenAI client example (schema conversion + structured output).
Standard extract (including URL injection path).
Google computer-use agent with a custom tool.
Anthropic computer-use agent with a custom tool.
All behaved as before

---------

Co-authored-by: miguel <[email protected]>

Author: tkattkat

.changeset/dark-pans-carry.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add support for zod 4, while maintaining backwards compatibility for zod 3 

packages/core/examples/2048.ts

@@ -1,5 +1,5 @@
 import { Stagehand } from "../lib/v3";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 async function example() {
   console.log("🎮 Starting 2048 bot...");

packages/core/examples/agent-custom-tools.ts

@@ -1,7 +1,7 @@
 /**
  * This example shows how to pass custom tools to stagehand agent (both CUA and non-CUA)
  */
-import { z } from "zod/v3";
+import { z } from "zod";
 import { tool } from "ai";
 import { Stagehand } from "../lib/v3";
 import chalk from "chalk";

packages/core/examples/custom_client_aisdk.ts

@@ -7,7 +7,7 @@
  */
 import { Stagehand } from "../lib/v3";
 import { AISdkClient } from "./external_clients/aisdk";
-import { z } from "zod/v3";
+import { z } from "zod";
 import { openai } from "@ai-sdk/openai";
 
 async function example() {

packages/core/examples/custom_client_langchain.ts

@@ -3,15 +3,17 @@
  *
  * You will need to reference the Langchain Client in /external_clients/langchain.ts
  */
-import { z } from "zod/v3";
+import { z } from "zod";
 import { Stagehand } from "../lib/v3";
 import { LangchainClient } from "./external_clients/langchain";
 import { ChatOpenAI } from "@langchain/openai";
 
 async function example() {
+  // @ts-expect-error Type instantiation is excessively deep and possibly infinite
   const stagehand = new Stagehand({
     env: "BROWSERBASE",
     verbose: 1,
+    // @ts-expect-error Type instantiation is excessively deep and possibly infinite
     llmClient: new LangchainClient(
       new ChatOpenAI({
         model: "gpt-4o",

packages/core/examples/custom_client_openai.ts

@@ -6,7 +6,7 @@
  * You will need to reference the Custom OpenAI Client in /external_clients/customOpenAI.ts
  */
 import { Stagehand } from "../lib/v3";
-import { z } from "zod/v3";
+import { z } from "zod";
 import { CustomOpenAIClient } from "./external_clients/customOpenAI";
 import OpenAI from "openai";
 

packages/core/examples/external_clients/customOpenAI.ts

@@ -11,7 +11,6 @@ import {
   LLMClient,
 } from "../../lib/v3";
 import OpenAI from "openai";
-import { zodResponseFormat } from "openai/helpers/zod";
 import type {
   ChatCompletion,
   ChatCompletionAssistantMessageParam,
@@ -22,10 +21,10 @@ import type {
   ChatCompletionSystemMessageParam,
   ChatCompletionUserMessageParam,
 } from "openai/resources/chat/completions";
-import { z } from "zod/v3";
 import { CreateChatCompletionResponseError } from "../../lib/v3";
+import { StagehandZodSchema, toJsonSchema } from "../../lib/v3/zodCompat";
 
-function validateZodSchema(schema: z.ZodTypeAny, data: unknown) {
+function validateZodSchema(schema: StagehandZodSchema, data: unknown) {
   try {
     schema.parse(data);
     return true;
@@ -83,12 +82,18 @@ export class CustomOpenAIClient extends LLMClient {
       );
     }
 
-    let responseFormat = undefined;
+    let responseFormat:
+      | ChatCompletionCreateParamsNonStreaming["response_format"]
+      | undefined;
     if (options.response_model) {
-      responseFormat = zodResponseFormat(
-        options.response_model.schema,
-        options.response_model.name,
-      );
+      const responseModelSchema = options.response_model.schema;
+      responseFormat = {
+        type: "json_schema",
+        json_schema: {
+          name: options.response_model.name,
+          schema: toJsonSchema(responseModelSchema),
+        },
+      };
     }
 
     /* eslint-disable */

packages/core/examples/external_clients/langchain.ts

@@ -4,14 +4,14 @@ import {
   LLMClient,
   AvailableModel,
 } from "../../lib/v3";
-import { zodToJsonSchema } from "zod-to-json-schema";
 import {
   AIMessage,
   BaseMessageLike,
   HumanMessage,
   SystemMessage,
 } from "@langchain/core/messages";
 import { ChatCompletion } from "openai/resources";
+import { toJsonSchema } from "../../lib/v3/zodCompat";
 
 export class LangchainClient extends LLMClient {
   public type = "langchainClient" as const;
@@ -60,9 +60,8 @@ export class LangchainClient extends LLMClient {
     );
 
     if (options.response_model) {
-      const responseSchema = zodToJsonSchema(options.response_model.schema, {
-        $refStrategy: "none",
-      });
+      //ref string no longer needed, this is now default behavior
+      const responseSchema = toJsonSchema(options.response_model.schema);
       const structuredModel = this.model.withStructuredOutput(responseSchema);
       const response = await structuredModel.invoke(formattedMessages);
 

packages/core/examples/operator-example.ts

@@ -5,17 +5,14 @@
  *
  * To learn more about Stagehand Agents, see: https://docs.stagehand.dev/concepts/agent
  */
-
 import { Stagehand } from "../lib/v3";
 import dotenv from "dotenv";
 import chalk from "chalk";
 
 // Load environment variables
 dotenv.config();
-
 async function main() {
   console.log(`\n${chalk.bold("Stagehand 🤘 Operator Example")}\n`);
-
   // Initialize Stagehand
   const stagehand = new Stagehand({
     env: "LOCAL",
@@ -48,5 +45,4 @@ async function main() {
     // await stagehand.close();
   }
 }
-
 main();

packages/core/examples/parameterizeApiKey.ts

@@ -1,5 +1,5 @@
 import { Stagehand } from "../lib/v3";
-import { z } from "zod/v3";
+import { z } from "zod";
 
 /**
  * This example shows how to parameterize the API key for the LLM provider.