@juspay/neurolink 10.4.0 → 10.4.2

package/dist/providers/googleVertex.js

@@ -26,6 +26,7 @@ import { TimeoutError, raceWithAbort, withTimeout, } from "../utils/async/index.
 import { parseTimeout } from "../utils/timeout.js";
 import { appendStepText, buildAbortedTurnMessage, buildContextCapMessage, buildToolLoopCapMessage, buildTurnStalledMessage, buildTurnTimeoutMessage, buildWrapupNudgeText, createContextGuard, createTextChannel, createTurnClock, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, DedupExecuteMap, } from "./googleNativeGemini3.js";
 import { getContextWindowSize } from "../constants/contextWindows.js";
+import { resolveLiveTool } from "../tools/toolDiscovery.js";
 import { ATTR, LANGFUSE_ATTR, spanJsonAttribute, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../telemetry/index.js";
 import { SpanKind, SpanStatusCode, context as otelContext, trace as otelTrace, } from "@opentelemetry/api";
 import { calculateCost } from "../utils/pricing.js";
@@ -997,6 +998,168 @@ export class GoogleVertexProvider extends BaseProvider {
             },
         });
     }
+    /**
+     * Convert one AI-SDK tool into a Vertex Gemini function declaration.
+     * Single source for the pre-loop snapshot AND the mid-turn discovery
+     * refresh, so tools hydrated by search_tools get the exact same schema
+     * treatment (inline, typed, additionalProperties stripped).
+     */
+    buildGeminiFunctionDeclaration(name, tool) {
+        const decl = {
+            name,
+            description: tool.description || `Tool: ${name}`,
+        };
+        // Access legacy `parameters` (AI SDK v3/v4) or current `inputSchema` (v6)
+        const legacyTool = tool;
+        const toolParams = legacyTool.parameters || tool.inputSchema;
+        if (toolParams) {
+            // Convert and inline schema to resolve $ref/definitions
+            const rawSchema = convertZodToJsonSchema(toolParams, "openApi3");
+            const inlinedSchema = inlineJsonSchema(rawSchema);
+            // Remove $schema if present - @google/genai doesn't need it
+            if (inlinedSchema.$schema) {
+                delete inlinedSchema.$schema;
+            }
+            // CRITICAL: Google Vertex AI requires ALL nested schemas to have a type field
+            // ensureNestedSchemaTypes recursively adds missing type fields to tool schemas
+            // Note: convertZodToJsonSchema now uses openApi3 target which produces nullable: true
+            const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
+            // Strip `additionalProperties` recursively — Vertex Gemini's
+            // function-call validator rejects it on object schemas (returns
+            // 400 INVALID_ARGUMENT) even though it's valid OpenAPI 3. The
+            // field has no semantic meaning to the model, so dropping it
+            // before send is safe for every caller.
+            stripAdditionalPropertiesDeep(typedSchema);
+            decl.parametersJsonSchema = typedSchema;
+        }
+        return decl;
+    }
+    /**
+     * Mid-turn tool sync for the native Gemini loops. `search_tools` hydrates
+     * discovered tools into the live `options.tools` record between steps, but
+     * the loop's declarations + executeMap are a pre-loop snapshot — without
+     * this refresh, a tool discovered this turn stays invisible to the rest of
+     * the turn and every call to it dies as TOOL_NOT_FOUND. Mutates the
+     * declaration array in place (the request config holds it by reference)
+     * and clears breaker strikes accrued while the tool was still deferred.
+     */
+    refreshGeminiToolDeclarations(liveTools, declarations, executeMap, failedTools) {
+        if (!liveTools || !declarations) {
+            return;
+        }
+        const declared = new Set(declarations.map((d) => d.name));
+        for (const [name, tool] of Object.entries(liveTools)) {
+            if (declared.has(name)) {
+                continue;
+            }
+            declarations.push(this.buildGeminiFunctionDeclaration(name, tool));
+            if (tool.execute) {
+                executeMap.set(name, tool.execute);
+            }
+            failedTools.delete(name);
+            logger.info(`[GoogleVertex] Tool "${name}" hydrated mid-turn via discovery — added to Gemini declarations.`);
+        }
+    }
+    /**
+     * Dispatch-miss recovery for the native Gemini loops: the model called a
+     * name missing from the executeMap snapshot. Re-read the live record (a
+     * tool hydrated by search_tools in this very step batch) or auto-hydrate a
+     * deferred catalog tool the model called directly by its advertised name.
+     * Returns the dedup-wrapped executor, or undefined when the name is
+     * genuinely unknown — callers keep TOOL_NOT_FOUND for that case.
+     */
+    resolveGeminiToolOnMiss(name, liveTools, declarations, executeMap, failedTools) {
+        if (!declarations) {
+            return undefined;
+        }
+        const tool = resolveLiveTool(liveTools, name);
+        if (!tool?.execute) {
+            return undefined;
+        }
+        if (!declarations.some((d) => d.name === name)) {
+            declarations.push(this.buildGeminiFunctionDeclaration(name, tool));
+        }
+        executeMap.set(name, tool.execute);
+        // NOT_FOUND strikes accrued while the tool was deferred are snapshot
+        // artifacts, not real failures — reset so the breaker starts clean.
+        failedTools.delete(name);
+        logger.info(`[GoogleVertex] Tool "${name}" resolved mid-turn via discovery — executing.`);
+        return executeMap.get(name);
+    }
+    /**
+     * Convert one AI-SDK tool into an Anthropic (Claude-on-Vertex) tool
+     * declaration. Single source for the pre-loop snapshot AND the mid-turn
+     * discovery refresh — Anthropic validates input_schema as JSON Schema
+     * draft 2020-12 and rejects OpenAPI-3 dialect (`nullable: true`), so this
+     * uses the default JSON Schema target, matching the direct anthropic
+     * provider. The Gemini paths keep "openApi3".
+     */
+    buildAnthropicToolDeclaration(name, tool) {
+        const anthropicTool = {
+            name,
+            description: tool.description || `Tool: ${name}`,
+            input_schema: {
+                type: "object",
+            },
+        };
+        // Access legacy `parameters` (AI SDK v3/v4) or current `inputSchema` (v6)
+        const legacyTool = tool;
+        const toolParams = legacyTool.parameters || tool.inputSchema;
+        if (toolParams) {
+            const jsonSchema = convertZodToJsonSchema(toolParams);
+            const inlined = inlineJsonSchema(jsonSchema);
+            anthropicTool.input_schema = {
+                type: "object",
+                properties: inlined.properties || {},
+                required: inlined.required || [],
+            };
+        }
+        return anthropicTool;
+    }
+    /**
+     * Mid-turn tool sync for the Claude-on-Vertex loops — the Anthropic
+     * counterpart of refreshGeminiToolDeclarations. Claude only calls tools
+     * present in the request's `tools` array, so without this per-step refresh
+     * a tool discovered via search_tools is unreachable for the rest of the
+     * turn. Mutates the array in place (requestParams holds it by reference).
+     */
+    refreshAnthropicToolDeclarations(liveTools, declarations, executeMap, failedTools) {
+        if (!liveTools || !declarations) {
+            return;
+        }
+        const declared = new Set(declarations.map((d) => d.name));
+        for (const [name, tool] of Object.entries(liveTools)) {
+            if (declared.has(name)) {
+                continue;
+            }
+            declarations.push(this.buildAnthropicToolDeclaration(name, tool));
+            if (tool.execute) {
+                executeMap.set(name, tool.execute);
+            }
+            failedTools.delete(name);
+            logger.info(`[GoogleVertex] Tool "${name}" hydrated mid-turn via discovery — added to Anthropic declarations.`);
+        }
+    }
+    /**
+     * Dispatch-miss recovery for the Claude-on-Vertex loops — the Anthropic
+     * counterpart of resolveGeminiToolOnMiss.
+     */
+    resolveAnthropicToolOnMiss(name, liveTools, declarations, executeMap, failedTools) {
+        if (!declarations) {
+            return undefined;
+        }
+        const tool = resolveLiveTool(liveTools, name);
+        if (!tool?.execute) {
+            return undefined;
+        }
+        if (!declarations.some((d) => d.name === name)) {
+            declarations.push(this.buildAnthropicToolDeclaration(name, tool));
+        }
+        executeMap.set(name, tool.execute);
+        failedTools.delete(name);
+        logger.info(`[GoogleVertex] Tool "${name}" resolved mid-turn via discovery — executing.`);
+        return executeMap.get(name);
+    }
     /**
      * Execute stream using native @google/genai SDK for Gemini 3 models on Vertex AI
      * This bypasses @ai-sdk/google-vertex to properly handle thought_signature
@@ -1144,34 +1307,7 @@ export class GoogleVertexProvider extends BaseProvider {
             !options.disableTools) {
             const functionDeclarations = [];
             for (const [name, tool] of Object.entries(options.tools)) {
-                const decl = {
-                    name,
-                    description: tool.description || `Tool: ${name}`,
-                };
-                // Access legacy `parameters` (AI SDK v3/v4) or current `inputSchema` (v6)
-                const legacyTool = tool;
-                const toolParams = legacyTool.parameters || tool.inputSchema;
-                if (toolParams) {
-                    // Convert and inline schema to resolve $ref/definitions
-                    const rawSchema = convertZodToJsonSchema(toolParams, "openApi3");
-                    const inlinedSchema = inlineJsonSchema(rawSchema);
-                    // Remove $schema if present - @google/genai doesn't need it
-                    if (inlinedSchema.$schema) {
-                        delete inlinedSchema.$schema;
-                    }
-                    // CRITICAL: Google Vertex AI requires ALL nested schemas to have a type field
-                    // ensureNestedSchemaTypes recursively adds missing type fields to tool schemas
-                    // Note: convertZodToJsonSchema now uses openApi3 target which produces nullable: true
-                    const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
-                    // Strip `additionalProperties` recursively — Vertex Gemini's
-                    // function-call validator rejects it on object schemas (returns
-                    // 400 INVALID_ARGUMENT) even though it's valid OpenAPI 3. The
-                    // field has no semantic meaning to the model, so dropping it
-                    // before send is safe for every caller.
-                    stripAdditionalPropertiesDeep(typedSchema);
-                    decl.parametersJsonSchema = typedSchema;
-                }
-                functionDeclarations.push(decl);
+                functionDeclarations.push(this.buildGeminiFunctionDeclaration(name, tool));
                 if (tool.execute) {
                     executeMap.set(name, tool.execute);
                 }
@@ -1390,6 +1526,11 @@ export class GoogleVertexProvider extends BaseProvider {
                 }
                 step++;
                 turnClock.noteProgress();
+                // Mid-turn discovery sync: search_tools may have hydrated new tools
+                // into the live record during the previous step — advertise them in
+                // this step's request instead of leaving them invisible until the
+                // next turn (TOOL_NOT_FOUND).
+                this.refreshGeminiToolDeclarations(options.tools, tools?.[0]?.functionDeclarations, executeMap, failedTools);
                 logger.debug(`[GoogleVertex] Native SDK step ${step}/${maxSteps}`);
                 try {
                     const stream = await client.models.generateContentStream({
@@ -1565,7 +1706,13 @@ export class GoogleVertexProvider extends BaseProvider {
                             });
                             continue;
                         }
-                        const execute = executeMap.get(call.name);
+                        let execute = executeMap.get(call.name);
+                        if (!execute) {
+                            // Snapshot miss: the tool may have been hydrated into the live
+                            // record by search_tools within this very step batch, or the
+                            // model called a deferred catalog tool directly by name.
+                            execute = this.resolveGeminiToolOnMiss(call.name, options.tools, tools?.[0]?.functionDeclarations, executeMap, failedTools);
+                        }
                         if (execute) {
                             try {
                                 // AI SDK Tool execute requires (args, options) - provide minimal options
@@ -2089,34 +2236,7 @@ export class GoogleVertexProvider extends BaseProvider {
         if (Object.keys(combinedTools).length > 0) {
             const functionDeclarations = [];
             for (const [name, tool] of Object.entries(combinedTools)) {
-                const decl = {
-                    name,
-                    description: tool.description || `Tool: ${name}`,
-                };
-                // Access legacy `parameters` (AI SDK v3/v4) or current `inputSchema` (v6)
-                const legacyTool = tool;
-                const toolParams = legacyTool.parameters || tool.inputSchema;
-                if (toolParams) {
-                    // Convert and inline schema to resolve $ref/definitions
-                    const rawSchema = convertZodToJsonSchema(toolParams, "openApi3");
-                    const inlinedSchema = inlineJsonSchema(rawSchema);
-                    // Remove $schema if present - @google/genai doesn't need it
-                    if (inlinedSchema.$schema) {
-                        delete inlinedSchema.$schema;
-                    }
-                    // CRITICAL: Google Vertex AI requires ALL nested schemas to have a type field
-                    // ensureNestedSchemaTypes recursively adds missing type fields to tool schemas
-                    // Note: convertZodToJsonSchema now uses openApi3 target which produces nullable: true
-                    const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
-                    // Strip `additionalProperties` recursively — Vertex Gemini's
-                    // function-call validator rejects it on object schemas (returns
-                    // 400 INVALID_ARGUMENT) even though it's valid OpenAPI 3. The
-                    // field has no semantic meaning to the model, so dropping it
-                    // before send is safe for every caller.
-                    stripAdditionalPropertiesDeep(typedSchema);
-                    decl.parametersJsonSchema = typedSchema;
-                }
-                functionDeclarations.push(decl);
+                functionDeclarations.push(this.buildGeminiFunctionDeclaration(name, tool));
                 if (tool.execute) {
                     executeMap.set(name, tool.execute);
                 }
@@ -2324,6 +2444,8 @@ export class GoogleVertexProvider extends BaseProvider {
                 }
                 step++;
                 turnClock.noteProgress();
+                // Mid-turn discovery sync — see the stream twin.
+                this.refreshGeminiToolDeclarations(combinedTools, tools?.[0]?.functionDeclarations, executeMap, failedTools);
                 logger.debug(`[GoogleVertex] Native SDK generate step ${step}/${maxSteps}`);
                 try {
                     // Use generateContentStream and collect all chunks (same as GoogleAIStudio)
@@ -2495,7 +2617,11 @@ export class GoogleVertexProvider extends BaseProvider {
                             });
                             continue;
                         }
-                        const execute = executeMap.get(call.name);
+                        let execute = executeMap.get(call.name);
+                        if (!execute) {
+                            // Snapshot miss — see the stream twin.
+                            execute = this.resolveGeminiToolOnMiss(call.name, combinedTools, tools?.[0]?.functionDeclarations, executeMap, failedTools);
+                        }
                         if (execute) {
                             try {
                                 // AI SDK Tool execute requires (args, options) - provide minimal options
@@ -3122,30 +3248,7 @@ export class GoogleVertexProvider extends BaseProvider {
             !options.disableTools) {
             tools = [];
             for (const [name, tool] of Object.entries(options.tools)) {
-                const anthropicTool = {
-                    name,
-                    description: tool.description || `Tool: ${name}`,
-                    input_schema: {
-                        type: "object",
-                    },
-                };
-                // Access legacy `parameters` (AI SDK v3/v4) or current `inputSchema` (v6)
-                const legacyTool = tool;
-                const toolParams = legacyTool.parameters || tool.inputSchema;
-                if (toolParams) {
-                    // Anthropic validates input_schema as JSON Schema draft 2020-12 and
-                    // rejects OpenAPI-3 dialect output (e.g. `nullable: true`) with a
-                    // 400 — use the default JSON Schema target, matching the direct
-                    // anthropic provider. The Gemini paths keep "openApi3".
-                    const jsonSchema = convertZodToJsonSchema(toolParams);
-                    const inlined = inlineJsonSchema(jsonSchema);
-                    anthropicTool.input_schema = {
-                        type: "object",
-                        properties: inlined.properties || {},
-                        required: inlined.required || [],
-                    };
-                }
-                tools.push(anthropicTool);
+                tools.push(this.buildAnthropicToolDeclaration(name, tool));
                 if (tool.execute) {
                     executeMap.set(name, tool.execute);
                 }
@@ -3386,6 +3489,11 @@ export class GoogleVertexProvider extends BaseProvider {
                     }
                     step++;
                     turnClock.noteProgress();
+                    // Mid-turn discovery sync: Claude only calls tools declared in the
+                    // request, so tools hydrated by search_tools last step must be
+                    // advertised now (requestParams.tools holds this array by
+                    // reference).
+                    this.refreshAnthropicToolDeclarations(options.tools, tools, executeMap, failedTools);
                     // One generation observation per API call: request in, content + usage out.
                     const generationSpan = tracers.generation.startSpan("anthropic.messages.stream", {
                         kind: SpanKind.CLIENT,
@@ -3641,7 +3749,12 @@ export class GoogleVertexProvider extends BaseProvider {
                             }
                             toolSpan.end();
                         };
-                        const execute = executeMap.get(toolUse.name);
+                        let execute = executeMap.get(toolUse.name);
+                        if (!execute) {
+                            // Snapshot miss: hydrated by search_tools this step batch, or
+                            // a deferred catalog tool called directly by name.
+                            execute = this.resolveAnthropicToolOnMiss(toolUse.name, options.tools, tools, executeMap, failedTools);
+                        }
                         if (execute) {
                             try {
                                 const toolOptions = {
@@ -4435,30 +4548,7 @@ export class GoogleVertexProvider extends BaseProvider {
             Object.keys(options.tools).length > 0) {
             tools = [];
             for (const [name, tool] of Object.entries(options.tools)) {
-                const anthropicTool = {
-                    name,
-                    description: tool.description || `Tool: ${name}`,
-                    input_schema: {
-                        type: "object",
-                    },
-                };
-                // Access legacy `parameters` (AI SDK v3/v4) or current `inputSchema` (v6)
-                const legacyTool = tool;
-                const toolParams = legacyTool.parameters || tool.inputSchema;
-                if (toolParams) {
-                    // Anthropic validates input_schema as JSON Schema draft 2020-12 and
-                    // rejects OpenAPI-3 dialect output (e.g. `nullable: true`) with a
-                    // 400 — use the default JSON Schema target, matching the direct
-                    // anthropic provider. The Gemini paths keep "openApi3".
-                    const jsonSchema = convertZodToJsonSchema(toolParams);
-                    const inlined = inlineJsonSchema(jsonSchema);
-                    anthropicTool.input_schema = {
-                        type: "object",
-                        properties: inlined.properties || {},
-                        required: inlined.required || [],
-                    };
-                }
-                tools.push(anthropicTool);
+                tools.push(this.buildAnthropicToolDeclaration(name, tool));
                 if (tool.execute) {
                     executeMap.set(name, tool.execute);
                 }
@@ -4626,6 +4716,8 @@ export class GoogleVertexProvider extends BaseProvider {
             }
             step++;
             turnClock.noteProgress();
+            // Mid-turn discovery sync — see the stream twin.
+            this.refreshAnthropicToolDeclarations(options.tools, tools, executeMap, failedTools);
             try {
                 // Bound the SDK wait so a stalled Vertex/Anthropic call can't hang
                 // generate forever. options.timeout wins if set, otherwise default
@@ -4748,7 +4840,11 @@ export class GoogleVertexProvider extends BaseProvider {
                         });
                         continue;
                     }
-                    const execute = executeMap.get(toolUse.name);
+                    let execute = executeMap.get(toolUse.name);
+                    if (!execute) {
+                        // Snapshot miss — see the stream twin.
+                        execute = this.resolveAnthropicToolOnMiss(toolUse.name, options.tools, tools, executeMap, failedTools);
+                    }
                     if (execute) {
                         try {
                             const toolOptions = {

package/dist/providers/openaiChatCompletionsBase.js

@@ -31,6 +31,7 @@ import { composeAbortSignalsScoped, createTimeoutController, mergeAbortSignals,
 import { emitToolEndFromStepFinish } from "../utils/toolEndEmitter.js";
 import { resolveToolChoice } from "../utils/toolChoice.js";
 import { transformToolExecutions } from "../utils/transformationUtils.js";
+import { resolveDeferredTool } from "../tools/toolDiscovery.js";
 import { buildAPIError, buildBody, buildToolsForOpenAI, buildWireToolNameMaps, createChunkQueue, createDeferredAnalytics, ensureJsonWordInBody, estimateWireTokens, mapNeuroLinkToolChoice, mergeUsage, messageBuilderToOpenAI, parseSSEStream, stringifyToolOutput, stripTrailingSlash, v3ResponseFormatToOpenAI, v3ToolChoiceToOpenAI, v3ToolsToOpenAI, } from "./openaiChatCompletionsClient.js";
 /**
  * Safety margin (tokens) when fitting `max_tokens` to a runtime-discovered
@@ -730,7 +731,34 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         try {
             let stepFinish = null;
             let stepUsage;
+            // May grow mid-turn: hydrated tools with wire-unsafe names need
+            // reverse-mapping even when the initial name set required none.
+            let effectiveToolNameFromWire = toolNameFromWire;
             for (let step = 0; step < maxSteps; step++) {
+                // Mid-turn discovery sync: search_tools (tools.discovery) hydrates
+                // new tools into toolsRecord between steps. Dispatch already re-reads
+                // the record — this block makes the request DECLARE them so the model
+                // can call them, keeping the wire-name round-trip intact.
+                if (openAITools) {
+                    const declared = new Set(openAITools.map((t) => effectiveToolNameFromWire?.get(t.function.name) ??
+                        t.function.name));
+                    const hydrated = Object.fromEntries(Object.entries(toolsRecord).filter(([name]) => !declared.has(name)));
+                    if (Object.keys(hydrated).length > 0) {
+                        // Seed with the wire names already declared this turn — mapping
+                        // only the hydrated subset could otherwise re-issue a wire name
+                        // an earlier tool claimed (sanitized or literal), making the
+                        // reverse mapping ambiguous.
+                        const extraMaps = buildWireToolNameMaps(Object.keys(hydrated), new Set(openAITools.map((t) => t.function.name)));
+                        if (extraMaps) {
+                            effectiveToolNameFromWire ??= new Map();
+                            for (const [wireName, registryName] of extraMaps.fromWire) {
+                                effectiveToolNameFromWire.set(wireName, registryName);
+                            }
+                        }
+                        openAITools.push(...(buildToolsForOpenAI(hydrated, extraMaps?.toWire) ?? []));
+                        logger.info(`${this.providerName}: ${Object.keys(hydrated).length} tool(s) hydrated mid-turn via discovery: ${Object.keys(hydrated).join(", ")}`);
+                    }
+                }
                 const stepResult = await this.streamOneStep({
                     modelId,
                     url,
@@ -753,7 +781,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                     stepResult,
                     conversation,
                     toolsRecord,
-                    toolNameFromWire,
+                    toolNameFromWire: effectiveToolNameFromWire,
                     emitter,
                     toolsUsed,
                     toolExecutionSummaries,
@@ -876,7 +904,11 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             // reporting use the registered names (reverse-mapped when a wire-name
             // map is in effect — see buildWireToolNameMaps).
             const registryName = toolNameFromWire?.get(t.name) ?? t.name;
-            const toolDef = toolsRecord[registryName];
+            // Live record lookup, then deferred-catalog auto-hydration: with
+            // tools.discovery on, the model may call a cataloged tool it never
+            // loaded via search_tools — that's a real tool, not a hallucination.
+            const toolDef = toolsRecord[registryName] ??
+                resolveDeferredTool(toolsRecord, registryName);
             emitter?.emit("tool:start", {
                 toolName: registryName,
                 toolCallId: t.id,

package/dist/providers/openaiChatCompletionsClient.d.ts

@@ -17,12 +17,18 @@ import type { OpenAICompatBuildBodyArgs, OpenAICompatChatMessage, OpenAICompatCh
 export declare const stripTrailingSlash: (s: string) => string;
 /**
  * Build a bijective original ↔ wire tool-name map. Returns undefined when
- * every name is already wire-valid (the common case — the wire then uses
- * original names untouched and callers skip all mapping). Sanitized names
- * that collide get a deterministic numeric suffix so the map stays
- * invertible.
+ * every name is already wire-valid and unreserved (the common case — the
+ * wire then uses original names untouched and callers skip all mapping).
+ * Sanitized names that collide get a deterministic numeric suffix so the
+ * map stays invertible.
+ *
+ * `reservedWireNames` seeds the collision set with wire names already
+ * declared in the request — a mid-turn discovery refresh maps only the
+ * newly hydrated subset, and without seeding a hydrated name (sanitized OR
+ * wire-valid) could reuse a wire name an earlier tool already claimed,
+ * making the reverse mapping ambiguous.
  */
