@juno-ai/bind 11.0.0 → 13.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "11.0.0",
+  "version": "13.0.0",
   "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, the plugin/tool vocabulary, and the skill vocabulary (`./skills`) for progressive knowledge disclosure. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",

package/tools/sanitize-schema.d.ts

@@ -100,6 +100,196 @@
  *      `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 non-object
+ *           `type` the root declared for itself IS rewritten to `"object"` and
+ *           recorded in the description — measured, such a root is rejected by
+ *           every model. Nested nodes keep their declared types unless transform
+ *           #12 applies.
+ *
+ *      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.
+ *
+ *      A branch's OWN `anyOf`/`oneOf` disqualifies it too, whatever else it
+ *      declares: `{type:"object", anyOf:[…]}` as a root union branch is 0/3 on
+ *      Grok, as is a branch carrying both `allOf` and `anyOf` — the union is what
+ *      poisons it. Scope is the branch's own keys and never its subtree: a
+ *      composition on a branch's PROPERTY is accepted 9/9, one or two levels
+ *      down, so a subtree scan would destroy constraints every provider honours.
+ *      A branch's own `allOf` is likewise accepted 9/9 (even with a
+ *      bare-`required` sub-branch), the same intersection-vs-union asymmetry xAI
+ *      applies to the root — hence `ROOT_UNION_KEYS`, not `COMPOSITION_KEYS`.
+ *
+ *      A root union of `$ref` branches is no longer a loss — transform #14 below
+ *      inlines the targets so the union survives. What remains is the narrow
+ *      residue it cannot inline: a target that is not a plain object schema, one
+ *      whose expanded size exceeds the copy-down ceiling, and a self-referential
+ *      root pointer. Those branches stay unusable and still drop the keyword.
+ *
+ *      Rule (b) covers EVERY root, not only composition roots. A property sweep
+ *      over recursive shapes (`__tests__/tool-schema/property/`) found the
+ *      narrower gate emitting unusable roots for whole classes the fixtures
+ *      never reached: a scalar or array root (reachable from transform #1
+ *      collapsing `{type:["string","null"]}`), an annotation-only root, a
+ *      `$defs`-only root, and a root whose `type` contradicts its `properties` —
+ *      that last one rejected by all nine models, the only rule here with no
+ *      tolerant provider. Rule (b) also DROPS a `const` or `$ref` carried by the
+ *      root: measured `root schema is a const` / `root schema is a $ref`, 400
+ *      even alongside `type: "object"` and `properties`, and for `$ref` even
+ *      when the target resolves. Nested `const`/`$ref` are meaningful and
+ *      untouched.
+ *
+ *      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.
+ *
+ *  10. Drop an EMPTY array-valued keyword (`allOf`/`anyOf`/`oneOf`/`prefixItems`)
+ *      at any depth. xAI rejects one anywhere in the tree — `/properties/a/oneOf:
+ *      [] has less than 1 item` — and it carries no constraint (an `allOf` of
+ *      nothing is satisfied by everything). Empty OBJECTS (`properties: {}`,
+ *      `$defs: {}`) and an empty `required: []` are accepted and left alone;
+ *      `enum: []` and `required: []` were already omitted by transforms #2/#3.
+ *  11. Drop a `$ref` whose LOCAL target does not resolve. xAI resolves `#/…`
+ *      pointers itself and 400s the whole request on a dangling one
+ *      (`unresolvable $ref '#/$defs/Nope'`), which a third-party MCP server
+ *      produces easily by shipping a subschema without its definitions — or by
+ *      putting `$defs` on a nested node, since `#/$defs/X` is anchored at the
+ *      document ROOT and a nested `$defs` is unaddressable that way. External
+ *      refs (`https://…`) and resolvable non-`$defs` pointers (`#/properties/a`)
+ *      are both accepted by xAI and left alone. Only the `$ref` keyword is
+ *      dropped, so the rest of the node survives.
+ *
+ *  12. Give any node carrying `properties` an explicit `type: "object"`. Gemini
+ *      rejects the type-less form outright — "Unable to submit request because
+ *      `t` functionDeclaration `parameters.b` schema specified incorrect schema
+ *      type field. For schema with properties, schema type should be OBJECT" —
+ *      on gemini-3.5/3.6/3.7-flash, and rejects a CONTRADICTORY declared type
+ *      (`{type:"string", properties:{…}}`) the same way, so the type is
+ *      overwritten rather than merely defaulted. It is not composition-specific:
+ *      a plain property subschema and an `items` schema fail identically. xAI
+ *      and OpenAI accept every one of those forms, which is why this survived
+ *      until a property sweep over recursive shapes went looking for it. The
+ *      root is exempt in Gemini's own validator, but the rule is applied
+ *      uniformly because it costs nothing and one rule beats two.
+ *
+ *      It is resolved during the node's type resolution, not patched onto the
+ *      finished node, so `dropEnum` sees the real type — an `enum` left on a
+ *      node that has just become an object would otherwise be dropped by the
+ *      NEXT pass instead of this one, breaking idempotence. A discarded
+ *      contradictory type is folded into the description like transform #1's.
+ *      This also makes a contradictory root-union BRANCH repairable: it arrives
+ *      at transform #9 already retyped, so the constraint survives instead of
+ *      the whole keyword being dropped.
+ *
+ *  13. Drop a `pattern` that uses a regex construct a provider's validator
+ *      refuses, echoing it into the description instead. Measured: `(?=`, `(?!`,
+ *      `(?<=`, `(?<!` AND named groups `(?<name>` are rejected by gpt-5.6-sol
+ *      and gpt-5.6-terra (`Invalid JSON schema: regex lookaround is not
+ *      supported` — the message says lookaround, but a named group fails
+ *      identically, so the giveaway is the `(?<` prefix); a BACKREFERENCE
+ *      (`\1`–`\9`) is rejected by grok-4.5. Non-capturing `(?:` is accepted
+ *      everywhere and is deliberately NOT caught. This is the defect that broke
+ *      Monad's own `spaces__invite_member` on every OpenAI model — a whole-
+ *      request 400 from one tool's email pattern. The scan tracks backslash
+ *      escaping and character classes, so a literal `\(\?=` or a `[(?=]` class
+ *      keeps its pattern: dropping a pattern that would have been accepted
+ *      costs a real constraint on every provider.
+ *  14. Inline a ROOT union branch that is a local `$ref`, so the union survives
+ *      rule (a) instead of being dropped whole. `z.union([A, B])` renders as
+ *      `{anyOf:[{$ref},{$ref}], $defs}` and xAI does not resolve a `$ref` union
+ *      branch (0/3 even with `type: "object"` on the root) — so rule (a) used to
+ *      drop the keyword, which for a root whose properties live entirely in
+ *      `$defs` left the tool advertising NO parameters. Inlining produces
+ *      ordinary object branches, accepted 9/9. Only branches that are not
+ *      already usable are inlined, one level deep (a `$ref` inside the target
+ *      resolves on its own, which is what makes a recursive definition
+ *      terminate here), with branch keywords winning over the target's per
+ *      2020-12 `$ref` semantics and a cap for the same reason the copy-down has
+ *      one. A branch whose target is not a plain object schema stays unusable
+ *      and still falls through to the drop.
  *
  * 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 +336,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>;