The Open Framework for Building Agents
fix(eve): tool schemas - degrade unsupported JSON Schemas instead of failing the turn (#934)
Andrew Barbad9c49fc16d0a
diff --git a/.changeset/fix-mcp-schema-validation.md b/.changeset/fix-mcp-schema-validation.mdnew file mode 100644index 000000000..088907d34--- /dev/null+++ b/.changeset/fix-mcp-schema-validation.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Tool schemas that cannot be rehydrated into local validators no longer fail the turn. Serialized JSON Schemas first retry rehydration as JSON Schema 2020-12 (so MCP `$defs` references validate correctly), and schemas outside the supported conversion subset (such as inline JSON Pointer `$ref`s) are now advertised to the model unchanged with validation left to the tool's own executor — OpenAPI operations with such schemas are kept instead of omitted.diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.tsindex 55d16d49c..3081db722 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts@@ -1,3 +1,4 @@+import { asSchema } from "ai";import { describe, expect, it, vi } from "vitest";import type { DynamicToolEntry } from "#shared/dynamic-tool-definition.js";@@ -498,6 +499,54 @@ function createReplayableTool(}describe("dispatchDynamicToolEvent", () => {+ it("leaves unsupported connection input schemas for the MCP server to validate", async () => {+ const ctx = createCtx();+ const inputSchema = {+ properties: {+ filters: {+ anyOf: [+ { properties: { source: { type: "string" } }, type: "object" },+ {+ properties: {+ source: { $ref: "#/properties/filters/anyOf/0/properties/source" },+ },+ type: "object",+ },+ ],+ },+ },+ type: "object",+ };+ const resolver = createResolver("connection", ["step.started"], () => ({+ remote: {+ description: "remote tool",+ inputSchema,+ execute: async (): Promise<unknown> => ({ ok: true }),+ },+ }));++ await dispatchDynamicToolEvent({+ ctx,+ resolvers: [resolver],+ messages: [],+ event: makeEvent("step.started"),+ });++ const tools = buildDynamicTools(ctx);+ expect(tools).toHaveLength(1);++ // The advertised schema preserves the source verbatim, including the+ // inline JSON Pointer $ref that zod cannot rehydrate.+ const schema = asSchema(tools[0]!.inputSchema);+ expect(schema.jsonSchema).toMatchObject(inputSchema);++ // Local validation is a passthrough — the MCP server stays responsible.+ await expect(schema.validate?.({ filters: { source: "octolens" } })).resolves.toEqual({+ success: true,+ value: { filters: { source: "octolens" } },+ });+ });+it("resolves tools for matching event and stores on scoped durable key", async () => {const ctx = createCtx();const resolver = createResolver("weather", ["session.started"], () => ({diff --git a/packages/eve/src/runtime/connections/openapi-client.test.ts b/packages/eve/src/runtime/connections/openapi-client.test.tsindex e7c5d09a1..42367ba16 100644--- a/packages/eve/src/runtime/connections/openapi-client.test.ts+++ b/packages/eve/src/runtime/connections/openapi-client.test.ts@@ -667,7 +667,7 @@ describe("OpenApiConnectionClient", () => {expect(props.mix?.type).toEqual(["string", "null"]);});- it("omits only operations whose input schemas cannot be rehydrated", async () => {+ it("keeps operations whose input schemas cannot be locally validated", async () => {const spec: Record<string, unknown> = {openapi: "3.0.3",info: { title: "T", version: "1" },@@ -691,10 +691,14 @@ describe("OpenApiConnectionClient", () => {};const client = new OpenApiConnectionClient(makeConnection({ spec }));- await expect(client.getToolMetadata()).resolves.toMatchObject([{ name: "getValid" }]);+ // Schemas outside the local validation subset degrade to passthrough+ // validation instead of dropping the operation — the API validates.+ await expect(client.getToolMetadata()).resolves.toMatchObject([+ { name: "getValid" },+ { name: "getInvalid" },+ ]);await expect(client.getTools()).resolves.toHaveProperty("getValid");- await expect(client.getTools()).resolves.not.toHaveProperty("getInvalid");- await expect(client.executeTool("getInvalid", {})).rejects.toThrow(/not found/);+ await expect(client.getTools()).resolves.toHaveProperty("getInvalid");});it("parses a YAML spec fetched from a URL", async () => {diff --git a/packages/eve/src/shared/tool-schema.test.ts b/packages/eve/src/shared/tool-schema.test.tsindex 23eef4c35..048e8136e 100644--- a/packages/eve/src/shared/tool-schema.test.ts+++ b/packages/eve/src/shared/tool-schema.test.ts@@ -46,8 +46,64 @@ describe("ToolSchema", () => {});});- it("rejects malformed serialized schemas at the runtime boundary", () => {- expect(() => toInputSchema({ type: "not-a-json-schema-type" })).toThrow();+ it("rehydrates draft 2020-12 $defs references with real validation", async () => {+ const schema = toInputSchema({+ $defs: { item: { type: "string" } },+ properties: { item: { $ref: "#/$defs/item" } },+ required: ["item"],+ type: "object",+ });+ const validate = asSchema(schema).validate;++ await expect(validate?.({ item: 42 })).resolves.toMatchObject({ success: false });+ await expect(validate?.({ item: "ok" })).resolves.toMatchObject({ success: true });+ });++ it("degrades schemas outside zod's conversion subset to validation-free passthrough", async () => {+ // Valid JSON Schema with an inline JSON Pointer $ref that zod's converter+ // rejects (it only resolves #, #/definitions/*, and #/$defs/*).+ const source = {+ properties: {+ filters: {+ anyOf: [+ { properties: { source: { type: "string" } }, type: "object" },+ {+ properties: {+ source: { $ref: "#/properties/filters/anyOf/0/properties/source" },+ },+ type: "object",+ },+ ],+ },+ },+ type: "object",+ };+ const schema = toInputSchema(source);++ expect(isToolSchema(schema)).toBe(true);+ // The source JSON Schema is advertised verbatim.+ expect(serializeInputSchema(schema)).toEqual(source);+ // Validation accepts any input — the tool's executor validates instead.+ await expect(asSchema(schema).validate?.({ filters: { source: 42 } })).resolves.toEqual({+ success: true,+ value: { filters: { source: 42 } },+ });+ });++ it("emits fresh copies from a passthrough schema so consumers cannot mutate the source", () => {+ const source = { properties: { x: { $ref: "#/properties/y" } }, type: "object" };+ const schema = toInputSchema(source);++ // asSchema's standardSchema path mutates the emitted JSON Schema in place.+ const emitted = asSchema(schema).jsonSchema as { additionalProperties?: boolean };++ expect(emitted.additionalProperties).toBe(false);+ expect(source).toEqual({ properties: { x: { $ref: "#/properties/y" } }, type: "object" });+ expect(serializeInputSchema(schema)).toEqual(source);+ });++ it("degrades malformed serialized schemas instead of failing the boundary", () => {+ expect(isToolSchema(toInputSchema({ type: "not-a-json-schema-type" }))).toBe(true);});it("preserves a live validated schema", () => {diff --git a/packages/eve/src/shared/tool-schema.ts b/packages/eve/src/shared/tool-schema.tsindex b7f11f11f..540b7ea9c 100644--- a/packages/eve/src/shared/tool-schema.ts+++ b/packages/eve/src/shared/tool-schema.ts@@ -4,6 +4,7 @@ import type {} from "#compiled/@standard-schema/spec/index.js";import { z } from "#compiled/zod/index.js";+import { toErrorMessage } from "#shared/errors.js";import { parseJsonObject, type JsonObject } from "#shared/json.js";/**@@ -37,7 +38,9 @@ const rehydratedSchemas: Record<SchemaDirection, WeakMap<object, ToolSchema>> =/*** Resolves a source into a live input {@link ToolSchema}. Live schemas pass* through unchanged; serialized JSON Schemas are rehydrated into vendored Zod- * validators. `null` and `undefined` pass through untouched.+ * validators. Serialized schemas outside Zod's conversion subset degrade to a+ * validation-free schema that still advertises the source JSON Schema. `null`+ * and `undefined` pass through untouched.*/export function toInputSchema<T extends ToolSchemaSource | null | undefined>(source: T,@@ -48,7 +51,9 @@ export function toInputSchema<T extends ToolSchemaSource | null | undefined>(/*** Resolves a source into a live output {@link ToolSchema}. Live schemas pass* through unchanged; serialized JSON Schemas are rehydrated into vendored Zod- * validators. `null` and `undefined` pass through untouched.+ * validators. Serialized schemas outside Zod's conversion subset degrade to a+ * validation-free schema that still advertises the source JSON Schema. `null`+ * and `undefined` pass through untouched.*/export function toOutputSchema<T extends ToolSchemaSource | null | undefined>(source: T,@@ -118,17 +123,63 @@ function toSchema(const cache = rehydratedSchemas[direction];let resolved = cache.get(source);if (resolved === undefined) {- const jsonSchema = toJsonObject(source, direction);- // The rehydration target must match JSON_SCHEMA_TARGET: serialized- // schemas strip `$schema`, so zod would otherwise assume draft-2020-12.- resolved = z.fromJSONSchema(jsonSchema as Parameters<typeof z.fromJSONSchema>[0], {- defaultTarget: "draft-7",- }) as ToolSchema;+ resolved = rehydrateJsonSchema(toJsonObject(source, direction));cache.set(source, resolved);}return resolved;}+type FromJsonSchemaSource = Parameters<typeof z.fromJSONSchema>[0];++function rehydrateJsonSchema(jsonSchema: JsonObject): ToolSchema {+ // The first rehydration target must match JSON_SCHEMA_TARGET: serialized+ // schemas strip `$schema`, so zod would otherwise assume draft-2020-12.+ try {+ return z.fromJSONSchema(jsonSchema as FromJsonSchemaSource, {+ defaultTarget: "draft-7",+ }) as ToolSchema;+ } catch {+ // Retry below with the dialect raw remote schemas actually use.+ }++ // MCP declares tool schemas as JSON Schema 2020-12, where `$defs` replaces+ // draft-07 `definitions`, so raw remote schemas get a second pass here.+ try {+ return z.fromJSONSchema(jsonSchema as FromJsonSchemaSource, {+ defaultTarget: "draft-2020-12",+ }) as ToolSchema;+ } catch (error) {+ // Valid JSON Schema can exceed zod's conversion subset (inline JSON+ // Pointer $refs, conditionals, unevaluated* keywords). Advertise the+ // schema unchanged without local validation — the tool's executor (e.g.+ // the remote MCP server) still validates input — rather than letting one+ // incompatible tool schema fail the whole turn.+ console.warn(+ "[eve] Tool schema uses JSON Schema features outside local validation support; " ++ `passing input through unvalidated: ${toErrorMessage(error)}`,+ );+ return toPassthroughSchema(jsonSchema);+ }+}++/**+ * Validation-free {@link ToolSchema} that advertises the source JSON Schema+ * verbatim and accepts any input. Emission returns a fresh copy per call so+ * consumers that mutate emitted schemas cannot corrupt durable sources.+ */+function toPassthroughSchema(jsonSchema: JsonObject): ToolSchema {+ const emit = (): Record<string, unknown> =>+ structuredClone(jsonSchema) as Record<string, unknown>;+ return {+ "~standard": {+ version: 1,+ vendor: "eve",+ validate: (value: unknown) => ({ value }),+ jsonSchema: { input: emit, output: emit },+ },+ };+}+function serializeSchema(source: ToolSchemaSource | null | undefined,direction: SchemaDirection,