toolgz 0.1.1 → 0.1.2

package/dist/index.js

@@ -1,5 +1,6 @@
 import { countSchemaTokensApprox, defaultNamespaceOf, firstSentence, flattenSchema, normalize, signatureLine, terseDescriptor, } from "./render/index.js";
 import { validateArgs } from "./runtime/validate.js";
+import { nearest } from "./runtime/similar.js";
 export * from "./types.js";
 export { flattenSchema, signatureLine, countSchemaTokensApprox } from "./render/index.js";
 const CODE_CHARS = "abcdefghijklmnopqrstuvwxyz";
@@ -79,6 +80,44 @@ export function compress(input, options = {}) {
             });
         }
     }
+    /**
+     * Separator-insensitive lookup for level-3 map keys.
+     *
+     * Observed on gpt-5.6-sol against real MCP tools: the model reassembled a
+     * namespaced name with a DOT where the real tool uses an underscore —
+     * `gdrive.sheets_append_rows`, `coding.task_result`, `reverse.geocode`. Joining a
+     * namespace and an operation with `.` is the ordinary convention for qualified
+     * identifiers, so the inference is reasonable and ours was simply too strict.
+     * Rejecting it burned six turns per task.
+     *
+     * Keys are therefore compared with every separator stripped, which accepts `.`,
+     * `:`, `/`, `-`, a space, or nothing. Registered ONLY where the normalised form
+     * is unambiguous: if two tools normalise alike neither is aliased and the exact
+     * name is required, so this can never silently dispatch the wrong tool.
+     */
+    const normKey = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const normIndex = new Map();
+    const registerNorm = (key, t) => {
+        const k = normKey(key);
+        if (!k)
+            return;
+        const seen = normIndex.get(k);
+        if (seen === undefined)
+            normIndex.set(k, t); // first claim
+        else if (seen && seen.name !== t.name)
+            normIndex.set(k, null); // ambiguous
+    };
+    if (level === 3) {
+        for (const t of tools)
+            registerNorm(t.name, t);
+        for (const [code, t] of codeToTool)
+            registerNorm(code, t);
+    }
+    /** Exact map key first, then the separator-insensitive fallback. */
+    const lookupMapKey = (raw) => {
+        const key = String(raw ?? "");
+        return codeToTool.get(key) ?? normIndex.get(normKey(key)) ?? undefined;
+    };
     const finish = (wire, systemPreamble, cachePreamble, resolve, encode) => {
         const compressedChars = countSchemaTokensApprox(wire) + systemPreamble.length;
         return {
@@ -257,11 +296,25 @@ export function compress(input, options = {}) {
             ? "Each line is: code name(args), where ? marks optional. "
             : "";
     const systemPreamble = `<toolmap>\n${lines.join("\n")}\n</toolmap>\n${mapLegend}Invoke with t(f=<code>, a={…}). Use q to expand a code before calling if you are unsure of its parameters.`;
-    return finish(wire, systemPreamble, true, (name, rawArgs) => {
-        const args = asObject(rawArgs);
+    return finish(wire, systemPreamble, true, (rawName, rawArgs) => {
+        let name = rawName;
+        let args = asObject(rawArgs);
+        // Observed on grok-4.5, on every level-3 map style: the model routes the
+        // lookup tool through the dispatcher — t(f="q", a={s:"…"}) instead of
+        // q(s="…"). The preamble invites it, saying "Invoke with t(f=<code>, a={…})"
+        // and then "Use q to expand a code", which reads as everything going through
+        // t. Tasks still completed, so this surfaced as wasted turns rather than as
+        // failure. `t` and `q` are our own reserved names, so the intent is
+        // unambiguous — nothing else could be meant.
+        if (name === "t" && (args.f === "q" || args.f === "t")) {
+            const nested = asObject(args.a);
+            const flat = Object.fromEntries(Object.entries(args).filter(([k]) => k !== "f" && k !== "a"));
+            name = String(args.f);
+            args = Object.keys(nested).length ? nested : flat;
+        }
         if (name === "q") {
             if (args.c !== undefined) {
-                const t = codeToTool.get(String(args.c));
+                const t = lookupMapKey(args.c);
                 if (!t)
                     return err(`No map code "${args.c}". Search with q(s=…).`);
                 return {
@@ -286,13 +339,17 @@ export function compress(input, options = {}) {
         // claude-opus-5: name="b5", args={f:"b5", a:"{…}"}. Codes are unique and
         // cannot collide with `t` or `q`, so this form is unambiguous and
         // accepting it removes a whole class of wasted turn.
-        const viaCode = name !== "t" && name !== "q" ? codeToTool.get(name) : undefined;
+        const viaCode = name !== "t" && name !== "q" ? lookupMapKey(name) : undefined;
         if (!viaCode && name !== "t") {
             return err(`No tool named "${name}". Invoke tools with t(f=<code>).`);
         }
-        const t = viaCode ?? codeToTool.get(String(args.f));
-        if (!t)
-            return err(`No map code "${args.f}". Search with q(s=…).`);
+        const t = viaCode ?? lookupMapKey(args.f);
+        if (!t) {
+            // A near miss is the common case, and a bare rejection costs another turn.
+            const guess = nearest(String(args.f ?? ""), [...codeToTool.keys()]);
+            return err(`No map code "${args.f}". Search with q(s=…).` +
+                (guess ? ` Did you mean "${guess}"? Use it exactly as written in <toolmap>.` : ""));
+        }
         // Args may arrive nested under `a`, or flat alongside `f`. Prefer `a`
         // when present rather than merging, so there is one source of truth.
         const nested = asObject(args.a);

package/dist/render/index.js

@@ -128,7 +128,20 @@ export function normalize(tools, namespaceOf) {
         if (seen.has(t.name))
             throw new Error(`duplicate tool name: ${t.name}`);
         seen.add(t.name);
-        const { ns, op } = namespaceOf(t.name);
+        // Validate the callback's return rather than trusting it. The contract is
+        // easy to get wrong — it takes a name and returns {ns, op}, not a bare
+        // namespace string — and the failure was silent and remote: every tool
+        // collapsed into one `undefined` namespace, level 2 emitted a wire tool with
+        // an empty name, and the first symptom was the provider rejecting the request
+        // with "tools.0.custom.name: Field required", nowhere near the cause.
+        const parts = namespaceOf(t.name);
+        const ns = parts?.ns;
+        const op = parts?.op;
+        if (typeof ns !== "string" || !ns || typeof op !== "string" || !op) {
+            throw new Error(`namespaceOf("${t.name}") must return { ns, op } with non-empty strings, ` +
+                `got ${JSON.stringify(parts)}. ` +
+                `Example: (name) => ({ ns: serverOf(name), op: name }).`);
+        }
         return {
             name: t.name,
             description: t.description ?? "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolgz",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Compress LLM tool definitions to reclaim context window. Measured across Anthropic, OpenAI, Google and xAI.",
   "main": "dist/index.js",
   "scripts": {