fix(server-hono): support Zod v4 records in Swagger docs

[omeraplak]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://voltagent.dev/docs/community/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://voltagent.dev/docs/community/contributing/#creating-a-changeset

What is the current behavior?

Swagger/OpenAPI generation can fail under Zod v4 for the built-in tool routes. The tool route schemas used single-argument z.record(z.any()), which Zod v4 treats differently and leaves the record value type undefined. The vendored OpenAPI generator then throws Cannot use 'in' operator to search for 'def' in undefined when /doc is requested by Swagger UI.

What is the new behavior?

The built-in tool route schemas now use explicit record key and value schemas via z.record(z.string(), z.any()), which works with both Zod v3 and Zod v4. Added coverage for built-in tool route OpenAPI docs and a Zod v4 record-schema OpenAPI regression test.

fixes Zod v4 Swagger UI crash for built-in tool route schemas

Notes for reviewers

Validated with:

• pnpm --filter @voltagent/server-hono test -- --run
• pnpm biome check packages/server-hono/src/routes/tool.routes.ts packages/server-hono/src/app-factory.spec.ts
• pnpm --filter @voltagent/server-hono build
• Temp zod@4.3.6 OpenAPI generation check

pnpm --filter @voltagent/server-hono typecheck currently fails in this checkout on pre-existing Hono typed-response/status-code route errors outside this change.

---

Summary by cubic

Fixes Swagger/OpenAPI generation crash under Zod v4 for built-in tool routes in @voltagent/server-hono. /doc now renders correctly with Zod v3 and v4.

• Bug Fixes
  • Use explicit record schemas: parameters and context now use z.record(z.string(), z.any()) instead of z.record(z.any()).
  • Add tests to verify built-in tool routes appear in generated OpenAPI and a Zod v4 record-schema regression test with OpenApiGeneratorV31.
  • Resolves the Swagger UI /doc error: Cannot use 'in' operator to search for 'def' in undefined.

^{Written for commit 0751299. Summary will update on new commits.}

Summary by CodeRabbit

• Bug Fixes

  • Fixed OpenAPI/Swagger documentation generation to correctly handle Zod v4 record schemas, ensuring accurate schema definitions in generated API documentation.

• Tests

  • Added test coverage for OpenAPI schema generation and Zod v4 compatibility validation.

[changeset-bot]

🦋 Changeset detected

Latest commit: 0751299

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

This PR includes changesets to release 1 package

Name	Type
@voltagent/server-hono	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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7248d6ed-3ea1-409c-89b0-bd9890339b06

📥 Commits

Reviewing files that changed from the base of the PR and between 8b8c238 and 0751299.

📒 Files selected for processing (3)

• .changeset/fix-zod-v4-swagger-records.md
• packages/server-hono/src/app-factory.spec.ts
• packages/server-hono/src/routes/tool.routes.ts

---

📝 Walkthrough

Walkthrough

This pull request fixes Swagger/OpenAPI generation for Zod v4 record schemas by updating route schemas to use explicit key-value record types (z.record(z.string(), z.any())) and adding test coverage to verify OpenAPI document generation and Zod v4 compatibility.

Changes

Cohort / File(s)	Summary
Changeset Documentation .changeset/fix-zod-v4-swagger-records.md	Documents a patch-level fix for @voltagent/server-hono addressing Swagger/OpenAPI generation with Zod v4 record schemas to emit explicit key and value schemas.
Test Coverage packages/server-hono/src/app-factory.spec.ts	Adds OpenAPI integration tests verifying /doc endpoint returns correct route definitions and validates that Zod v4 record-typed properties (parameters, context) emit with additionalProperties: {} in OpenAPI schemas.
Route Schema Updates packages/server-hono/src/routes/tool.routes.ts	Updates Zod record definitions for parameters and context fields from single-argument form z.record(z.any()) to explicit key-value form z.record(z.string(), z.any()) for Zod v4 compatibility.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fix: make workspace toolkit schemas compatible with Zod v4 record han… #1058: Implements the same Zod v4 compatibility change by converting z.record() calls from single-argument to key-value form across the codebase.

Poem

🐰 With v4 records so bright,
Keys and values aligned just right,
Swagger schemas dance with cheer,
No more undefined to fear,
Documentation shines in light! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: fixing Zod v4 support for records in Swagger documentation generation.
Description check	✅ Passed	The description covers all key sections including current behavior, new behavior, tests added, changesets, and comprehensive validation notes, matching the template requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/zod-v4-swagger-records

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 3 files