@juno-ai/bind 2.0.0 → 4.0.0

package/run/tool-batch.d.ts

@@ -0,0 +1,16 @@
+import type OpenAI from "openai";
+/**
+ * Run a batch of tool calls concurrently with per-tool-name pooling. Calls
+ * to different tools fan out fully; calls to the *same* tool are capped at
+ * `PER_TOOL_POOL_SIZE` so a batch of many calls to one downstream service does
+ * not overwhelm it. Results are
+ * returned in the same order as `calls`, each as a `PromiseSettledResult`
+ * so the caller can synthesize error tool messages for any rejections
+ * (every `tool_call_id` in the assistant message still needs a response).
+ *
+ * Generic over the per-call outcome: the pooling and ordering policy is
+ * harness-owned, while the shape a host derives from a completed call (which
+ * plugin activated, whether the run should compact, a suspend directive, …)
+ * stays with the host.
+ */
+export declare function runToolCallsPooledByTool<TOutcome>(calls: OpenAI.ChatCompletionMessageToolCall[], run: (tc: OpenAI.ChatCompletionMessageToolCall) => Promise<TOutcome>): Promise<PromiseSettledResult<TOutcome>[]>;

package/run/tool-batch.js

@@ -0,0 +1,83 @@
+// Per-tool concurrency ceiling inside a single LLM tool-call batch. A model
+// response can request many calls to the same tool; running them all at once
+// would hammer whatever it talks to (a search backend, a database, a
+// third-party API). Calls to *different* tools still fan out fully — the cap
+// is applied per tool name, not globally.
+const PER_TOOL_POOL_SIZE = 5;
+/**
+ * The name a batch pools on. `function` and `custom` tool calls both carry a
+ * name, on different fields; anything the wire union grows later falls back to
+ * its type, which pools all such calls together rather than guessing.
+ */
+function poolKey(call) {
+    switch (call.type) {
+        case "function":
+            return call.function.name;
+        case "custom":
+            return `__custom__:${call.custom.name}`;
+        default: {
+            // Not `never`: this union is a third party's, and a new member must not
+            // become a type error in a consumer that never sees one.
+            const unknownCall = call;
+            return `__${unknownCall.type ?? "unknown"}__`;
+        }
+    }
+}
+/**
+ * Run a batch of tool calls concurrently with per-tool-name pooling. Calls
+ * to different tools fan out fully; calls to the *same* tool are capped at
+ * `PER_TOOL_POOL_SIZE` so a batch of many calls to one downstream service does
+ * not overwhelm it. Results are
+ * returned in the same order as `calls`, each as a `PromiseSettledResult`
+ * so the caller can synthesize error tool messages for any rejections
+ * (every `tool_call_id` in the assistant message still needs a response).
+ *
+ * Generic over the per-call outcome: the pooling and ordering policy is
+ * harness-owned, while the shape a host derives from a completed call (which
+ * plugin activated, whether the run should compact, a suspend directive, …)
+ * stays with the host.
+ */
+export async function runToolCallsPooledByTool(calls, run) {
+    if (calls.length === 0)
+        return [];
+    const results = new Array(calls.length);
+    const groups = new Map();
+    for (let i = 0; i < calls.length; i++) {
+        const tc = calls[i];
+        // Pool key is the tool name, wherever the wire union puts it — `custom`
+        // tool calls carry theirs on a different field, and pooling every one of
+        // them together would serialize unrelated tools behind each other. A future
+        // variant with no name at all falls back to its type; the `__` fencing
+        // keeps either synthetic key from colliding with a real tool name.
+        const key = poolKey(tc);
+        let arr = groups.get(key);
+        if (!arr) {
+            arr = [];
+            groups.set(key, arr);
+        }
+        arr.push(i);
+    }
+    await Promise.all(Array.from(groups.values()).map(async (indices) => {
+        // `cursor++` in single-threaded JS is atomic between awaits — no lock
+        // needed. Workers race for the next index; when cursor exceeds the
+        // group size the worker returns.
+        let cursor = 0;
+        const workerCount = Math.min(PER_TOOL_POOL_SIZE, indices.length);
+        await Promise.all(Array.from({ length: workerCount }, async () => {
+            while (true) {
+                const pos = cursor++;
+                if (pos >= indices.length)
+                    return;
+                const callIdx = indices[pos];
+                try {
+                    const value = await run(calls[callIdx]);
+                    results[callIdx] = { status: "fulfilled", value };
+                }
+                catch (reason) {
+                    results[callIdx] = { status: "rejected", reason };
+                }
+            }
+        }));
+    }));
+    return results;
+}

package/tools/index.d.ts

@@ -0,0 +1 @@
+export { sanitizeToolSchema } from "./sanitize-schema.js";

package/tools/index.js

@@ -0,0 +1 @@
+export { sanitizeToolSchema } from "./sanitize-schema.js";

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>;