fix(core): fall back to zod/v4 JSON schema converter

[pragnyanramtha]

why

Fixes #1845. Stagehand detects v4-shaped schemas by _zod, but toJsonSchema() assumed the root zod import always exposes toJSONSchema(). In bundled/deployed environments where root zod resolves to the transitional v3 surface while user schemas come from zod/v4, extraction can throw Zod v4 toJSONSchema method not found.

what changed

• Import the zod/v4 subpath converter and try it before the root zod converter for v4 schemas.
• Keep the existing v3 zod-to-json-schema path unchanged.
• Add a unit test that mocks root zod without toJSONSchema() while zod/v4 provides it.
• Add a patch changeset for @browserbasehq/stagehand.

test plan

• pnpm --filter @browserbasehq/stagehand run build:esm
• pnpm exec vitest run --config vitest.esm.config.mjs dist/esm/tests/unit/zod-compat.test.js from packages/core
• pnpm --filter @browserbasehq/stagehand run typecheck
• pnpm --filter @browserbasehq/stagehand exec eslint lib/v3/zodCompat.ts tests/unit/zod-compat.test.ts
• pnpm --filter @browserbasehq/stagehand exec prettier --check lib/v3/zodCompat.ts tests/unit/zod-compat.test.ts ../../.changeset/zod-v4-json-schema-fallback.md
• git diff --check

---

Summary by cubic

Add a fallback to the zod/v4 JSON schema converter when the root zod lacks toJSONSchema, preventing “Zod v4 toJSONSchema method not found” errors in bundled builds. Fixes #1845.

• Bug Fixes
  • Use zod/v4’s toJSONSchema before the root zod for v4-shaped schemas.
  • Keep the v3 zod-to-json-schema path unchanged.
  • Add a unit test that mocks root zod without toJSONSchema and verifies the zod/v4 path.
  • Add a patch changeset for @browserbasehq/stagehand.

^{Written for commit c065d0f. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: c065d0f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Caller as Schema Caller
    participant zodCompat as toJsonSchema()
    participant ZodRoot as zod (root)
    participant ZodV4 as zod/v4
    participant ZodToJson as zod-to-json-schema

    Note over Caller,ZodToJson: Schema Type Detection

    Caller->>zodCompat: Call toJsonSchema(schema)
    zodCompat->>zodCompat: Check _zod property

    alt V3 Schema (no _zod)
        zodCompat->>ZodToJson: Convert using zod-to-json-schema
        ZodToJson-->>zodCompat: Return v3 JSON Schema
        zodCompat-->>Caller: Return JSON Schema
    else V4 Schema (_zod present)
        Note over zodCompat,ZodV4: Try zod/v4 first
        zodCompat->>ZodV4: Check .toJSONSchema exists
        alt Has toJSONSchema
            zodCompat->>ZodV4: Call toJSONSchema(schema)
            ZodV4-->>zodCompat: Return v4 JSON Schema
            zodCompat-->>Caller: Return JSON Schema
        else No toJSONSchema on zod/v4
            Note over zodCompat,ZodRoot: Fallback to root zod
            zodCompat->>ZodRoot: Check .toJSONSchema exists
            alt Has toJSONSchema
                zodCompat->>ZodRoot: Call toJSONSchema(schema)
                ZodRoot-->>zodCompat: Return v4 JSON Schema
                zodCompat-->>Caller: Return JSON Schema
            else No toJSONSchema on root zod
                Note over zodCompat: Both converters missing
                zodCompat->>zodCompat: Throw "Zod v4 toJSONSchema method not found"
                zodCompat-->>Caller: Error thrown
            end
        end
    end

Loading

_{Re-trigger cubic}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.