@juno-ai/bind 12.0.0 → 14.0.0

package/README.md

@@ -56,6 +56,27 @@ constraints that will fail CI if you break them.
 
 **Breaking**
 
+- **`sanitizeToolSchema` now emits a union for a nullable property** instead of
+  collapsing it. `{type:["string","null"], minLength:1}` comes out as
+  `{anyOf:[{type:"string",minLength:1},{type:"null"}]}`, with the node's
+  type-bearing keywords on the typed branch and its annotations left outside;
+  the old output was `{type:"string", minLength:1}` plus an "Accepts string or
+  null." note on the description. Nothing in the API changed, but the emitted
+  schema did — a consumer asserting on sanitizer output, or reading `.type` off
+  a sanitized node, needs updating.
+
+  The collapse was lossy in a way that broke callers. A model handed a
+  type-satisfying schema and a description that says "or send null" cannot
+  express "none" in the half of the declaration it treats as binding, so it
+  invents a value: one tool parameter authored `type:["string","null"],
+  minLength:1` received `"/"`, `". "` and `".000001"` for thousands of calls,
+  each refused by the downstream API and each retried. The union shape is
+  measured accepted on grok-4.3/4.5/4.6, gemini-3.5/3.6/3.7-flash and
+  gpt-5.6-terra/sol/luna. A genuine multi-type union
+  (`["string","number","boolean"]`) still collapses — no single shape is
+  accepted by every provider — and so does a nullable type at the parameters root, in
+  a branch of a root `anyOf`/`oneOf`, or in a composition branch whose
+  `required` resolves against the enclosing node.
 - `runToolLoop` now returns `ToolLoopResult` (`{ stopReason, stats }`) instead
   of `void`. A caller that ignores the return value is unchanged, but a
   wrapper *annotated* `Promise<void>` no longer typechecks — widen it to
@@ -1048,6 +1069,15 @@ property; a boolean `additionalProperties: false` on a nested object; and a
 parameter literally named `properties`. Run it on third-party (e.g. MCP) tool
 schemas too — those are where the violations usually come from.
 
+One transform is worth knowing about even if no provider forced it. A **nullable
+property** — `{type:["string","null"], minLength:1}` — is rewritten to
+`{anyOf:[{type:"string",minLength:1},{type:"null"}]}` rather than reduced to its
+non-null type with a note on the description. Reducing it is what a strict
+provider needs, but it leaves the model unable to say "none" in the part of the
+declaration it treats as binding, so it invents a value that satisfies the type:
+`"/"`, `" "`, `"null"`, `"undefined"`. If you author nullable parameters, you do
+not need to hand-write the union — the sanitizer produces it.
+
 ### How to repair a transcript before sending it
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "12.0.0",
+  "version": "14.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

@@ -32,13 +32,64 @@
  * 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.
+ *   1. Resolve a `type` ARRAY, which Gemini rejects outright (it requires a
+ *      scalar `type`). Two cases, and they are not the same kind of loss:
+ *
+ *      a. NULLABLE single type — exactly one non-`"null"` member plus `"null"`,
+ *         in either order, duplicates tolerated. Rewritten to
+ *         `anyOf: [ <T branch>, {type:"null"} ]`, where the T branch carries
+ *         the node's type-bearing keywords (`minLength`, `enum`, `properties`,
+ *         `items`, bounds, …) under `type: T` and the node keeps its
+ *         annotations. The branch is re-entered through this same walk, so
+ *         every per-node transform applies to it — #12 retypes it to `"object"`
+ *         when it carries `properties`, #13 drops an unsupported `pattern` into
+ *         prose ON the branch, #2 filters its `enum`, #3 resolves its
+ *         `required` against its own `properties`.
+ *
+ *         Collapsing this case instead was lossy in a way that broke callers in
+ *         production. A model handed `{type:"string", minLength:1,
+ *         description:"… or send null …"}` cannot express "none" in the half of
+ *         the declaration it treats as binding, so it INVENTS a value that
+ *         satisfies the type: `slack_send_message.thread_ts` (authored
+ *         `type:["string","null"], minLength:1`) received `"/"`, `". "`,
+ *         `".000001"` and the like for thousands of calls, each refused by
+ *         Slack and each retried; a Drive pagination cursor had already been
+ *         seen taking `"x"`, `" "`, `"undefined"`, `"null"` and `"/"`. Prose
+ *         loses to the schema every time. The `anyOf` shape is not a guess: it
+ *         passes under `properties` on grok-4.3/4.5/4.6,
+ *         gemini-3.5/3.6/3.7-flash and gpt-5.6-terra/sol/luna, and it ships
+ *         today on every pagination cursor of six connectors. No "Accepts T or
+ *         null." note is added — the schema now says it — and an `enum` that
+ *         listed `null` contributes only its non-null members to the branch,
+ *         with no "May also be null." note, since the null branch carries that.
+ *         A sibling `enum`/`const` that EXCLUDES one arm keeps case (b)
+ *         instead: those keywords are AND-ed with `type`, so
+ *         `{type:["string","null"], enum:["x"]}` means "must be \"x\"", and a
+ *         union whose null branch the enum never reaches would admit a value
+ *         the node forbade.
+ *
+ *         Four shapes opt out. The parameters ROOT, which has to be an object
+ *         for every provider (transform #9 owns it). A branch of a ROOT
+ *         `anyOf`/`oneOf`, because a root union branch carrying its OWN `anyOf`
+ *         is 0/3 on Grok — rewriting there would turn a usable branch into one
+ *         rule (a) drops, taking the whole keyword and every shape it
+ *         advertised with it. And a COMPOSITION BRANCH whose `required` reaches
+ *         the ENCLOSING node's `properties` — the extra scope transform #8
+ *         gives it — because nesting such a name inside an `anyOf` puts it two
+ *         levels from that scope, where transform #3 prunes it away entirely
+ *         (a branch whose `required` its own `properties` cover needs no
+ *         exception). All three keep case (b). (One residue is known and accepted: a `$defs` target
+ *         rewritten this way, then inlined into a root union branch by
+ *         transform #14, is unusable for the same 0/3 reason and still drops
+ *         the keyword — the same narrow class #14 already documents.)
+ *
+ *      b. Everything else — a genuine MULTI-type union, which has no shape
+ *         every provider accepts. Collapsed to the first non-`"null"` member
+ *         (`["string","number","boolean"]` → `"string"`) with the alternatives
+ *         folded into `description`; 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,
@@ -174,8 +225,11 @@
  *           `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.
+ *           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
@@ -187,12 +241,36 @@
  *      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 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
+ *      (a union of its own included, which is what a `$defs` entry transform
+ *      #1a rewrote becomes), 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
@@ -201,11 +279,78 @@
  *      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
- * node's `description` as prose ("Accepts string, number, or boolean.",
+ *  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 (1b) or (2) discards information the model could use — a collapsed
+ * multi-type union, 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.
+ * string every provider accepts, so this is always safe. Prose is the fallback,
+ * never the first choice: where a shape every provider accepts exists, the
+ * schema says it instead — which is the whole of (1a).
  *
  * It deliberately leaves meaningful validation keywords (`format`,
  * `pattern`, object- or `true`-valued `additionalProperties`, `const`, string