Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,