feat(codemode): support AI SDK jsonSchema wrapper + production-harden schema converter

[mattzcarey]

Summary

This PR makes codemode's generateTypes() work with AI SDK jsonSchema() wrappers (from MCP tools) and hardens the entire JSON Schema → TypeScript conversion pipeline so it never crashes regardless of input.

Before: generateTypes() only worked with Zod schemas. MCP tools using jsonSchema() wrappers silently produced unknown types. No protection against recursive schemas, malformed input, or special characters.

After: Full support for both Zod and jsonSchema() wrappers with direct JSON Schema → TypeScript conversion (~6µs vs ~32µs for Zod). The converter handles $ref, circular schemas, deeply nested schemas, tuple types, nullable types, and special characters without crashing.

What changed

packages/codemode/src/types.ts (+568 lines)

Schema detection & extraction:

• isJsonSchemaWrapper() / extractJsonSchema() — detect and unwrap AI SDK jsonSchema() wrappers (both direct property and symbol-based storage)
• isZodSchema() — detect Zod schemas via _zod property
• safeSchemaToTs() — routes to zodToTs or direct conversion based on schema type

Direct JSON Schema → TypeScript converter (jsonSchemaToTypeString):

• Handles: string, number, integer, boolean, null, object, array, enum, const, anyOf, oneOf, allOf, type arrays (["string", "null"])
• ConversionContext threading through all recursive calls (root schema, depth counter, visited set, max depth)

Safety & correctness:

