@juspay/neurolink 10.4.1 → 10.4.3

package/dist/proxy/rollingWorkerSupervisor.js

@@ -79,7 +79,6 @@ export class RollingWorkerSupervisor {
                 ? this.replacement
                 : Promise.reject(ErrorFactory.proxyWorkerLifecycle(`worker replacement for v${this.candidate?.expectedVersion ?? "unknown"} is already in progress`, { requestedVersion: expectedVersion }));
         }
-        this.lastFailure = null;
         this.replacement = this.spawnCandidate(expectedVersion).finally(() => {
             this.replacement = null;
         });
@@ -242,6 +241,16 @@ export class RollingWorkerSupervisor {
                     }
                     return;
                 }
+                if (message.type === "proxy-worker:replacement-requested") {
+                    if (this.active?.generation === generation) {
+                        this.options.onReplacementRequested?.({
+                            generation,
+                            pid: handle.pid,
+                            reason: message.reason,
+                        });
+                    }
+                    return;
+                }
                 if (message.type === "proxy-worker:ready") {
                     if (message.version !== expectedVersion) {
                         finish(new Error(`worker ${handle.pid} reported v${message.version}; expected v${expectedVersion}`));
@@ -309,7 +318,7 @@ export class RollingWorkerSupervisor {
                     if (!this.closed) {
                         this.recordFailure(generation, expectedVersion, "runtime", `worker exited (code=${code ?? "none"}, signal=${signal ?? "none"})`);
                     }
-                    this.options.log?.(`[proxy-supervisor] active worker exited generation=${generation} pid=${handle.pid}`);
+                    this.options.log?.(`[proxy-supervisor] active worker exited generation=${generation} pid=${handle.pid} code=${code ?? "none"} signal=${signal ?? "none"}`);
                 }
                 const drained = this.draining.get(generation);
                 if (drained) {
@@ -356,23 +365,27 @@ export class RollingWorkerSupervisor {
         try {
             worker.handle.sendSocket(worker.generation, socket, (error) => {
                 if (error) {
-                    this.handleTransferFailure(worker, socket);
+                    this.handleTransferFailure(worker, socket, error);
                 }
             });
         }
-        catch {
-            this.handleTransferFailure(worker, socket);
+        catch (error) {
+            this.handleTransferFailure(worker, socket, error);
         }
     }
-    handleTransferFailure(worker, socket) {
+    handleTransferFailure(worker, socket, error) {
         this.failedTransfers += 1;
-        this.recordFailure(worker.generation, worker.version, "transfer", `worker ${worker.handle.pid} failed to accept a transferred socket`);
+        const detail = this.describeTransferError(error);
+        this.recordFailure(worker.generation, worker.version, "transfer", `worker ${worker.handle.pid} failed to accept a transferred socket: ${detail}`);
+        this.options.log?.(`[proxy-supervisor] socket transfer failed generation=${worker.generation} pid=${worker.handle.pid}: ${detail}`);
         if (this.active?.generation === worker.generation && !this.closed) {
-            // Do not let worker-side graceful shutdown call shutdown(2) on an
-            // offered-but-uncommitted duplicate descriptor.
-            worker.dispose();
-            worker.handle.terminate("SIGKILL");
             this.active = null;
+            this.draining.set(worker.generation, worker);
+            // The child may own a duplicate of an incompletely transferred socket.
+            // SIGKILL closes its descriptor without worker-side shutdown(2), after
+            // which the parent rejects its copy rather than attempting unsafe replay.
+            worker.handle.terminate("SIGKILL");
+            this.publishState();
         }
         this.rejectSocket(socket);
     }
@@ -381,6 +394,13 @@ export class RollingWorkerSupervisor {
         socket.destroy();
         this.publishState();
     }
+    describeTransferError(error) {
+        if (!(error instanceof Error)) {
+            return String(error ?? "unknown transfer failure");
+        }
+        const code = error.code;
+        return code ? `${code}: ${error.message}` : error.message;
+    }
     recordFailure(generation, version, phase, message) {
         this.lastFailure = {
             at: new Date().toISOString(),

package/dist/proxy/runtimeConfig.d.ts

@@ -10,6 +10,7 @@ export declare class ProxyRuntimeConfigStore {
     private reloadTimer;
     private configFileObserved;
     private envFileObserved;
+    private currentEnvFileHash;
     private readonly watchListener;
     private constructor();
     static create(options: ProxyRuntimeConfigStoreOptions): Promise<ProxyRuntimeConfigStore>;

package/dist/proxy/runtimeConfig.js

@@ -162,11 +162,13 @@ function assertResolvedRoutingValues(value, path = "routing") {
 async function buildCandidate(options, generation, allowMissingConfig, allowMissingEnvFile, rejectInvalidHotEnv) {
     const effectiveEnv = { ...options.baseEnv };
     let envFilePresent = false;
+    let envFileValues = {};
     if (options.envFilePath) {
         try {
-            const envContent = await readFile(options.envFilePath, "utf8");
+            const envFileContent = await readFile(options.envFilePath, "utf8");
             const { parse } = await import("dotenv");
-            Object.assign(effectiveEnv, parse(envContent));
+            envFileValues = parse(envFileContent);
+            Object.assign(effectiveEnv, envFileValues);
             envFilePresent = true;
         }
         catch (error) {
@@ -218,6 +220,12 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
             accountAllowlist: routing.accountAllowlist,
         })
         : undefined;
+    const envFileHash = createHash("sha256")
+        .update(envFilePresent
+        ? JSON.stringify(Object.entries(envFileValues).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0))
+        : "[missing]")
+        .digest("hex")
+        .slice(0, 16);
     const fingerprintSource = JSON.stringify({
         strategy,
         passthrough: options.passthrough,
@@ -249,6 +257,7 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         }),
         configFilePresent,
         envFilePresent,
+        envFileHash,
     };
 }
 /** Atomic last-known-good runtime configuration with file-triggered reloads. */
@@ -262,6 +271,7 @@ export class ProxyRuntimeConfigStore {
     reloadTimer;
     configFileObserved;
     envFileObserved;
+    currentEnvFileHash;
     watchListener = (current, previous) => {
         if (current.mtimeMs === previous.mtimeMs &&
             current.size === previous.size &&
@@ -270,11 +280,12 @@ export class ProxyRuntimeConfigStore {
         }
         this.scheduleWatchReload();
     };
-    constructor(options, snapshot, configFileObserved, envFileObserved) {
+    constructor(options, snapshot, configFileObserved, envFileObserved, envFileHash) {
         this.options = { ...options, baseEnv: { ...options.baseEnv } };
         this.currentSnapshot = snapshot;
         this.configFileObserved = configFileObserved;
         this.envFileObserved = envFileObserved;
+        this.currentEnvFileHash = envFileHash;
         this.status = {
             configPath: options.configPath,
             ...(options.envFilePath ? { envFilePath: options.envFilePath } : {}),
@@ -287,7 +298,7 @@ export class ProxyRuntimeConfigStore {
     }
     static async create(options) {
         const candidate = await buildCandidate(options, 1, true, true, false);
-        return new ProxyRuntimeConfigStore(options, candidate.snapshot, candidate.configFilePresent, candidate.envFilePresent);
+        return new ProxyRuntimeConfigStore(options, candidate.snapshot, candidate.configFilePresent, candidate.envFilePresent, candidate.envFileHash);
     }
     getSnapshot() {
         return this.currentSnapshot;
@@ -354,7 +365,8 @@ export class ProxyRuntimeConfigStore {
             const candidate = await buildCandidate(this.options, this.currentSnapshot.generation + 1, !this.configFileObserved, !this.envFileObserved, true);
             this.configFileObserved ||= candidate.configFilePresent;
             this.envFileObserved ||= candidate.envFilePresent;
-            if (candidate.snapshot.configHash === this.currentSnapshot.configHash) {
+            if (candidate.snapshot.configHash === this.currentSnapshot.configHash &&
+                candidate.envFileHash === this.currentEnvFileHash) {
                 this.status = {
                     ...this.status,
                     lastReloadAt: attemptedAt,
@@ -369,7 +381,9 @@ export class ProxyRuntimeConfigStore {
                 this.notifyReloadListeners(result);
                 return result;
             }
+            const environmentChanged = candidate.envFileHash !== this.currentEnvFileHash;
             this.currentSnapshot = candidate.snapshot;
+            this.currentEnvFileHash = candidate.envFileHash;
             this.status = {
                 ...this.status,
                 generation: candidate.snapshot.generation,
@@ -392,6 +406,7 @@ export class ProxyRuntimeConfigStore {
                 applied: true,
                 changed: true,
                 generation: candidate.snapshot.generation,
+                ...(environmentChanged ? { environmentChanged: true } : {}),
             };
             this.notifyReloadListeners(result);
             return result;

package/dist/proxy/socketWorkerRuntime.js

@@ -8,6 +8,7 @@ function isTransferableProxySocket(handle) {
         typeof candidate.resume === "function" &&
         typeof candidate.destroy === "function" &&
         typeof candidate.end === "function" &&
+        typeof candidate.off === "function" &&
         typeof candidate.once === "function");
 }
 function destroyTransferredHandle(handle) {
@@ -153,6 +154,16 @@ export function attachSocketWorkerProcess(server, input) {
         // synchronously here would truncate that in-flight request.
         setImmediate(() => runtime.drain());
     };
+    const takePendingSocket = (socketId) => {
+        const pending = pendingSockets.get(socketId);
+        if (!pending) {
+            return undefined;
+        }
+        pendingSockets.delete(socketId);
+        pending.socket.off("error", pending.onError);
+        pending.socket.off("close", pending.onClose);
+        return pending.socket;
+    };
     const onMessage = (message, handle) => {
         if (message &&
             typeof message === "object" &&
@@ -176,7 +187,27 @@ export function attachSocketWorkerProcess(server, input) {
                     socket.destroy();
                     return;
                 }
-                pendingSockets.set(socketId, socket);
+                // A client can reset while the transferred handle is paused between
+                // acceptance and commit. The HTTP server has not seen the socket yet,
+                // so it cannot install its normal transport-error handler for us.
+                const onError = () => {
+                    if (pendingSockets.get(socketId)?.socket !== socket) {
+                        return;
+                    }
+                    takePendingSocket(socketId);
+                    socket.destroy();
+                    drainWhenPendingSettled();
+                };
+                const onClose = () => {
+                    if (pendingSockets.get(socketId)?.socket !== socket) {
+                        return;
+                    }
+                    takePendingSocket(socketId);
+                    drainWhenPendingSettled();
+                };
+                pendingSockets.set(socketId, { socket, onError, onClose });
+                socket.once("error", onError);
+                socket.once("close", onClose);
                 try {
                     process.send({
                         type: "proxy-worker:socket-accepted",
@@ -185,14 +216,14 @@ export function attachSocketWorkerProcess(server, input) {
                         socketId,
                     }, (error) => {
                         if (error) {
-                            pendingSockets.delete(socketId);
-                            socket.destroy();
+                            takePendingSocket(socketId)?.destroy();
+                            drainWhenPendingSettled();
                         }
                     });
                 }
                 catch {
-                    pendingSockets.delete(socketId);
-                    socket.destroy();
+                    takePendingSocket(socketId)?.destroy();
+                    drainWhenPendingSettled();
                 }
             }
             else {
@@ -229,11 +260,10 @@ export function attachSocketWorkerProcess(server, input) {
             }
             else if (message.type === "proxy-worker:socket-commit" ||
                 message.type === "proxy-worker:socket-cancel") {
-                const socket = pendingSockets.get(message.socketId);
+                const socket = takePendingSocket(message.socketId);
                 if (!socket) {
                     return;
                 }
-                pendingSockets.delete(message.socketId);
                 if (message.type === "proxy-worker:socket-commit") {
                     runtime.acceptSocket(socket);
                 }
@@ -259,10 +289,9 @@ export function attachSocketWorkerProcess(server, input) {
     // is exiting. The zero-downtime guarantee applies to the rolling handoff
     // (control-message) path, not to process termination.
     const drain = () => {
-        for (const socket of pendingSockets.values()) {
-            socket.destroy();
+        for (const socketId of [...pendingSockets.keys()]) {
+            takePendingSocket(socketId)?.destroy();
         }
-        pendingSockets.clear();
         runtime.drain();
     };
     const onTerminationSignal = () => drain();
@@ -283,10 +312,9 @@ export function attachSocketWorkerProcess(server, input) {
             process.off("disconnect", drain);
             process.off("SIGTERM", onTerminationSignal);
             process.off("SIGINT", onTerminationSignal);
-            for (const socket of pendingSockets.values()) {
-                socket.destroy();
+            for (const socketId of [...pendingSockets.keys()]) {
+                takePendingSocket(socketId)?.destroy();
             }
-            pendingSockets.clear();
             runtime.close();
         },
     };

package/dist/server/routes/claudeProxyRoutes.js

@@ -2241,6 +2241,7 @@ async function handleAnthropicSuccessfulResponse(args) {
         attemptNumber,
         finalBodyStr,
         upstreamSpan,
+        logAttempt,
         logProxyBody,
         logFinalRequest,
     });
@@ -2248,6 +2249,8 @@ async function handleAnthropicSuccessfulResponse(args) {
 async function handleAnthropicStreamingSuccessResponse(args) {
     const { account, accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, } = args;
     if (!response.body) {
+        recordAttemptError(account.label, account.type, 502);
+        logAttempt(502, "stream_error", "No response body from upstream");
         upstreamSpan?.end();
         tracer?.setError("stream_error", "No response body from upstream");
         tracer?.end(502, Date.now() - requestStartTime);
@@ -2386,6 +2389,9 @@ async function handleAnthropicStreamingSuccessResponse(args) {
             failure: { message: preflight.message, rateLimit: isRateLimit },
         };
     }
+    logAttempt(response.status, undefined, undefined, {
+        attemptDurationMs: Date.now() - fetchStartMs,
+    });
     const streamOutcomeTracker = createStreamTerminalOutcomeTracker();
     let mainStreamClosed = false;
     const remainingStream = new ReadableStream({
@@ -2693,8 +2699,11 @@ function attachAnthropicSuccessStreamTelemetry(args) {
     });
 }
 async function handleAnthropicJsonSuccessResponse(args) {
-    const { account, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { account, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, } = args;
     const responseText = await response.text();
+    logAttempt(response.status, undefined, undefined, {
+        attemptDurationMs: Date.now() - fetchStartMs,
+    });
     tracer?.logUpstreamResponseBody(responseText);
     logProxyBody({
         phase: "upstream_response",
@@ -2779,8 +2788,8 @@ async function handleAnthropicJsonSuccessResponse(args) {
     }
     return { response: responseJson };
 }
-async function handleAnthropicSuccessfulRetryResponse(args) {
-    const { body, account, accountState, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+async function handleAnthropicSuccessfulNonStreamRetryResponse(args) {
+    const { account, accountState, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, } = args;
     const retryQuota = parseQuotaHeaders(retryResp.headers);
     if (retryQuota) {
         // Keep the auth-retry success path in parity with the main success path:
@@ -2802,63 +2811,11 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
             });
         });
     }
-    if (body.stream && retryResp.body) {
-        const retryReader = retryResp.body.getReader();
-        const streamOutcomeTracker = createStreamTerminalOutcomeTracker();
-        let retryStreamClosed = false;
-        const retryStream = new ReadableStream({
-            async pull(controller) {
-                if (retryStreamClosed) {
-                    return;
-                }
-                try {
-                    const { done, value } = await retryReader.read();
-                    if (retryStreamClosed) {
-                        return;
-                    }
-                    if (done) {
-                        retryStreamClosed = true;
-                        streamOutcomeTracker.complete();
-                        controller.close();
-                        return;
-                    }
-                    controller.enqueue(value);
-                }
-                catch (streamErr) {
-                    const errMsg = describeTransportError(streamErr);
-                    logger.always(`[proxy] mid-stream error (auth-retry) account=${account.label}: ${errMsg}`);
-                    streamOutcomeTracker.fail(errMsg);
-                    if (!retryStreamClosed) {
-                        retryStreamClosed = true;
-                        const errorEvent = `event: error\ndata: ${JSON.stringify({ type: "error", error: { type: "api_error", message: `Upstream stream interrupted: ${errMsg}` } })}\n\n`;
-                        controller.enqueue(new TextEncoder().encode(errorEvent));
-                        controller.close();
-                    }
-                }
-            },
-            cancel() {
-                retryStreamClosed = true;
-                streamOutcomeTracker.cancel();
-                return retryReader.cancel();
-            },
-        });
-        return attachAnthropicSuccessStreamTelemetry({
-            account,
-            response: retryResp,
-            responseHeaders: Object.fromEntries([...retryResp.headers.entries()]),
-            remainingStream: retryStream,
-            streamOutcome: streamOutcomeTracker.outcome,
-            tracer,
-            requestStartTime,
-            attemptNumber,
-            finalBodyStr,
-            upstreamSpan,
-            logProxyBody,
-            logFinalRequest,
-        });
-    }
     const retryRespHeaders = Object.fromEntries([...retryResp.headers.entries()]);
     const retryText = await retryResp.text();
+    logAttempt(retryResp.status, undefined, undefined, {
+        attemptDurationMs: Date.now() - fetchStartMs,
+    });
     tracer?.logUpstreamResponseHeaders(retryRespHeaders);
     tracer?.logUpstreamResponseBody(retryText);
     logProxyBody({
@@ -2960,7 +2917,7 @@ async function handleAnthropicAuthRetry(args) {
         const retryLogAttempt = (status, errorType, errorMessage, extra) => logAttempt(status, errorType, errorMessage, {
             ...extra,
             attempt: retryAttemptNumber,
-            attemptDurationMs: Date.now() - retryAttemptStartedAt,
+            attemptDurationMs: extra?.attemptDurationMs ?? Date.now() - retryAttemptStartedAt,
         });
         const retryBodyStr = buildUpstreamBody(account.token).bodyStr;
         const retryFetchStartMs = Date.now();
@@ -2986,23 +2943,54 @@ async function handleAnthropicAuthRetry(args) {
                 authRetrySucceeded = true;
                 accountState.consecutiveRefreshFailures = 0;
                 logger.always(`[proxy] ← 200 account=${account.label} (after ${authRetry + 1} refresh(es))`);
-                const successResponse = await handleAnthropicSuccessfulRetryResponse({
-                    ctx,
-                    body,
-                    account,
-                    accountState,
-                    retryResp,
-                    tracer,
-                    requestStartTime,
-                    fetchStartMs: retryFetchStartMs,
-                    attemptNumber: retryAttemptNumber,
-                    finalBodyStr: retryBodyStr,
-                    upstreamSpan: currentUpstreamSpan,
-                    logProxyBody,
-                    logFinalRequest,
-                });
+                const successResult = body.stream
+                    ? await handleAnthropicSuccessfulResponse({
+                        ctx,
+                        body,
+                        account,
+                        accountState,
+                        response: retryResp,
+                        tracer,
+                        requestStartTime,
+                        fetchStartMs: retryFetchStartMs,
+                        attemptNumber: retryAttemptNumber,
+                        finalBodyStr: retryBodyStr,
+                        upstreamSpan: currentUpstreamSpan,
+                        logAttempt: retryLogAttempt,
+                        logProxyBody,
+                        logFinalRequest,
+                    })
+                    : {
+                        response: await handleAnthropicSuccessfulNonStreamRetryResponse({
+                            account,
+                            accountState,
+                            retryResp,
+                            tracer,
+                            requestStartTime,
+                            fetchStartMs: retryFetchStartMs,
+                            attemptNumber: retryAttemptNumber,
+                            finalBodyStr: retryBodyStr,
+                            upstreamSpan: currentUpstreamSpan,
+                            logAttempt: retryLogAttempt,
+                            logProxyBody,
+                            logFinalRequest,
+                        }),
+                    };
+                if ("retryNextAccount" in successResult) {
+                    const failure = successResult.failure;
+                    return {
+                        continueLoop: true,
+                        lastError: failure?.message ?? currentLastError,
+                        authFailureMessage: currentAuthFailureMessage,
+                        sawRateLimit: currentSawRateLimit || Boolean(failure?.rateLimit),
+                        sawTransientFailure: currentSawTransientFailure ||
+                            Boolean(failure && !failure.rateLimit),
+                        sawNetworkError: currentSawNetworkError,
+                        upstreamSpan: undefined,
+                    };
+                }
                 return {
-                    response: successResponse,
+                    response: successResult.response,
                     continueLoop: false,
                     lastError: currentLastError,
                     authFailureMessage: currentAuthFailureMessage,

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;

package/dist/tools/toolDiscovery.js

@@ -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).
@@ -23,6 +30,14 @@ import { z } from "zod";
 import { tool as createAISDKTool } from "../utils/tool.js";
 import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
 import { logger } from "../utils/logger.js";
+/**
+ * Symbol key under which the hot record carries its deferred-tool resolver.
+ * Symbol-keyed properties are skipped by Object.keys/entries, for-in, and
+ * JSON.stringify, so no declaration builder (or the AI SDK) ever sees the
+ * resolver as a tool. `Symbol.for` (global registry) keeps the key stable
+ * even if this module is loaded twice (ESM/CJS dual load of the bundle).
+ */
+const DEFERRED_TOOL_RESOLVER_KEY = Symbol.for("neurolink.deferredToolResolver");
 /**
  * Above this many tools, a WARN suggests enabling `tools.discovery` when it
  * is off. Chosen from the measured degradation range (30-50 tools).
@@ -162,6 +177,35 @@ export function partitionToolsForDiscovery(tools, args) {
         };
     });
     hot["search_tools"] = buildSearchTool(entries, tools, hot, args.onHydrate);
+    // Dispatch-miss escape hatch for the native agent loops: hydrate a
+    // deferred tool the model called directly by its cataloged name (the
+    // catalog advertises exact names, so this is legitimate model behavior,
+    // not hallucination). Hydration mutates the hot record and persists the
+    // session pin — identical side effects to a search_tools hit.
+    const resolver = (name) => {
+        if (name in hot) {
+            return hot[name];
+        }
+        if (!deferredSet.has(name)) {
+            return undefined;
+        }
+        const toolDef = tools[name];
+        if (!toolDef) {
+            return undefined;
+        }
+        hot[name] = toolDef;
+        args.onHydrate([name]);
+        logger.debug("[ToolDiscovery] Auto-hydrated deferred tool on direct call", {
+            name,
+        });
+        return toolDef;
+    };
+    Object.defineProperty(hot, DEFERRED_TOOL_RESOLVER_KEY, {
+        value: resolver,
+        enumerable: false,
+        writable: false,
+        configurable: true,
+    });
     logger.debug("[ToolDiscovery] Deferred external tools behind search_tools", {
         hotCount: Object.keys(hot).length - 1,
         deferredCount: deferredNames.length,
@@ -169,6 +213,34 @@ export function partitionToolsForDiscovery(tools, args) {
     });
     return hot;
 }
+/**
+ * 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 function resolveDeferredTool(record, name) {
+    if (!record) {
+        return undefined;
+    }
+    const resolver = record[DEFERRED_TOOL_RESOLVER_KEY];
+    return typeof resolver === "function"
+        ? resolver(name)
+        : 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 function resolveLiveTool(record, name) {
+    if (!record) {
+        return undefined;
+    }
+    return record[name] ?? resolveDeferredTool(record, name);
+}
 function buildSearchTool(entries, allTools, hotRecord, onHydrate) {
     const catalog = renderCatalog(entries);
     const searchTool = createAISDKTool({
@@ -221,7 +293,7 @@ function buildSearchTool(entries, allTools, hotRecord, onHydrate) {
             return {
                 found: loaded.length,
                 tools: loaded,
-                message: "These tools are now loaded for this session. Call them directly by name with arguments matching their inputSchema. If a call reports the tool as unavailable, it will be available from the next message onward.",
+                message: "These tools are now loaded for this session. Call them directly by name with arguments matching their inputSchema.",
             };
         },
     });