-export declare const buildWireToolNameMaps: (names: readonly string[]) => {
+export declare const buildWireToolNameMaps: (names: readonly string[], reservedWireNames?: ReadonlySet<string>) => {
     toWire: Map<string, string>;
     fromWire: Map<string, string>;
 } | undefined;

package/dist/providers/openaiChatCompletionsClient.js

@@ -28,27 +28,33 @@ export const stripTrailingSlash = (s) => s.replace(/\/+$/, "");
 const WIRE_TOOL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$/;
 /**
  * Build a bijective original ↔ wire tool-name map. Returns undefined when
- * every name is already wire-valid (the common case — the wire then uses
- * original names untouched and callers skip all mapping). Sanitized names
- * that collide get a deterministic numeric suffix so the map stays
- * invertible.
+ * every name is already wire-valid and unreserved (the common case — the
+ * wire then uses original names untouched and callers skip all mapping).
+ * Sanitized names that collide get a deterministic numeric suffix so the
+ * map stays invertible.
+ *
+ * `reservedWireNames` seeds the collision set with wire names already
+ * declared in the request — a mid-turn discovery refresh maps only the
+ * newly hydrated subset, and without seeding a hydrated name (sanitized OR
+ * wire-valid) could reuse a wire name an earlier tool already claimed,
+ * making the reverse mapping ambiguous.
  */
-export const buildWireToolNameMaps = (names) => {
-    if (names.every((name) => WIRE_TOOL_NAME_RE.test(name))) {
+export const buildWireToolNameMaps = (names, reservedWireNames) => {
+    if (names.every((name) => WIRE_TOOL_NAME_RE.test(name) && !reservedWireNames?.has(name))) {
         return undefined;
     }
     const toWire = new Map();
     const fromWire = new Map();
     for (const name of names) {
         let wire = WIRE_TOOL_NAME_RE.test(name) ? name : sanitizeToolName(name);
-        if (fromWire.has(wire)) {
+        if (fromWire.has(wire) || reservedWireNames?.has(wire)) {
             let suffix = 2;
             let candidate;
             do {
                 const tail = `_${suffix}`;
                 candidate = `${wire.slice(0, 64 - tail.length)}${tail}`;
                 suffix++;
-            } while (fromWire.has(candidate));
+            } while (fromWire.has(candidate) || reservedWireNames?.has(candidate));
             wire = candidate;
         }
         toWire.set(name, wire);

package/dist/tools/toolDiscovery.d.ts

@@ -6,12 +6,19 @@
  * requested tools, and previously discovered tools) plus ONE `search_tools`
  * meta-tool whose description embeds a compact name+summary catalog of the
  * deferred tools. Calling `search_tools` loads matching tools:
- *  - immediately into the live tool record (providers that re-read the tools
- *    record between agent-loop steps — the AI SDK path — can call them on the
- *    very next step), and
+ *  - immediately into the live tool record — the AI SDK path re-reads the
+ *    record between agent-loop steps, and the native loops (Vertex
+ *    Gemini/Claude, AI Studio, chat-completions, direct Anthropic) re-resolve
+ *    against it on a dispatch miss and refresh their wire declarations per
+ *    step — so discovered tools are callable on the very next step, and
  *  - into the session pin set (all providers include them in full on every
  *    subsequent call of the session).
  *
+ * The record additionally carries a symbol-keyed {@link DeferredToolResolver}
+ * (see `resolveDeferredTool`) so a loop can hydrate a cataloged tool the
+ * model called directly by name WITHOUT a prior search_tools call — the
+ * catalog advertises exact names, so models legitimately do this.
+ *
  * Evidence for this design: catalogs past ~30-50 tools measurably degrade
  * tool-selection accuracy, and deferral+search both cuts definition tokens by
  * ~85% and RAISES selection accuracy (Anthropic MCP-eval 49%→74% on Opus 4).
@@ -46,3 +53,18 @@ export declare function partitionToolsForDiscovery(tools: Record<string, Tool>,
     /** Called with newly discovered names — persists session pins. */
     onHydrate: (names: string[]) => void;
 }): Record<string, Tool>;
+/**
+ * Hydrate-and-return a deferred tool by name, when `record` was produced by
+ * `partitionToolsForDiscovery` and `name` is in its deferred catalog.
+ * Returns `undefined` for records without a resolver (discovery off) and for
+ * names that are genuinely unknown — callers keep their hallucinated-name
+ * handling for that case.
+ */
+export declare function resolveDeferredTool(record: Record<string, Tool> | undefined, name: string): Tool | undefined;
+/**
+ * Live tool lookup for native agent loops on a dispatch miss: first re-reads
+ * the record (a tool hydrated by search_tools after the loop built its
+ * pre-step snapshot), then falls back to auto-hydrating from the deferred
+ * catalog. Returns `undefined` only when the name is genuinely unknown.
+ */
+export declare function resolveLiveTool(record: Record<string, Tool> | undefined, name: string): Tool | undefined;