@juno-ai/bind 10.0.0 → 12.0.0

package/tools/sanitize-schema.d.ts

@@ -100,6 +100,106 @@
  *      `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.
+ *   8. Resolve a COMPOSITION BRANCH's `required` against the branch's own
+ *      `properties` UNIONED with the enclosing node's `properties`, and — at the
+ *      parameters ROOT only — make the surviving branch self-sufficient by copying
+ *      the referenced property subschemas down into it and setting
+ *      `type: "object"`. This is the narrow, measured exception to transform #3.
+ *      The ordinary way to say "pass exactly one of these" puts the properties on
+ *      the parent and only `required` in each branch:
+ *
+ *        { type: "object", properties: { query: …, memoryItemId: … },
+ *          oneOf: [ { required: ["query"] }, { required: ["memoryItemId"] } ] }
+ *
+ *      which is how JSON Schema composition works, and which transform #3 alone
+ *      sanitized to `oneOf: [{}, {}]` — a root xAI (Grok) hard-rejects
+ *      (`tool parameter root must be an object type (root schema is an
+ *      anyOf/oneOf union with a non-object branch)`, failing EVERY tool in the
+ *      request), and which Gemini/OpenAI accept while silently losing the
+ *      constraint, letting the model send both parameters or neither. Measured on
+ *      xAI for branches of a ROOT union: `{type:"object", …}` or `{properties:…}`
+ *      is accepted with EITHER alone sufficing; a bare `{required:[…]}` or `{}` is
+ *      a 400. Hence the copy-down, which also makes the branch idempotent under
+ *      this sanitizer (a second pass finds every `required` name in the branch's
+ *      OWN `properties` and changes nothing).
+ *
+ *      Two limits are load-bearing, both measured:
+ *        - The parent scope is the ENCLOSING node only, and only for
+ *          `allOf`/`anyOf`/`oneOf` elements. Widening transform #3 to resolve
+ *          `required` against ALL ancestors at every node reintroduces the hard
+ *          Gemini 400 that transform #3 exists to prevent ("required fields
+ *          ['value'] are not defined in the schema properties" — still true on
+ *          gemini-3.5/3.6/3.7-flash). Every non-branch node keeps transform #3
+ *          exactly as it is, and so do `if`/`then`/`else` and `dependentSchemas`,
+ *          which are not composition arrays.
+ *        - The copy-down is ROOT-ONLY. The identical bare-`required` union nested
+ *          under a property is accepted by all nine measured models including
+ *          every Grok version, so a nested composition keeps its `required` (that
+ *          is the fix) and is otherwise left alone — no provider constrains it,
+ *          and churning it risks the transform-#5 `allOf` flatten.
+ *      Only the names in the branch's own `required` are copied, so a branch does
+ *      not inherit the parent's whole property set — and a single ceiling
+ *      (`MAX_ROOT_COPY_DOWN`) bounds the copy-down across ALL branches of one
+ *      root composition, because the per-branch bound does not bound N branches
+ *      × P names. Past the ceiling the repair is skipped, leaving the branches
+ *      bare for rule (a) below to drop.
+ *   9. Guarantee the parameters ROOT is one xAI will accept, as a final pass.
+ *      xAI rejects a root that is not an object type, and the rejection takes the
+ *      whole request (every tool) with it. Two distinct rules, each measured
+ *      against grok-4.3/4.5/4.6 (and confirmed inert on the six Gemini/OpenAI
+ *      models) through OpenRouter with `provider.allow_fallbacks: false` and one
+ *      tool per request:
+ *
+ *        a. Every element of a root `anyOf`/`oneOf` must be a plain object that
+ *           is object-shaped, and must not be `{}`. A branch that declares a
+ *           `type` is judged on that alone (`type: "object"` passes, anything
+ *           else fails even when the branch also carries `properties` — measured
+ *           0/3, identical to a bare `{type:"string"}`); a branch with no `type`
+ *           passes on `properties`. This holds even when the root ITSELF declares
+ *           `type: "object"` and `properties` — an object root does not excuse a
+ *           non-object branch. Rule (a) runs BEFORE the transform-#5 flatten,
+ *           since that flatten refuses to merge an `allOf` while a union sibling
+ *           is present; dropping the union afterwards would strand an `allOf`
+ *           that the next pass would merge, breaking idempotence. A
+ *           branch that still fails after #8 cannot be repaired (its `required`
+ *           names something no `properties` map declares — the parent supplies it
+ *           only via `patternProperties`/`additionalProperties`, or not at all —
+ *           or it is a `$ref`/scalar/boolean branch), so the whole keyword is
+ *           dropped. Losing one tool's constraint is strictly better than losing
+ *           every tool in the request.
+ *        b. A root carrying a composition keyword but declaring neither `type`
+ *           nor `properties` is rejected on its OWN account, whatever the branches
+ *           look like: `{allOf:[{$ref:…}], $defs:…}` and
+ *           `{allOf:[{type:"object",…}, {not:…}]}` are both 0/3 on Grok. Adding
+ *           `type: "object"` to such a root makes exactly those cases pass 9/9
+ *           without touching the composition — so the un-flattenable root `allOf`
+ *           that transform #5 deliberately preserves is RESCUED rather than
+ *           discarded, and it stops being the silent 400 it is today. A `type` the
+ *           schema declared for itself is never overridden.
+ *
+ *      Rule (a) is all-or-nothing per keyword, because ONE unusable branch
+ *      poisons the whole union on xAI even when its siblings are good (0/3 with a
+ *      `{type:"string"}` sibling next to a valid object branch). Filtering the bad
+ *      branches out instead is accepted by xAI (3/3) but is NOT what we do — it
+ *      advertises a narrower tool, telling the model an arm is invalid so it never
+ *      calls that shape, with nothing to surface the loss. Dropping the keyword
+ *      leaves the parent's `properties` fully visible, so every shape stays
+ *      callable and a wrong COMBINATION comes back from dispatch/the remote
+ *      server as a recoverable tool error.
+ *
+ *      Two shapes are known losses, both measured and both unavoidable here:
+ *      a root union of `$ref` branches (xAI does not resolve them — 0/3 even with
+ *      an object root), and a root union whose branch is itself a composition
+ *      (`{oneOf:[{anyOf:[…]}]}` — 0/3 even with `type:"object"` stamped on the
+ *      root). Both drop to a root that is accepted but advertises no properties.
+ *      Recovering the first means inlining same-document `$ref`s before rule (a).
+ *
+ *      A root `allOf`'s BRANCHES are deliberately not constrained by (a):
+ *      measured, xAI accepts `$ref`, `not`, nested-`allOf` and even scalar
+ *      branches under an `allOf` as long as (b) holds — only `anyOf`/`oneOf`
+ *      branches are validated individually. A bare union root whose branches are
+ *      all object-carrying is accepted too (xAI infers object-ness from them), so
+ *      (b) leaves it alone. Compositions nested below the root are untouched.
  *
  * 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
@@ -146,5 +246,9 @@
  * 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.
+ *
+ * Idempotent: `sanitizeToolSchema(sanitizeToolSchema(x))` deep-equals
+ * `sanitizeToolSchema(x)`. Transform #8's copy-down depends on that — a repaired
+ * branch that a second pass re-emptied would be no repair at all.
  */
 export declare function sanitizeToolSchema(schema: Record<string, unknown>): Record<string, unknown>;