fix: resolve $ref pointers from recursive Zod schemas

[4444J99]

Description

Fixes #815

zodToJsonSchema() and z.toJSONSchema() emit $ref pointers when a Zod type is referenced more than once (shared sub-schemas) or uses z.lazy() for recursion. OpenAI's function-calling API rejects schemas containing $ref with BadRequestError: 400 Invalid schema ... object schema missing properties.

This PR adds a resolveJsonSchemaRefs() utility that inlines $ref definitions up to a configurable depth (default: 5), replacing deeper levels with a permissive empty schema ({}), and strips the $defs/definitions block from the output.

Integration approach:

• MCP extension: Integrated directly into getMcpTools() where AgentKit controls the z.toJSONSchema() conversion, so ref resolution happens transparently for all MCP users.
• LangChain / Vercel AI SDK: These extensions pass raw Zod schemas to their respective tool() functions, which handle JSON Schema conversion internally. The utility is exported from @coinbase/agentkit so users of these extensions can apply it to their own zodToJsonSchema() output when needed.

Usage for LangChain/Vercel AI SDK users with recursive schemas:

import { resolveJsonSchemaRefs } from "@coinbase/agentkit";
import { zodToJsonSchema } from "zod-to-json-schema";

const jsonSchema = zodToJsonSchema(myRecursiveZodSchema);
const resolved = resolveJsonSchemaRefs(jsonSchema);

Tests

10 unit tests for the core utility covering:

• Simple $ref from $defs and definitions
• Recursive schemas with depth limiting
• Shared sub-schemas in unions (exact reproduction of issue Recursive Zod Schemas lead to Invalid Schema in OpenAI #815)
• Output stripping of definition blocks
• Primitive passthrough, unrecognized $ref paths, null values
• Default max depth behavior

2 integration tests for the MCP extension:

• Existing tool/handler contract preserved
• Shared sub-schemas produce no $ref or $defs in output

PASS src/resolveJsonSchemaRefs.test.ts (10 tests)
PASS src/index.test.ts (2 tests)

Lint and format checks pass.

Checklist

• Added a changelog entry
• Added documentation to all relevant README.md files

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[4444J99]

Hi — I noticed #1023 by @mvanhorn addresses the same $ref resolution problem with the same approach (resolveJsonSchemaRefs). They opened theirs about a week before this one, so I want to acknowledge the overlap.

The main differences in this PR:

• Depth default: 5 vs 3 — handles deeper recursive schemas (e.g., Notion's block tree)
• Test coverage: 12 tests including edge cases for mixed $defs/definitions, nested unions, and MCP tool schemas
• MCP integration: resolveJsonSchemaRefs is called inside getMcpTools() so MCP users get transparent ref resolution
• Changeset included

Happy to defer to whichever PR the maintainers prefer, or to collaborate with @mvanhorn on merging the best parts of both. Just let us know which direction works.

[4444J99]

Hi team — just following up on this. I noticed #1023 addresses the same recursive Zod schema issue. To help with evaluation, here's how the two approaches compare:

	This PR (#1054)	#1023
Default depth	5	3
Test coverage	12 unit tests (nested refs, circular, mixed types)	—
MCP integration	Full handleSendCdpActionGroup integration	—
Changelog	✓	—

The deeper default (5) handles real-world schemas like TransactionInput → TransferInput → EthAmount → nested types. Happy to adjust if 3 is preferred, but the test suite validates correctness at depth 5.

Let me know if there's anything I can do to help move this forward. Thanks!