• $ref resolution — resolveRef() handles internal JSON Pointers (#/definitions/..., #/$defs/..., #), JSON Pointer unescaping (~0/~1). External URLs degrade to unknown
• Depth guard — returns unknown at depth 20
• Circular reference guard — Set<unknown> tracks visited schema objects, returns unknown on cycles
• Tuple support — prefixItems (JSON Schema 2020-12) and items as array (draft-07) → [T1, T2, ...]
• OpenAPI 3.0 nullable: true — applyNullable() applied across all branches including $ref
• additionalProperties: false — empty object with no additional properties returns {} instead of Record<string, unknown>
• Empty enum — enum: [] produces never instead of invalid TypeScript
• Object/array enum & const values — JSON.stringify() instead of String() (which produced [object Object])
• String escaping — escapeStringLiteral() for \n, \r, \t, control chars, U+2028/U+2029 in enum/const values; quoteProp() for property names; escapeJsDoc() for */ in JSDoc
• Newline normalization — \r?\n → spaces in descriptions before JSDoc emission
• @format as JSDoc hint — JSON Schema format keyword emitted as @format tag; multi-line JSDoc when combined with description
• Per-tool error isolation — try-catch in generateTypes() loop; one bad tool emits unknown types without crashing the pipeline
• Null guard on inputSchema — missing schema produces empty param descriptions instead of throwing
• Null guard in extractDescriptions — guards typeof null === "object" edge case

packages/agents/src/mcp/client.ts (+25/-7)

• Per-tool error isolation in getAITools() — replaced .map() with for-loop + try-catch; bad tools logged via console.warn and skipped
• Guard tool.inputSchema — missing schema falls back to { type: "object" }

packages/codemode/src/tests/schema-conversion.test.ts (new, 42 tests)

Group	Tests
jsonSchema wrapper basics	8 (object, nested, arrays, enums, required/optional, descriptions, anyOf, output schema)
Zod schema basics	2
$ref resolution	5 ($defs, definitions, unresolvable, external URL, nested chains)
Circular schemas	2 (self-ref, 30-level deep nesting)
Property name safety	3 (control chars, quotes, empty string)
JSDoc safety	2 (*/ in property and tool descriptions)
Tuple support	2 (draft-07 items array, 2020-12 prefixItems)
Nullable	2 (with/without nullable: true)
allOf / oneOf	2 (intersection, 3+ member union)
Enum/const escaping	3 (special chars, null, const escaping)
additionalProperties: false	2 (empty {} vs Record<string, unknown>)
Enum/const object values	3 (object enum, array enum, object const via JSON.stringify)
Multi-line JSDoc @format	2 (desc+format multi-line, format-only single-line)
Newline normalization	2 (property descriptions, tool descriptions)
Codemode declaration	2 (structure, name sanitization)

packages/codemode/src/tests/types.test.ts (new, 24 tests)

Covers: Zod tools, jsonSchema tools, mixed tools, tool name sanitization, description/JSDoc, edge cases (hyphenated names, reserved words, digit-leading names), malformed input (null/undefined/string inputSchema), error isolation (throwing tool doesn't break others).

Stress testing

Tested against 51 schemas from real-world MCP servers and adversarial inputs:

Real MCP servers: Cloudflare Workers, DynamoDB, Docker, Filesystem, Playwright, Kubernetes, Home Assistant, Obsidian, Stagehand

Adversarial inputs: Self-referencing $ref, 25-level nesting, circular A→B→A refs, __proto__ property names, JSDoc-breaking */ descriptions, empty enums, external URL refs, boolean schemas, null/undefined/string inputSchema

All 51 pass without crashes.

Performance

Operation	Time
MCP getAITools()	~0.25 µs/schema
generateTypes() with jsonSchema	~6 µs
generateTypes() with Zod	~32 µs

Known limitations

• __proto__ as a property name is silently dropped by the JS engine (object literals only — JSON.parse() from MCP wire protocol is unaffected)
• External $ref URLs, not, if/then/else, patternProperties are out of scope and degrade to unknown
• format keyword is emitted as a @format JSDoc hint, not as a refined TypeScript type

Test plan

• 66 new codemode tests pass (42 schema-conversion + 24 types)
• 89 total codemode tests pass
• Formatting: 0 issues
• Linting (oxlint): 0 errors
• Typecheck: 0 new errors (pre-existing glm-4.7-flash only)
• 51 real-world + adversarial schemas pass without crashes

[changeset-bot]

🦋 Changeset detected

Latest commit: 0ee5368

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

This PR includes changesets to release 2 packages

Name	Type
@cloudflare/codemode	Patch
agents	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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@960

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/ai-chat@960

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/codemode@960

npm i https://pkg.pr.new/cloudflare/agents/hono-agents@960

commit: 0ee5368

[mattzcarey]

Performance Analysis: jsonSchema() vs fromJSONSchema()

Profiled the performance impact of switching from AI SDK's jsonSchema() to Zod v4's fromJSONSchema():

Metric	fromJSONSchema()	jsonSchema()	Ratio
Simple schema (2 props)	25 µs	0.25 µs	~100x slower
Complex MCP schema	151 µs	0.22 µs	~685x slower
Deeply nested (5 levels)	89 µs	0.26 µs	~342x slower
Memory per schema	~559 KB	~1 KB	~559x more

What this means in practice

For a typical MCP server with 10 tools:

• fromJSONSchema(): ~1.5ms startup + ~5.5MB memory
• jsonSchema(): ~0.002ms startup + ~10KB memory

However, this cost is paid once when getAITools() is called, not per-request. After initialization:

• Validation is fast: ~1 µs per call
• Schemas are cached in the returned tool definitions

Why we need fromJSONSchema()

• jsonSchema() creates a thin wrapper without _zod property
• fromJSONSchema() creates a real Zod schema with _zod property
• The _zod property is required for zod-to-ts which codemode uses for type generation

Recommendation

keep jsonSchema and build a parser to support it.

[mattzcarey]

Stress Testing Findings

Ran generateTypes against 51 schemas — real-world MCP servers (Cloudflare Workers, DynamoDB, Docker, Filesystem, Playwright, Kubernetes, Home Assistant, Obsidian, Stagehand) plus adversarial inputs. All pass.

Bugs found and fixed

Issue	Fix
nullable: true on a $ref property was silently lost	applyNullable() now wraps the resolved ref result
Empty enum: [] produced val?: ; (invalid TS)	Returns never for empty enums
nullable wasn't applied to anyOf/oneOf/allOf/enum/const branches	All branches now go through applyNullable()
escapeStringLiteral missed newlines, control chars, U+2028/U+2029	Character-level loop escapes everything
*/ in descriptions broke JSDoc comments	escapeJsDoc() applied to all descriptions
format keyword (email, date-time, uuid) was silently dropped	Now emitted as @format JSDoc hint

Known limitations (cannot fix in converter)

• __proto__ as a property name is silently dropped by the JS engine when using object literals. JSON.parse() (i.e., schemas arriving from MCP wire protocol) is unaffected.

Out of scope (by design, degrade to unknown)

• External $ref URLs — security risk
• not, if/then/else — no clean TS equivalent
• patternProperties — rare, complex
• dependencies / dependentRequired — conditional requirements can't be expressed in TS types

[threepointone]

Added a few more tests, and addressed this gap:

Boolean property schemas silently dropped
In JSON Schema, { "foo": true } means foo accepts any value, { "foo": false } means foo accepts nothing. These should map to unknown and never, not be skipped entirely. Properties with boolean schemas will vanish from the generated type.

---

Approving, land if my above thing makes sense to you (look at my commit)