Skip to content

Commit 18510c4

Browse files
authored
fix(llm-proxy): sanitize non-string enums in Gemini tool schemas (archestra-ai#5407)
## Problem Chat with `gemini-2.5-pro` + MCP tools fails with HTTP 400 `INVALID_ARGUMENT`: ``` Invalid value at 'tools[0].function_declarations[0].parameters .properties[2].value.any_of[0].properties[0].value.enum[0]' (TYPE_STRING), true ``` Gemini's `function_declaration` schema validation only permits `enum` on **string-typed** fields. A boolean `true` inside `enum` is rejected. ## Root cause `@ai-sdk/google` (verified in installed `3.0.43` and latest `3.0.80`) converts a zod `const: true` (e.g. a boolean acknowledgement flag / discriminated-union discriminator) into `enum: [true]` and never coerces enum values to strings: ```js if (constValue !== void 0) { result.enum = [constValue]; } // const -> enum, verbatim if (enumValues !== void 0) { result.enum = enumValues; } // enum verbatim, no coercion ``` The proxy then forwarded `fd.parameters` verbatim through `@google/genai` to Gemini in `restToSdkGenerateContentParams`, so the boolean enum reached Gemini unchanged. Bumping the AI SDK would **not** fix this (latest has identical handling), and the proxy also serves external clients, so sanitizing in the proxy is the correct layer. ## Fix A recursive sanitizer (`gemini-schema.ts`) applied at the single chokepoint `restToSdkGenerateContentParams` — shared by both the native-Gemini and OpenAI-compat-to-Gemini paths. For any schema node with an empty or non-string `enum`: - drop the `enum` (Gemini cannot express the literal anyway); - preserve the existing `type`, or infer a safe one from the values (null-only/heterogeneous → `string`, all-float → `number`); - fold the dropped literal(s) into `description` (e.g. *"Value must be `true`."*) so the model keeps the hint. Valid string enums are left untouched. The walk covers all JSON-schema applicator keywords (`properties`, `anyOf`/`oneOf`/`allOf`, `items`/`prefixItems`, `$defs`/`definitions`, `additionalProperties`, `dependencies`/`dependentSchemas`, `unevaluatedItems`, `if`/`then`/`else`, `not`, `contains`, ...) and never recurses into data-bearing keys (`enum`/`const`/`default`/`examples`). ### Why drop, not stringify For tool params forwarded to a strict MCP server, stringifying (`type:string, enum:["true"]`) would make the model emit `"true"` and break downstream validation. Dropping keeps the correct JSON type. ## Tests - `gemini-schema.test.ts` — reported `anyOf` shape, boolean/numeric/empty/mixed/untyped enums, type inference, description folding, recursion into `items`/`$defs`/`dependencies`/`unevaluatedItems`, no input mutation. - `gemini.test.ts` — wiring: all four fd schema fields (`parameters`, `parametersJsonSchema`, `response`, `responseJsonSchema`) sanitized on the outbound path, plus the no-parameters short-circuit. `type-check`, `lint`, full `knip` all clean. --- <!-- archestra-banner:v1 --> <a href="https://archestra.ai/contributor-onboard" rel="nofollow noreferrer noopener" target="_blank"> <img alt="Archestra Contributor" src="https://raw.githubusercontent.com/archestra-ai/archestra/main/docs/assets/archestra-contributor-banner.webp"/> </a> ## References / prior art - Vercel AI SDK — [`convert-json-schema-to-openapi-schema.ts`](https://github.com/vercel/ai/blob/main/packages/google/src/convert-json-schema-to-openapi-schema.ts): rewrites `const` → `enum: [const]` and passes `enum` through verbatim (no string coercion) — the upstream source of the boolean enum. - Gemini API — [structured output / enum docs](https://ai.google.dev/gemini-api/docs/structured-output): `enum` is only valid on `STRING`-typed fields. - [Google AI forum: Gemini rejecting enum schema (Zod cannot set `type: "string"`)](https://discuss.ai.google.dev/t/gemini-rejecting-enum-schema-zod-cannot-set-type-string/90681) - [`gemini-cli` archestra-ai#2237](google-gemini/gemini-cli#2237): only `enum`/`date-time` supported for STRING type — same class of validation. - [`opencode` #12784](anomalyco/opencode#12784): handles the same problem by **stringifying** numeric enums. We deliberately **drop** instead: stringifying changes the JSON type the model emits, which breaks tool args validated by a strict downstream MCP server. Dropping preserves the type and keeps the literal as a description hint.
1 parent a66852f commit 18510c4

4 files changed

Lines changed: 404 additions & 6 deletions

File tree

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
import { describe, expect, it } from "vitest";
2+
import { sanitizeGeminiToolSchema } from "./gemini-schema";
3+
4+
describe("sanitizeGeminiToolSchema", () => {
5+
it("removes a boolean enum nested in anyOf (the reported failure shape)", () => {
6+
const schema = {
7+
type: "object",
8+
properties: {
9+
a: { type: "string" },
10+
b: { type: "string" },
11+
flag: {
12+
anyOf: [
13+
{
14+
type: "object",
15+
properties: {
16+
discriminator: { type: "boolean", enum: [true] },
17+
},
18+
},
19+
{ type: "string" },
20+
],
21+
},
22+
},
23+
};
24+
25+
expect(sanitizeGeminiToolSchema(schema)).toEqual({
26+
type: "object",
27+
properties: {
28+
a: { type: "string" },
29+
b: { type: "string" },
30+
flag: {
31+
anyOf: [
32+
{
33+
type: "object",
34+
properties: {
35+
discriminator: {
36+
type: "boolean",
37+
description: "Value must be `true`.",
38+
},
39+
},
40+
},
41+
{ type: "string" },
42+
],
43+
},
44+
},
45+
});
46+
});
47+
48+
it("drops a numeric enum but keeps the numeric type", () => {
49+
expect(
50+
sanitizeGeminiToolSchema({ type: "number", enum: [1, 2, 3] }),
51+
).toEqual({
52+
type: "number",
53+
description: "Value must be one of: `1`, `2`, `3`.",
54+
});
55+
});
56+
57+
it("infers the type from the first value when none is declared", () => {
58+
expect(sanitizeGeminiToolSchema({ enum: [true] })).toEqual({
59+
type: "boolean",
60+
description: "Value must be `true`.",
61+
});
62+
expect(sanitizeGeminiToolSchema({ enum: [7] })).toEqual({
63+
type: "integer",
64+
description: "Value must be `7`.",
65+
});
66+
expect(sanitizeGeminiToolSchema({ enum: [1.5] })).toEqual({
67+
type: "number",
68+
description: "Value must be `1.5`.",
69+
});
70+
});
71+
72+
it("appends the constraint to an existing description", () => {
73+
expect(
74+
sanitizeGeminiToolSchema({
75+
type: "boolean",
76+
enum: [true],
77+
description: "Acknowledgement.",
78+
}),
79+
).toEqual({
80+
type: "boolean",
81+
description: "Acknowledgement. Value must be `true`.",
82+
});
83+
});
84+
85+
it("drops mixed enums entirely", () => {
86+
expect(
87+
sanitizeGeminiToolSchema({ type: "string", enum: ["a", 1] }),
88+
).toEqual({
89+
type: "string",
90+
description: "Value must be one of: `a`, `1`.",
91+
});
92+
});
93+
94+
it("infers a safe type for null-only and heterogeneous untyped enums", () => {
95+
// typeof null === "object" must not leak as type "object"
96+
expect(sanitizeGeminiToolSchema({ enum: [null] })).toEqual({
97+
type: "string",
98+
description: "Value must be `null`.",
99+
});
100+
// mixed value types fall back to string rather than the first value's type
101+
expect(sanitizeGeminiToolSchema({ enum: [1, "a"] })).toEqual({
102+
type: "string",
103+
description: "Value must be one of: `1`, `a`.",
104+
});
105+
// all-float numeric set stays number, not integer
106+
expect(sanitizeGeminiToolSchema({ enum: [1, 1.5] })).toEqual({
107+
type: "number",
108+
description: "Value must be one of: `1`, `1.5`.",
109+
});
110+
});
111+
112+
it("recurses into dependencies and unevaluatedItems subschemas", () => {
113+
expect(
114+
sanitizeGeminiToolSchema({
115+
type: "object",
116+
dependencies: {
117+
a: { type: "boolean", enum: [true] },
118+
b: ["c"],
119+
},
120+
unevaluatedItems: { type: "boolean", enum: [false] },
121+
}),
122+
).toEqual({
123+
type: "object",
124+
dependencies: {
125+
a: { type: "boolean", description: "Value must be `true`." },
126+
b: ["c"],
127+
},
128+
unevaluatedItems: {
129+
type: "boolean",
130+
description: "Value must be `false`.",
131+
},
132+
});
133+
});
134+
135+
it("drops an empty enum without adding a description", () => {
136+
expect(sanitizeGeminiToolSchema({ type: "string", enum: [] })).toEqual({
137+
type: "string",
138+
});
139+
});
140+
141+
it("leaves valid string enums untouched", () => {
142+
const schema = { type: "string", enum: ["red", "green", "blue"] };
143+
expect(sanitizeGeminiToolSchema(schema)).toEqual(schema);
144+
});
145+
146+
it("recurses into items and $defs", () => {
147+
expect(
148+
sanitizeGeminiToolSchema({
149+
type: "array",
150+
items: { type: "boolean", enum: [true] },
151+
$defs: { Flag: { type: "boolean", enum: [false] } },
152+
}),
153+
).toEqual({
154+
type: "array",
155+
items: { type: "boolean", description: "Value must be `true`." },
156+
$defs: {
157+
Flag: { type: "boolean", description: "Value must be `false`." },
158+
},
159+
});
160+
});
161+
162+
it("passes through non-schema inputs", () => {
163+
expect(sanitizeGeminiToolSchema("text")).toBe("text");
164+
expect(sanitizeGeminiToolSchema(42)).toBe(42);
165+
expect(sanitizeGeminiToolSchema(null)).toBe(null);
166+
expect(sanitizeGeminiToolSchema([1, 2])).toEqual([1, 2]);
167+
});
168+
169+
it("does not mutate the input", () => {
170+
const schema = {
171+
type: "object",
172+
properties: { flag: { type: "boolean", enum: [true] } },
173+
};
174+
const snapshot = structuredClone(schema);
175+
sanitizeGeminiToolSchema(schema);
176+
expect(schema).toEqual(snapshot);
177+
});
178+
});
Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
// Gemini's tool/function schema validation only permits `enum` on string-typed
2+
// fields. JSON schemas produced upstream (e.g. `@ai-sdk/google` rewrites a zod
3+
// `const: true` into `enum: [true]`) can carry boolean/number enums, which Gemini
4+
// rejects with 400 INVALID_ARGUMENT. This sanitizer walks a tool parameter schema
5+
// and removes non-string enums while preserving the value type, folding the dropped
6+
// literal(s) into the field description so the model keeps the hint.
7+
8+
type SchemaObject = Record<string, unknown>;
9+
10+
// keywords whose value is a single subschema (recurse only when it is an object)
11+
const SINGLE_SUBSCHEMA_KEYS = [
12+
"additionalProperties",
13+
"unevaluatedProperties",
14+
"propertyNames",
15+
"contains",
16+
"not",
17+
"if",
18+
"then",
19+
"else",
20+
"unevaluatedItems",
21+
] as const;
22+
23+
// keywords whose value is a map of named subschemas
24+
const SUBSCHEMA_MAP_KEYS = [
25+
"properties",
26+
"patternProperties",
27+
"$defs",
28+
"definitions",
29+
"dependentSchemas",
30+
// draft-07 `dependencies` may hold subschemas (or property-name arrays, which
31+
// pass through the walk unchanged)
32+
"dependencies",
33+
] as const;
34+
35+
// keywords whose value is an array of subschemas
36+
const SUBSCHEMA_ARRAY_KEYS = [
37+
"anyOf",
38+
"oneOf",
39+
"allOf",
40+
"prefixItems",
41+
] as const;
42+
43+
export function sanitizeGeminiToolSchema(schema: unknown): unknown {
44+
if (Array.isArray(schema)) {
45+
return schema.map(sanitizeGeminiToolSchema);
46+
}
47+
if (schema === null || typeof schema !== "object") {
48+
return schema;
49+
}
50+
51+
const result: SchemaObject = { ...(schema as SchemaObject) };
52+
normalizeEnum(result);
53+
recurseSubschemas(result);
54+
return result;
55+
}
56+
57+
function normalizeEnum(node: SchemaObject): void {
58+
const enumValues = node.enum;
59+
if (!Array.isArray(enumValues)) return;
60+
if (enumValues.length > 0 && enumValues.every((v) => typeof v === "string")) {
61+
return;
62+
}
63+
64+
delete node.enum;
65+
66+
if (node.type === undefined && enumValues.length > 0) {
67+
node.type = inferType(enumValues);
68+
}
69+
70+
if (enumValues.length > 0) {
71+
node.description = appendConstraint(node.description, enumValues);
72+
}
73+
}
74+
75+
function recurseSubschemas(node: SchemaObject): void {
76+
for (const key of SUBSCHEMA_MAP_KEYS) {
77+
const map = node[key];
78+
if (map !== null && typeof map === "object" && !Array.isArray(map)) {
79+
const sanitized: SchemaObject = {};
80+
for (const [name, sub] of Object.entries(map)) {
81+
sanitized[name] = sanitizeGeminiToolSchema(sub);
82+
}
83+
node[key] = sanitized;
84+
}
85+
}
86+
87+
for (const key of SUBSCHEMA_ARRAY_KEYS) {
88+
const arr = node[key];
89+
if (Array.isArray(arr)) {
90+
node[key] = arr.map(sanitizeGeminiToolSchema);
91+
}
92+
}
93+
94+
// `items` and `additionalItems` may be a single subschema or an array of them
95+
for (const key of ["items", "additionalItems"] as const) {
96+
const value = node[key];
97+
if (Array.isArray(value)) {
98+
node[key] = value.map(sanitizeGeminiToolSchema);
99+
} else if (value !== null && typeof value === "object") {
100+
node[key] = sanitizeGeminiToolSchema(value);
101+
}
102+
}
103+
104+
for (const key of SINGLE_SUBSCHEMA_KEYS) {
105+
const value = node[key];
106+
if (value !== null && typeof value === "object" && !Array.isArray(value)) {
107+
node[key] = sanitizeGeminiToolSchema(value);
108+
}
109+
}
110+
}
111+
112+
// Infer a single JSON-schema type for a dropped non-string enum. `string` is the
113+
// safe fallback for empty/null-only/heterogeneous value sets (always valid for
114+
// Gemini), so we only commit to a narrower type when every value agrees.
115+
function inferType(values: unknown[]): string {
116+
const nonNull = values.filter((v) => v !== null);
117+
if (nonNull.length === 0) return "string";
118+
if (nonNull.every((v) => typeof v === "boolean")) return "boolean";
119+
if (nonNull.every((v) => typeof v === "number")) {
120+
return nonNull.every((v) => Number.isInteger(v)) ? "integer" : "number";
121+
}
122+
if (nonNull.every((v) => Array.isArray(v))) return "array";
123+
if (nonNull.every((v) => typeof v === "object")) return "object";
124+
return "string";
125+
}
126+
127+
function appendConstraint(description: unknown, values: unknown[]): string {
128+
const rendered = values.map((v) =>
129+
typeof v === "string" ? `\`${v}\`` : `\`${JSON.stringify(v)}\``,
130+
);
131+
const note =
132+
rendered.length === 1
133+
? `Value must be ${rendered[0]}.`
134+
: `Value must be one of: ${rendered.join(", ")}.`;
135+
return typeof description === "string" && description.length > 0
136+
? `${description} ${note}`
137+
: note;
138+
}

0 commit comments

Comments
 (0)