@juno-ai/bind 2.0.0 → 4.0.0

package/tools/sanitize-schema.js

@@ -0,0 +1,683 @@
+/**
+ * Sanitize a tool's JSON Schema before it is handed to the model.
+ *
+ * Why this exists
+ * ---------------
+ * Tool schemas reach the LLM verbatim — for MCP tools the third-party
+ * server's `inputSchema` is forwarded as-is (`rawJsonSchema` in
+ * `buildToolDefinitions`). Some providers validate that schema strictly
+ * and reject the *entire* request (every tool, not just the bad one) on
+ * the first violation. The one that bit us in production was Google
+ * Gemini via OpenRouter:
+ *
+ *   OpenRouter 400 — Provider: Google (Google AI Studio), INVALID_ARGUMENT:
+ *   GenerateContentRequest.tools[0].function_declarations[50]
+ *     .parameters.properties[issue_fields].items.required[0]:
+ *     property is not defined
+ *
+ * That message is a *symptom*, not the cause. The GitHub MCP `issue_write`
+ * tool's `issue_fields.items` schema contained constructs Gemini's
+ * function-declaration schema (a strict OpenAPI 3.0 subset) does not
+ * support: a property typed with a `type` ARRAY (`value: { type:
+ * ["string","number","boolean"] }`) and an `enum` on a boolean property
+ * (`delete: { type: "boolean", enum: [true] }`). When Gemini's translator
+ * hits an unsupported construct it drops the enclosing `properties` object,
+ * after which the (perfectly valid) `required: ["field_name"]` dangles —
+ * hence the misleading "property is not defined". The root causes were
+ * confirmed empirically by bisecting the real schema against live Gemini
+ * inference via OpenRouter; OpenAI and Anthropic accept all of it.
+ *
+ * What it does (applied to EVERY tool for EVERY model)
+ * ----------------------------------------------------
+ * The transforms only remove or normalize constructs that carry no real
+ * constraint for a model's tool call. Each was verified against live Gemini:
+ *
+ *   1. Collapse a `type` ARRAY to a single `type`. Gemini requires a scalar
+ *      `type` and rejects a union array. We keep the first non-`"null"`
+ *      member (e.g. `["string","number","boolean"]` → `"string"`,
+ *      `["string","null"]` → `"string"`); an array of only `"null"` drops
+ *      the `type`. The lost alternatives are advisory — arguments are still
+ *      validated at dispatch against the tool's zod schema and by the remote
+ *      MCP server.
+ *   2. Constrain `enum` to Gemini's rule: it is accepted ONLY as a list of
+ *      strings on a string-typed (or type-less) property. So drop `enum`
+ *      entirely when the node has an explicit non-string type (boolean,
+ *      number, integer, array, object, null), and otherwise filter it to its
+ *      string members (dropping any non-string leftovers — e.g. after a union
+ *      `type` collapsed to "string") and omit it if none remain. `const`,
+ *      which Gemini DOES support on every type, is left untouched — do not
+ *      convert it to `enum`, which would manufacture the rejected case.
+ *   3. Drop `required` entries with no matching key in the SAME node's own
+ *      `properties` map (evaluated per node, against direct `properties`
+ *      only — Gemini does not resolve composition or parent scope, and a
+ *      `required` naming an absent property is a hard 400). A genuinely
+ *      dangling `required` is invalid everywhere; this is a safety net, not
+ *      the primary fix for the issue above.
+ *   4. Strip the `$schema` dialect declaration, which function-calling APIs
+ *      ignore. We deliberately KEEP `$id`: for schemas that use relative
+ *      `$ref`s it defines the base URI / identifies subschemas, and we
+ *      preserve `$ref`, so dropping `$id` could break reference resolution.
+ *   5. Flatten a top-level `allOf` of object subschemas into a single object
+ *      schema (merge `properties`, union `required`). A function's parameters
+ *      root produced by a Zod intersection (`a.and(b)`) renders as `{ allOf:
+ *      [ {type:object…}, {type:object…} ] }` with no root `type`/`properties`.
+ *      xAI (Grok) via OpenRouter strictly requires the parameters ROOT to be a
+ *      plain object schema and rejects the whole request with a 502 "Invalid
+ *      arguments passed to the model" on a composition root; Gemini tolerates
+ *      it. Merging is safe for tool calling — `allOf` means "satisfy every
+ *      branch", i.e. an object carrying the union of all branches' properties.
+ *      Confirmed empirically against live Grok (`document__convert_excel` /
+ *      `document__ocr`). Only `allOf` is flattened (a true intersection);
+ *      `anyOf`/`oneOf` roots are left untouched. The flatten is applied ONLY
+ *      when it's lossless — every branch is a plain object schema with
+ *      merge-safe keywords; a branch carrying `$ref`, `not`, `if`, nested
+ *      composition, a non-object `type`, etc. leaves the `allOf` intact rather
+ *      than dropping the unmerged constraint.
+ *   6. Drop a boolean `additionalProperties: false`. xAI (Grok) via OpenRouter
+ *      rejects that form on a NESTED object schema with a hard 400 ("property
+ *      schema 'false' is not supported"), failing the WHOLE request (every
+ *      tool). The constraint it carries — "no keys beyond those declared" — is
+ *      advisory for tool calling (arguments are validated at dispatch against
+ *      the tool's zod schema and by the remote MCP server), so it is dropped
+ *      rather than allowed to sink the request. `additionalProperties: true`
+ *      (the JSON Schema default, a no-op) is left as-is, and an OBJECT-valued
+ *      `additionalProperties` is a real subschema constraint every provider
+ *      accepts — it is kept and recursed into. Confirmed against the production
+ *      failure (Notion `notion-create-pages`,
+ *      `pages[].properties.properties.additionalProperties`).
+ *   7. Neutralize a tool parameter literally NAMED `properties` whose schema is
+ *      object-shaped. xAI (Grok) via OpenRouter mis-reads such a field as the
+ *      JSON-Schema `properties` keyword — it descends in, injects an
+ *      `additionalProperties: false`, then rejects its own injection, failing the
+ *      WHOLE request with `/properties/properties/additionalProperties: property
+ *      schema 'false' is not supported` (so transform #6 alone never helped —
+ *      the rejected `false` is xAI's own, not ours). Notion's `notion-create-pages`
+ *      / `update-page` carry exactly this field (the page's `properties` map), so
+ *      it 400s the default Grok agent. xAI accepts the field only when it does NOT
+ *      look like an object schema, so we collapse an object-shaped
+ *      `properties`-named node to annotations only (`description` / `title`).
+ *      Advisory-safe (args validated at dispatch + by the remote server; Notion's
+ *      `properties` is an open per-database map with no fixed sub-schema), and the
+ *      key name is never changed so the model still emits the right argument key.
+ *      Confirmed live: `x-ai/grok-4.3` 400→200, Gemini/Claude unaffected.
+ *
+ * When (1) or (2) discards information the model could use — a collapsed
+ * union type, or a wholly-dropped `enum` — that constraint is folded into the
+ * node's `description` as prose ("Accepts string, number, or boolean.",
+ * "Allowed values: true.") so the model still sees it. `description` is a free
+ * string every provider accepts, so this is always safe.
+ *
+ * It deliberately leaves meaningful validation keywords (`format`,
+ * `pattern`, object- or `true`-valued `additionalProperties`, `const`, string
+ * `enum`, length/range bounds, `$ref`, `$id`) intact so compliant providers
+ * keep their guidance. The two structural exceptions are both xAI-rejected: the
+ * boolean `false` form of `additionalProperties` (transform #6), and the
+ * object-structure of a property literally named `properties` (transform #7),
+ * which is collapsed to annotations only.
+ *
+ * The walk is keyword-aware: it only recurses into positions that JSON
+ * Schema defines as subschemas, and treats `enum` / `const` / `default` /
+ * `examples` values (and the `required` array itself) as opaque data. That
+ * way a tool parameter literally named `properties` or `required`, or an
+ * example value that happens to contain those keys, is never mistaken for
+ * schema structure and corrupted by OUR walk. (Transform #7 separately
+ * rewrites a `properties`-named object field — not because we confuse it, but
+ * because xAI's parser does.)
+ *
+ * Robustness: the walk is depth-bounded (`MAX_DEPTH`) so a pathologically
+ * nested third-party schema can't overflow the stack, and the entry point
+ * tolerates a non-object root (a boolean schema, or a malformed server's
+ * payload) by returning an empty object instead of throwing. Past the bound
+ * the subtree is *replaced*, not returned verbatim — a bomb passed through
+ * would simply overflow one frame later, when the caller serializes the
+ * result into a request body. For the same reason nothing in this module
+ * hands an untrusted value to `JSON.stringify`, which recurses on its own and
+ * so would reintroduce the unbounded walk the depth guard exists to prevent.
+ *
+ * Non-mutating, but NOT a full deep clone: the returned object has a fresh
+ * spine (every object/array node the walk descends into is rebuilt), so the
+ * input `rawJsonSchema` — shared across runs — is never mutated. Opaque
+ * leaf values (`enum`, `const`, `default`, `examples`, `pattern`, …) are
+ * carried over by reference, so callers must treat the result as read-only.
+ */
+/** Hard cap on recursion depth to bound stack usage on adversarial input. */
+const MAX_DEPTH = 100;
+/** Metadata keyword(s) the function-calling APIs ignore; safe to drop. */
+const METADATA_KEYS = new Set(["$schema"]);
+/**
+ * Keys skipped at the keyword level — none are valid JSON Schema keywords.
+ * Only `__proto__` carries real danger (its setter mutates the prototype
+ * rather than creating an own property; `safeSet` uses `defineProperty` for
+ * it inside maps); `constructor`/`prototype` are included conservatively.
+ */
+const PROTO_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/** Single-subschema keywords (value is a subschema, or a boolean).
+ * `additionalProperties` is handled by a dedicated branch in `sanitizeSchemaNode`
+ * (transform #6 drops its boolean `false` form and recurses into the object
+ * form), so it is intentionally NOT listed here — that dedicated branch
+ * `continue`s before the generic single-subschema handler is reached. */
+const SUBSCHEMA_SINGLE_KEYS = new Set([
+    "unevaluatedProperties",
+    "additionalItems",
+    "unevaluatedItems",
+    "contains",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+]);
+/** Array-of-subschema keywords. */
+const SUBSCHEMA_ARRAY_KEYS = new Set([
+    "allOf",
+    "anyOf",
+    "oneOf",
+    "prefixItems",
+]);
+/** Name → subschema maps. `properties` is listed here for completeness, but a
+ * dedicated `key === "properties"` branch in `sanitizeSchemaNode` intercepts it
+ * first (to apply transform #7) and `continue`s — so the generic map handler
+ * only ever sees the others. Keep it in the set so that if the dedicated branch
+ * is ever removed, `properties` still falls back to generic map sanitization
+ * rather than being treated as opaque. */
+const SUBSCHEMA_MAP_KEYS = new Set([
+    "properties",
+    "patternProperties",
+    "$defs",
+    "definitions",
+    "dependentSchemas",
+]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Join words as a human list: ["a"]→"a", ["a","b"]→"a or b", ["a","b","c"]→"a, b, or c". */
+function humanJoin(items) {
+    if (items.length <= 1)
+        return items.join("");
+    if (items.length === 2)
+        return `${items[0]} or ${items[1]}`;
+    return `${items.slice(0, -1).join(", ")}, or ${items[items.length - 1]}`;
+}
+/**
+ * Render one `enum` member for the human-readable prose we attach to a
+ * description when the enum itself is dropped.
+ *
+ * Composite members are summarized rather than serialized. `JSON.stringify`
+ * recurses over the value, so a third party could hand us a deeply nested
+ * `enum` member and overflow the stack here — outside the walk's depth guard,
+ * which bounds structural recursion only. The summary loses nothing a model
+ * could act on: an enum of nested containers is not a constraint prose can
+ * usefully express.
+ */
+function describeEnumValue(value) {
+    if (typeof value === "object" && value !== null) {
+        return Array.isArray(value) ? "[…]" : "{…}";
+    }
+    // `undefined` (illegal in JSON but reachable from a hand-built object)
+    // stringifies to `undefined`, not a string.
+    return JSON.stringify(value) ?? String(value);
+}
+/**
+ * True if a (sanitized) schema node "looks like an object schema" to xAI's
+ * tool-schema parser — i.e. carries `type: "object"` or any of the keywords it
+ * descends through as object structure (`properties` / `patternProperties` /
+ * `additionalProperties`). Used only by the transform-#7 collision check below.
+ */
+function looksObjectShapedToXai(node) {
+    return (node.type === "object" ||
+        "properties" in node ||
+        "patternProperties" in node ||
+        "additionalProperties" in node);
+}
+/**
+ * Transform #7 (xAI/Grok workaround). A tool parameter literally NAMED
+ * `properties` whose schema is object-shaped makes xAI's validator mis-read it
+ * as the JSON-Schema `properties` keyword: it descends in, injects an
+ * `additionalProperties: false`, then rejects its own injection — failing the
+ * WHOLE request with `/properties/properties/additionalProperties: property
+ * schema 'false' is not supported` (verified live against `x-ai/grok-4.3`).
+ * Notion's `notion-create-pages` / `update-page` tools carry exactly such a
+ * field (the page's `properties` map), so this 400s the default Grok agent.
+ *
+ * xAI accepts the field only when it does NOT look like an object schema
+ * (`{ description }`, `{}`, or a non-object `type` all pass). So we collapse an
+ * object-shaped `properties`-named node to its non-structural keywords: the
+ * `description` / `title` annotations plus the opaque data keywords `default` /
+ * `examples` / `const` (verified live that xAI does NOT descend into these — it
+ * treats them as data, not schema — so they preserve model guidance without
+ * re-triggering the bug). Only the object-STRUCTURE keywords (`type: "object"`,
+ * `properties`, `patternProperties`, `additionalProperties`, `required`, …) are
+ * dropped. This is advisory-safe — arguments are passed through and validated at
+ * dispatch + by the remote MCP server — and the field's object intent survives in
+ * its description (Notion's `properties` is an open per-database map with no fixed
+ * sub-schema, so little is lost). The key name is never changed, so the model
+ * still emits the correct argument key.
+ */
+function neutralizeXaiPropertiesField(node) {
+    const out = {};
+    if (typeof node.title === "string")
+        out.title = node.title;
+    out.description =
+        typeof node.description === "string" && node.description.length > 0
+            ? node.description
+            : "An object.";
+    // Opaque data keywords (not schema structure) — kept as model guidance; xAI
+    // does not descend into them, so they don't re-trigger the collision.
+    for (const k of ["default", "examples", "const"]) {
+        if (k in node)
+            out[k] = node[k];
+    }
+    return out;
+}
+/** Assign a key/value, using `defineProperty` for `__proto__` so a literal
+ * `__proto__` key becomes an own property instead of mutating the prototype. */
+function safeSet(out, key, value) {
+    if (key === "__proto__") {
+        Object.defineProperty(out, key, {
+            value,
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    else {
+        out[key] = value;
+    }
+}
+/** Recurse into a value that JSON Schema defines as a single subschema. In
+ * draft-07 `items` / tuple forms a value may also be an array of subschemas. */
+function sanitizeSubschema(value, depth) {
+    // Arrays count toward the depth budget too. Counting only object nodes left
+    // the bound bypassable by a chain of nested arrays (`items: [[[[…]]]]`),
+    // which recurses here without ever reaching `sanitizeSchemaNode` — a third
+    // party could overflow the stack with a schema the guard claimed to bound.
+    //
+    // `true` — the accept-anything boolean schema — rather than the value: past
+    // MAX_DEPTH the input is adversarial, and returning it would only move the
+    // overflow to whoever serializes our output.
+    if (depth > MAX_DEPTH)
+        return true;
+    if (Array.isArray(value)) {
+        return value.map((v) => sanitizeSubschema(v, depth + 1));
+    }
+    if (isPlainObject(value))
+        return sanitizeSchemaNode(value, depth);
+    return value; // boolean or other primitive (e.g. `not: false`)
+}
+/** Recurse into a name → subschema map (`properties`, `$defs`, …). */
+function sanitizeSchemaMap(value, depth) {
+    if (!isPlainObject(value))
+        return value;
+    const out = {};
+    for (const [name, sub] of Object.entries(value)) {
+        safeSet(out, name, isPlainObject(sub) || Array.isArray(sub)
+            ? sanitizeSubschema(sub, depth)
+            : sub);
+    }
+    return out;
+}
+function sanitizeSchemaNode(node, depth) {
+    // Depth guard: stop walking absurdly nested input rather than overflowing
+    // the stack. Real tool schemas are a few levels deep; anything past
+    // MAX_DEPTH is adversarial, so the subtree is replaced with the
+    // unconstrained empty schema instead of being carried through — passing it
+    // through bounds only OUR recursion, and the bomb would then detonate in
+    // `JSON.stringify` when the sanitized schema is serialized into the request.
+    if (depth > MAX_DEPTH)
+        return {};
+    const childDepth = depth + 1;
+    // Property names a `required` on THIS node may reference — the node's OWN
+    // `properties` only (see module header: matches Gemini's validator, which
+    // does not resolve composition or parent scope).
+    const propertyNames = isPlainObject(node.properties)
+        ? new Set(Object.keys(node.properties))
+        : null;
+    // Resolve the node's effective single `type`, collapsing a JSON Schema
+    // `type` ARRAY (a union, e.g. `["string","number","boolean"]` or a nullable
+    // `["string","null"]`) to the first non-"null" member. Gemini's
+    // function-declaration schema requires a single `type` and hard-rejects a
+    // type array, which manifests as a misleading downstream error. Computed up
+    // front (not in key order) because the `enum` decision below depends on it.
+    let typeToEmit = node.type;
+    let emitType = "type" in node;
+    let singleType;
+    if (Array.isArray(node.type)) {
+        const nonNull = node.type.filter((t) => t !== "null");
+        if (nonNull.length > 0) {
+            typeToEmit = nonNull[0];
+            if (typeof nonNull[0] === "string")
+                singleType = nonNull[0];
+        }
+        else {
+            emitType = false; // a `["null"]`-only type → drop it
+        }
+    }
+    else if (typeof node.type === "string") {
+        singleType = node.type;
+    }
+    // Gemini accepts `enum` only on string-typed properties. Drop it outright
+    // when the node has an explicit NON-string type (boolean/number/integer/
+    // array/object/null); when the type is "string" or absent, the enum is
+    // instead filtered to its string members below. (The constraint is advisory
+    // — arguments are validated at dispatch and by the remote server.)
+    const dropEnum = singleType !== undefined && singleType !== "string";
+    // A `type` collapse or a dropped `enum` discards a constraint the model
+    // could use. Fold that information into the node's `description` (as prose,
+    // which every provider accepts) so the model still sees it. Computed up
+    // front so it can be appended wherever `description` appears in key order.
+    const notes = [];
+    if (Array.isArray(node.type)) {
+        const typeNames = node.type.filter((t) => typeof t === "string");
+        if (typeNames.length > 1) {
+            notes.push(`Accepts ${humanJoin(typeNames)}.`);
+        }
+        else if (typeNames.length === 1 && typeNames[0] === "null") {
+            // A `["null"]`-only type was dropped (no scalar type to emit).
+            notes.push("Must be null.");
+        }
+    }
+    if (Array.isArray(node.enum)) {
+        const stringMembers = node.enum.filter((v) => typeof v === "string");
+        if (dropEnum || stringMembers.length === 0) {
+            // The whole enum is dropped (non-string type, or no string members
+            // survive the string-filter) — surface every original allowed value.
+            notes.push(`Allowed values: ${node.enum.map(describeEnumValue).join(", ")}.`);
+        }
+        else if (node.enum.length > stringMembers.length) {
+            // Partial filter: string members are kept in the emitted `enum`; surface
+            // the dropped non-string members so they aren't lost.
+            const dropped = node.enum.filter((v) => typeof v !== "string");
+            notes.push(`May also be ${humanJoin(dropped.map(describeEnumValue))}.`);
+        }
+    }
+    const descNote = notes.join(" ");
+    let descriptionEmitted = false;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (METADATA_KEYS.has(key))
+            continue;
+        // Never let an invalid `__proto__`/`constructor`/`prototype` *keyword*
+        // through; none are valid JSON Schema keywords. (Literal property names
+        // by those names are handled safely inside `sanitizeSchemaMap`.)
+        if (PROTO_KEYS.has(key))
+            continue;
+        if (key === "type") {
+            if (emitType)
+                out.type = typeToEmit;
+            continue;
+        }
+        if (key === "description") {
+            // Append any constraint notes (collapsed type / dropped enum) to the
+            // existing description so the information survives the sanitization.
+            descriptionEmitted = true;
+            out.description =
+                typeof value === "string" && descNote
+                    ? `${value} ${descNote}`
+                    : value;
+            continue;
+        }
+        if (key === "enum") {
+            // Gemini accepts `enum` ONLY as a list of strings: an enum on a
+            // boolean/number/integer type is rejected (`dropEnum`), and even on a
+            // string type any non-string member is rejected — including leftovers
+            // after a union `type` was collapsed to "string" (e.g. `type:
+            // ["string","number"], enum: ["a", 1]` → keep only `["a"]`). Filter to
+            // string members; drop the keyword entirely if none remain. (Verified
+            // against live Gemini inference.)
+            if (!dropEnum && Array.isArray(value)) {
+                const strings = value.filter((v) => typeof v === "string");
+                if (strings.length > 0)
+                    out.enum = strings;
+            }
+            continue;
+        }
+        if (key === "required") {
+            if (Array.isArray(value)) {
+                const pruned = value.filter((name) => typeof name === "string" && (propertyNames?.has(name) ?? false));
+                // An empty `required: []` is valid but noise; omit it entirely.
+                if (pruned.length > 0)
+                    out.required = pruned;
+            }
+            // A non-array `required` is malformed JSON Schema (and would itself
+            // trip a strict validator) — drop it.
+            continue;
+        }
+        if (key === "dependencies") {
+            // draft-07: name → (subschema | string[]). Subschema values are
+            // sanitized (and self-prune their own `required`); string[] values are
+            // property dependencies (opaque data), left untouched.
+            if (isPlainObject(value)) {
+                const deps = {};
+                for (const [name, dep] of Object.entries(value)) {
+                    safeSet(deps, name, isPlainObject(dep) ? sanitizeSchemaNode(dep, childDepth) : dep);
+                }
+                out.dependencies = deps;
+            }
+            else {
+                out.dependencies = value;
+            }
+            continue;
+        }
+        if (key === "properties") {
+            // Recurse normally, then apply transform #7: a child property literally
+            // named `properties` whose schema is object-shaped trips xAI's parser, so
+            // collapse it to annotations only. (Only the `properties` MAP triggers the
+            // `/properties/properties` collision — `patternProperties`/`$defs` keys are
+            // patterns/definition names, not property names, so they go through the
+            // generic map handler below.)
+            const mapped = sanitizeSchemaMap(value, childDepth);
+            if (isPlainObject(mapped) &&
+                isPlainObject(mapped.properties) &&
+                looksObjectShapedToXai(mapped.properties)) {
+                mapped.properties = neutralizeXaiPropertiesField(mapped.properties);
+            }
+            out.properties = mapped;
+            continue;
+        }
+        if (SUBSCHEMA_MAP_KEYS.has(key)) {
+            out[key] = sanitizeSchemaMap(value, childDepth);
+            continue;
+        }
+        if (key === "additionalProperties") {
+            // Drop the boolean `false` form — xAI (Grok) rejects it on a nested
+            // object schema and 400s the whole request (transform #6). `true` (no-op
+            // default) and an object-valued subschema (a real constraint) are kept;
+            // the latter is recursed into like any other single subschema.
+            if (value === false)
+                continue;
+            out.additionalProperties = sanitizeSubschema(value, childDepth);
+            continue;
+        }
+        if (SUBSCHEMA_SINGLE_KEYS.has(key) || key === "items") {
+            // `items` is a subschema (2020-12) or an array of subschemas (draft-07
+            // tuple); `sanitizeSubschema` handles both.
+            out[key] = sanitizeSubschema(value, childDepth);
+            continue;
+        }
+        if (SUBSCHEMA_ARRAY_KEYS.has(key)) {
+            out[key] = Array.isArray(value)
+                ? value.map((v) => sanitizeSubschema(v, childDepth))
+                : value;
+            continue;
+        }
+        // Opaque keyword (`default`, `examples`, `format`, `pattern`,
+        // `dependentRequired`, numeric bounds, …) — copy verbatim. Notably we do
+        // NOT walk into `default`/`examples` values, which are arbitrary data and
+        // may legitimately contain `properties`/`required` keys that are not
+        // schema structure.
+        safeSet(out, key, value);
+    }
+    // If we have constraint notes but the node had no `description` to append
+    // them to, add one so the dropped information still reaches the model.
+    if (descNote && !descriptionEmitted)
+        out.description = descNote;
+    return out;
+}
+/**
+ * Keys an `allOf` branch may carry and still be merged losslessly into a single
+ * object schema: plain object structure plus annotations. A branch with any
+ * other keyword (`$ref`, `not`, `if`/`then`/`else`, `anyOf`/`oneOf`, nested
+ * `allOf`, `dependentSchemas`/`dependencies`, `patternProperties`,
+ * `propertyNames`, `unevaluatedProperties`, …) carries a constraint the flatten
+ * does NOT carry forward, so flattening it would silently drop that constraint.
+ */
+const MERGEABLE_ALLOF_BRANCH_KEYS = new Set([
+    "type",
+    "properties",
+    "required",
+    "additionalProperties",
+    "description",
+    "title",
+]);
+/** Sibling keywords on the root that, alongside `allOf`, mean the root is not a
+ * pure intersection — flattening only the `allOf` would change its meaning. */
+const ROOT_COMPOSITION_SIBLINGS = [
+    "anyOf",
+    "oneOf",
+    "not",
+    "if",
+    "then",
+    "else",
+    "$ref",
+];
+/** True if every `allOf` branch is a plain object schema whose keywords are all
+ * merge-safe (and whose `type`, if present, is `"object"`; whose
+ * `additionalProperties`, if present, is `true` — the only boolean surviving
+ * transform #6; an object-valued form blocks the flatten) — i.e. the
+ * intersection can be flattened without dropping any constraint. */
+function canLosslesslyFlattenAllOf(root, branches) {
+    if (ROOT_COMPOSITION_SIBLINGS.some((k) => k in root))
+        return false;
+    for (const branch of branches) {
+        if (!isPlainObject(branch))
+            return false;
+        for (const key of Object.keys(branch)) {
+            if (!MERGEABLE_ALLOF_BRANCH_KEYS.has(key))
+                return false;
+        }
+        if ("type" in branch && branch.type !== "object")
+            return false;
+        if ("additionalProperties" in branch &&
+            typeof branch.additionalProperties !== "boolean") {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Flatten a top-level `allOf` of object subschemas into a single object schema
+ * (see module-header transform #5). Operates ONLY on the parameters root —
+ * `allOf` nested deeper is a meaningful constraint left intact by the walk. The
+ * root node and every `allOf` branch contribute their `properties` (a later
+ * branch wins a key collision) and `required` entries (unioned, then pruned to
+ * the merged property set). The node walk runs BEFORE this flatten and has
+ * already dropped every boolean `additionalProperties: false` (transform #6),
+ * so only `true` can reach the merge — it is carried through and the flattened
+ * root never emits `false`. Branch-level `description`s are folded into the
+ * merged description rather than dropped.
+ *
+ * The flatten is applied ONLY when every branch can be merged losslessly
+ * (`canLosslesslyFlattenAllOf`): a branch carrying a keyword the merge doesn't
+ * carry forward — `$ref`, `not`, `if`, nested composition, `dependentSchemas`,
+ * `patternProperties`, … — or a non-object `type`, or a schema-valued
+ * `additionalProperties`, leaves the `allOf` UNTOUCHED. Dropping such a branch
+ * would advertise an empty/under-constrained object to the model (it runs on
+ * every third-party MCP `rawJsonSchema`), so we keep the original composition
+ * rather than silently lose the constraint. A no-op when the root has no
+ * `allOf` array.
+ */
+function flattenRootAllOf(root) {
+    if (!Array.isArray(root.allOf))
+        return root;
+    // Only flatten when nothing is lost; otherwise keep the composition intact.
+    if (!canLosslesslyFlattenAllOf(root, root.allOf))
+        return root;
+    const mergedProps = {};
+    const requiredSet = new Set();
+    // Transform #6 already stripped every boolean `additionalProperties: false`
+    // during the node walk, so the only boolean that can reach here is `true`
+    // (the no-op default). Carry it through if any branch declares it; we never
+    // (re)introduce a `false` the providers downstream would reject.
+    let additionalProperties;
+    // Branch-level `description`s are folded into the merged description rather
+    // than dropped (a branch may carry input-semantics context for the model).
+    const branchDescriptions = [];
+    // The root's own object fields merge first, then each allOf branch in order.
+    const branches = [root, ...root.allOf];
+    for (const branch of branches) {
+        if (!isPlainObject(branch))
+            continue;
+        if (isPlainObject(branch.properties)) {
+            for (const [name, sub] of Object.entries(branch.properties)) {
+                safeSet(mergedProps, name, sub);
+            }
+        }
+        if (Array.isArray(branch.required)) {
+            for (const name of branch.required) {
+                if (typeof name === "string")
+                    requiredSet.add(name);
+            }
+        }
+        // Only `true` survives the node walk (transform #6 dropped `false`); carry
+        // it. An object-valued form would have blocked the flatten entirely
+        // (canLosslesslyFlattenAllOf), so it can't appear here.
+        if (branch.additionalProperties === true)
+            additionalProperties = true;
+        // Collect branch descriptions other than the root's own (handled below).
+        if (branch !== root && typeof branch.description === "string") {
+            branchDescriptions.push(branch.description);
+        }
+    }
+    // Preserve root-level annotations (e.g. `description`, `$id`) while dropping
+    // the composition keyword and any root object fields now folded into the
+    // merged result.
+    const out = {};
+    for (const [key, value] of Object.entries(root)) {
+        if (key === "allOf" ||
+            key === "properties" ||
+            key === "required" ||
+            key === "type" ||
+            key === "additionalProperties") {
+            continue;
+        }
+        safeSet(out, key, value);
+    }
+    out.type = "object";
+    out.properties = mergedProps;
+    // Fold branch descriptions into the merged description (root's first), keeping
+    // only those not already present so a duplicated annotation isn't repeated.
+    const descriptions = [
+        ...(typeof out.description === "string" ? [out.description] : []),
+        ...branchDescriptions,
+    ];
+    // `Set`, not `filter`+`indexOf`: the latter is O(n²), and `allOf` branch
+    // count is attacker-controlled for an MCP tool schema — 40k branches cost
+    // ~1.9s of blocked event loop, which is a denial of service for every tenant
+    // on the process, not just the one whose connector served the schema.
+    // Insertion order is preserved either way, so the output is unchanged.
+    const uniqueDescriptions = [...new Set(descriptions)];
+    if (uniqueDescriptions.length > 0)
+        out.description = uniqueDescriptions.join(" ");
+    // `hasOwnProperty.call`, not `name in mergedProps`: the latter would treat a
+    // required entry named after a prototype member ("toString", "constructor")
+    // as present and fail to prune a genuinely-undeclared property.
+    const required = [...requiredSet].filter((name) => Object.prototype.hasOwnProperty.call(mergedProps, name));
+    if (required.length > 0)
+        out.required = required;
+    if (additionalProperties !== undefined) {
+        out.additionalProperties = additionalProperties;
+    }
+    return out;
+}
+/**
+ * Return a sanitized, non-mutating copy of a tool parameter JSON Schema (see
+ * the module header for the immutability caveat — opaque leaf values are
+ * shared by reference, so treat the result as read-only). A non-object root
+ * (boolean schema, or malformed third-party payload) yields an empty object
+ * rather than throwing.
+ */
+export function sanitizeToolSchema(schema) {
+    if (!isPlainObject(schema))
+        return {};
+    return flattenRootAllOf(sanitizeSchemaNode(schema, 0));
+}