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

Author: omeraplak

.changeset/fix-zod-v4-swagger-records.md

@@ -0,0 +1,8 @@
+---
+"@voltagent/server-hono": patch
+---
+
+fix(server-hono): support Zod v4 record schemas in Swagger docs
+
+The built-in tool OpenAPI schemas now use explicit record key and value schemas so Zod v4 does not
+produce undefined record value types during Swagger document generation.

packages/server-hono/src/app-factory.spec.ts

@@ -1,6 +1,9 @@
+import { TOOL_ROUTES } from "@voltagent/server-core";
 import { cors } from "hono/cors";
 import { describe, expect, it } from "vitest";
+import { z as zodV4 } from "zod/v4";
 import { createApp } from "./app-factory";
+import { OpenApiGeneratorV31 } from "./vendor/zod-to-openapi/v4";
 
 const createDeps = () =>
   ({
@@ -270,6 +273,17 @@ describe("app-factory CORS configuration", () => {
     expect(defaultRes.headers.get("access-control-allow-credentials")).toBe("true");
   });
 
+  it("should generate OpenAPI docs for built-in tool routes", async () => {
+    const { app } = await createApp(createDeps(), {});
+
+    const res = await app.request("/doc");
+    const doc = await res.json();
+
+    expect(res.status).toBe(200);
+    expect(doc.paths[TOOL_ROUTES.listTools.path].get).toBeDefined();
+    expect(doc.paths[TOOL_ROUTES.executeTool.path.replace(":name", "{name}")].post).toBeDefined();
+  });
+
   it("should keep custom routes public in opt-in mode (default)", async () => {
     const mockAuthProvider = {
       verifyToken: async (token: string) => {
@@ -326,3 +340,41 @@ describe("app-factory CORS configuration", () => {
     expect(executionOrder).toEqual(["auth-middleware", "custom-route"]);
   });
 });
+
+describe("Zod v4 OpenAPI compatibility", () => {
+  it("should generate docs for record schemas with explicit key and value types", () => {
+    const schema = zodV4.object({
+      parameters: zodV4.record(zodV4.string(), zodV4.any()).optional(),
+      context: zodV4.record(zodV4.string(), zodV4.any()).optional().default({}),
+    });
+    const route = {
+      method: "post",
+      path: "/tools/{name}/execute",
+      request: {
+        body: {
+          content: {
+            "application/json": {
+              schema,
+            },
+          },
+        },
+      },
+      responses: {
+        200: {
+          description: "Successful response",
+        },
+      },
+    };
+
+    const doc = new OpenApiGeneratorV31([{ type: "route", route }]).generateDocument({
+      openapi: "3.1.0",
+      info: { title: "Zod v4 regression", version: "1.0.0" },
+    });
+
+    const requestSchema =
+      doc.paths["/tools/{name}/execute"].post.requestBody.content["application/json"].schema;
+
+    expect(requestSchema.properties.parameters.additionalProperties).toEqual({});
+    expect(requestSchema.properties.context.additionalProperties).toEqual({});
+  });
+});

packages/server-hono/src/routes/tool.routes.ts

@@ -16,7 +16,7 @@ const ToolDefinitionSchema = z.object({
   id: z.string().optional(),
   name: z.string(),
   description: z.string().optional(),
-  parameters: z.record(z.any()).optional(),
+  parameters: z.record(z.string(), z.any()).optional(),
   status: z.string().optional(),
   agents: z
     .array(
@@ -37,7 +37,7 @@ const ToolListResponseSchema = z.object({
 const ToolExecuteRequestSchema = z
   .object({
     input: z.any().optional().default({}),
-    context: z.record(z.any()).optional().default({}),
+    context: z.record(z.string(), z.any()).optional().default({}),
     userId: z.string().optional(),
     conversationId: z.string().optional(),
   })