@juno-ai/bind 1.0.0 → 3.0.0

package/tools/sanitize-schema.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function sanitizeToolSchema(schema: Record<string, unknown>): Record<string, unknown>;