@juspay/neurolink 13.5.1 → 13.6.1

package/dist/core/baseProvider.d.ts

@@ -152,7 +152,9 @@ export declare abstract class BaseProvider implements AIProvider {
     private sortToolRecord;
     /**
      * On-demand discovery (`tools.discovery: true`): defer external MCP tool
-     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
+     * schemas — or, with `tools.discoveryScope: "all"`, every non-built-in
+     * tool — behind one `search_tools` meta-tool, except names matching
+     * `tools.discoveryAlwaysVisible`. Built-in tools, per-call
      * tools, explicitly whitelisted tools, and session-pinned (previously
      * discovered) tools always stay hot. No-op when discovery is off — with a
      * one-time WARN when the catalog is large enough that selection accuracy

package/dist/core/baseProvider.js

@@ -1246,7 +1246,9 @@ export class BaseProvider {
     }
     /**
      * On-demand discovery (`tools.discovery: true`): defer external MCP tool
-     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
+     * schemas — or, with `tools.discoveryScope: "all"`, every non-built-in
+     * tool — behind one `search_tools` meta-tool, except names matching
+     * `tools.discoveryAlwaysVisible`. Built-in tools, per-call
      * tools, explicitly whitelisted tools, and session-pinned (previously
      * discovered) tools always stay hot. No-op when discovery is off — with a
      * one-time WARN when the catalog is large enough that selection accuracy
@@ -1273,8 +1275,13 @@ export class BaseProvider {
             }
             return tools;
         }
-        const externalTools = this.neurolink?.getExternalMCPTools() ?? [];
-        if (externalTools.length === 0) {
+        // "external" defers only attached MCP servers' tools; "all" defers every
+        // tool in the record except the built-ins.
+        const builtinNames = new Set(Object.keys(this.directTools ?? {}));
+        const candidateNames = policy.discoveryScope === "all"
+            ? Object.keys(tools).filter((name) => !builtinNames.has(name))
+            : (this.neurolink?.getExternalMCPTools() ?? []).map((t) => t.name);
+        if (candidateNames.length === 0) {
             return tools;
         }
         // Session pinning requires a caller-provided sessionId. Without one there
@@ -1305,12 +1312,15 @@ export class BaseProvider {
             explicitPatterns.push(toolChoice.toolName);
         }
         const explicitMatcher = explicitPatterns.length > 0 ? toolNameMatcher(explicitPatterns) : null;
-        const deferrableNames = externalTools
-            .map((t) => t.name)
-            .filter((name) => name in tools &&
+        const alwaysVisiblePatterns = policy.discoveryAlwaysVisible ?? [];
+        const alwaysVisibleMatcher = alwaysVisiblePatterns.length > 0
+            ? toolNameMatcher(alwaysVisiblePatterns)
+            : null;
+        const deferrableNames = candidateNames.filter((name) => name in tools &&
             !perCallNames.has(name) &&
-            !(explicitMatcher ? explicitMatcher(name) : false));
-        return partitionToolsForDiscovery(tools, {
+            !(explicitMatcher ? explicitMatcher(name) : false) &&
+            !(alwaysVisibleMatcher ? alwaysVisibleMatcher(name) : false));
+        const partitioned = partitionToolsForDiscovery(tools, {
             deferrableNames,
             pinnedNames,
             onHydrate: (names) => {
@@ -1319,6 +1329,16 @@ export class BaseProvider {
                 }
             },
         });
+        // The meta-tool is built after the event wrappers ran, so without this
+        // a search_tools call never reaches tool:start / tool:end listeners.
+        const metaTool = partitioned["search_tools"];
+        if (isDiscoveryMetaTool(metaTool)) {
+            partitioned["search_tools"] =
+                this.toolsManager.wrapExternalToolsWithEvents({
+                    search_tools: metaTool,
+                })["search_tools"];
+        }
+        return partitioned;
     }
     static warnedLargeCatalog = false;
     warnLargeCatalogOnce(toolCount) {

package/dist/core/modules/ToolsManager.js

@@ -6,6 +6,7 @@ import { logger } from "../../utils/logger.js";
 import { TOOL_EVENTS_WRAPPED } from "../../types/index.js";
 import { getKeyCount } from "../../utils/transformationUtils.js";
 import { extractIsErrorText } from "../../utils/toolResultStatus.js";
+import { createToolExecutionId } from "../../utils/toolExecutionId.js";
 import { convertJsonSchemaToZod } from "../../utils/schemaConversion.js";
 import { generateToolOutputPreview, DEFAULT_MAX_PREVIEW_BYTES, RETRIEVE_CONTEXT_TOOL_NAME, } from "../../context/toolOutputLimits.js";
 /**
@@ -512,6 +513,12 @@ export class ToolsManager {
             const idField = typeof toolCallId === "string" && toolCallId.length > 0
                 ? { toolCallId }
                 : {};
+            // Same per-invocation id executeTool gives registered tools, so a
+            // listener can pair this start with its end.
+            const eventIds = {
+                ...idField,
+                executionId: createToolExecutionId(toolName),
+            };
             return withSpan({
                 name: toolSpanName(toolName),
                 tracer: tracers.mcp,
@@ -521,7 +528,7 @@ export class ToolsManager {
                 const startTime = Date.now();
                 this.emitToolEvent("tool:start", toolName, {
                     input: params,
-                    ...idField,
+                    ...eventIds,
                 });
                 let result;
                 try {
@@ -533,7 +540,7 @@ export class ToolsManager {
                         error: errorMsg,
                         success: false,
                         responseTime: Date.now() - startTime,
-                        ...idField,
+                        ...eventIds,
                     });
                     throw error;
                 }
@@ -549,7 +556,7 @@ export class ToolsManager {
                     success: isErrorText === undefined,
                     ...(isErrorText !== undefined ? { error: isErrorText } : {}),
                     responseTime: Date.now() - startTime,
-                    ...idField,
+                    ...eventIds,
                 });
                 return result;
             });

package/dist/core/nativeGenerateLoop.d.ts

@@ -84,6 +84,8 @@ export declare const toPrepareStepRecord: (step: {
 export declare const hasNativeDoGenerate: (value: unknown) => value is {
     doGenerate: (options: Record<string, unknown>) => Promise<Record<string, unknown>>;
 };
+/** A tool's inputSchema with its lazy (function) form, if any, resolved. */
+export declare const resolveToolInputSchema: (schema: Tool["inputSchema"]) => Exclude<Tool["inputSchema"], (...args: never[]) => unknown>;
 /**
  * Spell a JSON Schema into the conversation's system turn.
  *

package/dist/core/nativeGenerateLoop.js

@@ -17,6 +17,7 @@ import { observeGeneration } from "../telemetry/observation.js";
 import { StepSpans, withGeneration } from "../telemetry/withSpan.js";
 import { logger } from "../utils/logger.js";
 import { guardToolExecutor } from "./toolExecutionGuards.js";
+import { resolveLiveTool } from "../tools/toolDiscovery.js";
 const DEFAULT_TOOL_CHOICE_STEPS = 1;
 /**
  * A choice that compels a tool call: `"required"` or a named tool, in either
@@ -74,9 +75,9 @@ const warnUndeclaredForcedTool = (toolName, step, source) => {
 };
 /**
  * The names this request actually carries, in the record shape
- * `declaredTools` takes. The loop sends `args.tools`, built once by the
- * caller; `args.toolsRecord` can hold more (discovery hydrates into it, and
- * this loop never re-declares), so only `tools` answers "is it offered".
+ * `declaredTools` takes. `args.toolsRecord` can hold more than is declared
+ * (discovery hydrates into it), so only the sent declarations answer "is it
+ * offered".
  * Null prototype: a tool may be named `__proto__` or `constructor`.
  */
 const declaredToolRecord = (tools) => {
@@ -336,6 +337,8 @@ const parseToolInput = (raw) => {
         return { input: {}, error: "arguments were not valid JSON" };
     }
 };
+/** A tool's inputSchema with its lazy (function) form, if any, resolved. */
+export const resolveToolInputSchema = (schema) => typeof schema === "function" ? resolveToolInputSchema(schema()) : schema;
 /**
  * Validate parsed input against the tool's own schema when it exposes one.
  *
@@ -346,8 +349,13 @@ const parseToolInput = (raw) => {
  * validator this loop has no business carrying.
  */
 const validateToolInput = (tool, input) => {
-    const schema = tool?.inputSchema;
-    if (typeof schema?.safeParse !== "function") {
+    const schema = tool?.inputSchema
+        ? resolveToolInputSchema(tool.inputSchema)
+        : undefined;
+    if (!schema ||
+        typeof schema !== "object" ||
+        !("safeParse" in schema) ||
+        typeof schema.safeParse !== "function") {
         return undefined;
     }
     const result = schema.safeParse(input);
@@ -478,11 +486,28 @@ async function runGenerateSteps(args, toolExecutionSummaries, stepSpans) {
     // answer is that result — not a thrown turn.
     let preReask;
     const hasTools = Boolean(args.tools && args.tools.length > 0);
+    // The declarations actually sent. Starts as the caller's list and grows when
+    // a tool joins toolsRecord mid-turn (discovery loads tools into it).
+    const liveTools = args.tools ? [...args.tools] : undefined;
+    const declaredNames = declaredToolRecord(args.tools);
     // Completed-step records for `prepareStep`; one per step that returned.
     const stepRecords = [];
     for (let step = 0; step < args.maxSteps; step++) {
         steps = step + 1;
         stepSpans.begin(steps);
+        if (liveTools && args.declareTool) {
+            const loaded = [];
+            for (const name of Object.keys(args.toolsRecord)) {
+                if (!declaredNames[name]) {
+                    liveTools.push(args.declareTool(name, args.toolsRecord[name]));
+                    declaredNames[name] = true;
+                    loaded.push(name);
+                }
+            }
+            if (loaded.length > 0) {
+                logger.debug(`[nativeGenerateLoop] ${loaded.length} tool(s) hydrated mid-turn via discovery: ${loaded.join(", ")}`);
+            }
+        }
         // The forced-choice window and the caller's hook are resolved BEFORE the
         // re-ask override below: the re-ask has to win, since its whole point is
         // a request with tools disabled.
@@ -498,7 +523,7 @@ async function runGenerateSteps(args, toolExecutionSummaries, stepSpans) {
                 steps: stepRecords,
                 maxSteps: args.maxSteps,
                 model: args.modelId,
-                declaredTools: declaredToolRecord(args.tools),
+                declaredTools: declaredToolRecord(liveTools),
                 ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
             })
             : undefined;
@@ -519,7 +544,7 @@ async function runGenerateSteps(args, toolExecutionSummaries, stepSpans) {
         }
         const runThisStep = () => generateObservedStep(args, {
             prompt: args.conversation,
-            ...(args.tools && args.tools.length > 0 ? { tools: args.tools } : {}),
+            ...(liveTools && liveTools.length > 0 ? { tools: liveTools } : {}),
             // The v3 call option is an OBJECT — `{ type: "none" }`. Passing the
             // bare string "none" type-checks against `unknown` and is then
             // dropped by every converter that switches on `choice.type`, so the
@@ -688,7 +713,9 @@ async function runGenerateSteps(args, toolExecutionSummaries, stepSpans) {
             const startTime = new Date();
             const parsed = parseToolInput(call.input);
             const input = parsed.input;
-            const tool = args.toolsRecord[name];
+            // resolveLiveTool also loads a deferred tool the model called by its
+            // catalog name without searching first.
+            const tool = resolveLiveTool(args.toolsRecord, name);
             let output;
             let failure;
             const rejection = parsed.error ??

package/dist/neurolink.js

@@ -76,6 +76,7 @@ import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { endSpanWhenDropped, withSpan } from "./telemetry/withSpan.js";
 import { getActiveTraceContext } from "./telemetry/traceContext.js";
 import { calculateCost } from "./utils/pricing.js";
+import { createToolExecutionId } from "./utils/toolExecutionId.js";
 import { acquireTelemetry, ensureTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, isOpenTelemetryInitialized, releaseTelemetry, setLangfuseContext, traceMetadataFromContext, } from "./services/server/ai/observability/instrumentation.js";
 import { clearChecklistState, createChecklistTools, getChecklistState, resolveChecklistSessionId, } from "./agent/taskChecklist.js";
 import { cancelDelegates as cancelBackgroundDelegates, collectDelegates as collectBackgroundDelegates, configureDelegation, createDelegationTools, spawnDelegate as spawnBackgroundDelegate, } from "./agent/backgroundDelegation.js";
@@ -10599,7 +10600,7 @@ Current user's request: ${currentInput}`;
      * @returns executionId for tracking this specific execution
      */
     emitToolStart(toolName, input, startTime = Date.now()) {
-        const executionId = `${toolName}-${startTime}-${Math.random().toString(36).substr(2, 9)}`;
+        const executionId = createToolExecutionId(toolName, startTime);
         // Create execution context for tracking
         const context = {
             executionId,

package/dist/providers/openaiChatCompletionsBase.js

@@ -36,7 +36,7 @@ import { NoOutputGeneratedError } from "../utils/generationErrors.js";
 import { buildNoOutputSentinel, stampNoOutputSpan, } from "../utils/noOutputSentinel.js";
 import { composeAbortSignalsScoped, createTimeoutController, mergeAbortSignals, TimeoutError, } from "../utils/timeout.js";
 import { resolveRequestKind } from "../core/resolveRequestKind.js";
-import { appendJsonSchemaInstruction, hasNativeDoGenerate, resolveStepToolChoice, runNativeGenerateLoop, toPrepareStepRecord, } from "../core/nativeGenerateLoop.js";
+import { appendJsonSchemaInstruction, hasNativeDoGenerate, resolveToolInputSchema, resolveStepToolChoice, runNativeGenerateLoop, toPrepareStepRecord, } from "../core/nativeGenerateLoop.js";
 import { resolveToolExecutionRecords, toolCallsFromSummaries, } from "../core/toolExecutionRecorder.js";
 import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
 import { coerceJsonToSchema, recoverScalarRoot, schemaAccepts, } from "../utils/json/coerce.js";
@@ -925,18 +925,19 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             ? options.tools || (await this.getAllTools())
             : {};
         // v3 tool shape — the same one doGenerate already converts internally.
+        // Also handed to the loop, which declares tools discovery loads mid-turn.
+        const declareTool = (name, tool) => {
+            return {
+                type: "function",
+                name,
+                description: tool.description ?? "",
+                inputSchema: tool.inputSchema
+                    ? convertZodToJsonSchema(resolveToolInputSchema(tool.inputSchema))
+                    : { type: "object", properties: {} },
+            };
+        };
         const v3Tools = shouldUseTools
-            ? Object.entries(toolsRecord).map(([name, t]) => {
-                const tool = t;
-                return {
-                    type: "function",
-                    name,
-                    description: tool.description ?? "",
-                    inputSchema: (tool.inputSchema
-                        ? convertZodToJsonSchema(tool.inputSchema)
-                        : { type: "object", properties: {} }),
-                };
-            })
+            ? Object.entries(toolsRecord).map(([name, t]) => declareTool(name, t))
             : undefined;
         const hasTools = !!v3Tools && v3Tools.length > 0;
         // Structured output rides response_format, which is what Output.object did
@@ -964,6 +965,14 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         // model has already given. Dropping them is what makes `response_format`
         // legal again on a vendor that refuses the two together.
         withTools = true) => {
+            // What this pass sends: the initial declarations plus any the loop adds
+            // for tools discovery loads mid-turn, so the guard counts them too.
+            const passTools = withTools && v3Tools ? [...v3Tools] : undefined;
+            const declarePassTool = (name, tool) => {
+                const declaration = declareTool(name, tool);
+                passTools?.push(declaration);
+                return declaration;
+            };
             return runNativeGenerateLoop({
                 doGenerate,
                 provider: this.providerName,
@@ -983,12 +992,14 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                     // the estimate past the reclaim threshold and drop older tool
                     // exchanges out of a reformat request that would have fit.
                     getFixedOverheadTokens: () => estimateTokens(serializeForEstimate({
-                        ...(withTools && v3Tools ? { tools: v3Tools } : {}),
+                        ...(passTools ? { tools: passTools } : {}),
                         responseFormat: format,
                     }), this.providerName),
                 }),
                 conversation: conv,
-                ...(withTools && v3Tools ? { tools: v3Tools } : {}),
+                ...(passTools
+                    ? { tools: [...passTools], declareTool: declarePassTool }
+                    : {}),
                 toolsRecord,
                 ...(withTools && hasTools && options.toolChoice
                     ? { toolChoice: resolveToolChoice(options, toolsRecord, true) }

package/dist/tools/toolDiscovery.js

@@ -244,7 +244,8 @@ export function resolveLiveTool(record, name) {
 function buildSearchTool(entries, allTools, hotRecord, onHydrate) {
     const catalog = renderCatalog(entries);
     const searchTool = createAISDKTool({
-        description: `Search and load additional tools on demand. ${entries.length} more tools are available but not yet loaded:\n` +
+        description: `Search and load additional tools on demand. ${entries.length} more tools are available but not yet loaded. ` +
+            `Before telling the user you cannot do something, check this catalog: if a listed tool fits, call it directly by its exact name, or call search_tools with a short description of the task.\n` +
             `${catalog}\n` +
             `Call this with a task description or an exact tool name; matching tools are loaded and become directly callable.`,
         inputSchema: z.object({

package/dist/tools/toolPolicy.js

@@ -186,8 +186,28 @@ export function resolveToolPolicy(input) {
     }
     // --- discovery -----------------------------------------------------------
     const discovery = instanceConfig?.discovery === true;
+    let discoveryScope = "external";
+    let discoveryAlwaysVisible = [];
     if (discovery) {
         sources.push("tools.discovery");
-    }
-    return { enabled, include, includeBound, exclude, discovery, sources };
+        const configScope = instanceConfig?.discoveryScope;
+        if (configScope === "all") {
+            discoveryScope = "all";
+        }
+        else if (configScope !== undefined && configScope !== "external") {
+            warnOnce("shape:tools.discoveryScope", `[ToolPolicy] Ignoring unknown tools.discoveryScope; using "external"`, { received: configScope });
+        }
+        discoveryAlwaysVisible =
+            normalizeConfigList(instanceConfig?.discoveryAlwaysVisible, "tools.discoveryAlwaysVisible", false) ?? [];
+    }
+    return {
+        enabled,
+        include,
+        includeBound,
+        exclude,
+        discovery,
+        discoveryScope,
+        discoveryAlwaysVisible,
+        sources,
+    };
 }

package/dist/types/config.d.ts

@@ -443,9 +443,40 @@ export type ToolConfig = {
      * full. Note: the instance-level `include` list deliberately does NOT
      * force tools hot — it scopes the catalog, and discovery defers within
      * that scope (a scoped-but-large catalog is exactly where deferral pays).
+     *
+     * What the model and your listeners see once discovery is on: the
+     * `search_tools` description ends with an instruction to check the catalog
+     * before saying a task cannot be done; each `search_tools` call emits
+     * `tool:start` and `tool:end` (paired by `executionId`) and is traced and
+     * observed like any other tool call; and the events of every wrapped
+     * external tool carry an `executionId`.
      * Default: false.
      */
     discovery?: boolean;
+    /**
+     * Which tools `discovery` may defer.
+     * - `"external"`: tools of servers attached with `addExternalMCPServer`.
+     * - `"all"`: every tool in the request's record except the built-in tools,
+     *   so tools registered with `registerTool`/`registerTools` and in-process
+     *   MCP tools are deferred as well. That includes the tools NeuroLink
+     *   registers for its own features through `registerTool()`, such as
+     *   `retrieve_context` (memory retrieval), the skills tools, and the tools
+     *   of `registerTaskTools`, `registerDelegationTools`,
+     *   `registerBackgroundCommandTools` and `registerGitTools`. Name them in
+     *   `discoveryAlwaysVisible` to keep them in full.
+     * Per-call tools, per-call whitelists, forced `toolChoice` tools and
+     * already-discovered tools stay hot in both scopes. Ignored unless
+     * `discovery` is true.
+     * Default: "external".
+     */
+    discoveryScope?: "external" | "all";
+    /**
+     * Tool-name patterns (exact names or `*` globs) that `discovery` never
+     * defers, in either scope. E.g. `["utility-server_*"]` keeps every tool
+     * whose name starts with `utility-server_` in full on every request.
+     * Ignored unless `discovery` is true.
+     */
+    discoveryAlwaysVisible?: string[];
     /** Whether built-in tools should be disabled (equivalent to excluding all direct tools) */
     disableBuiltinTools?: boolean;
     /** Whether custom tools are allowed */

package/dist/types/generate.d.ts

@@ -1839,7 +1839,15 @@ export type NativeGenerateLoopArgs = {
     /** Tool declarations in the v3 shape doGenerate already knows how to convert. */
     tools?: Array<Record<string, unknown>>;
     /** Registered tools, used to execute a call the model asks for. */
-    toolsRecord: Record<string, unknown>;
+    toolsRecord: Record<string, Tool>;
+    /**
+     * Builds the v3 declaration for one tool. When set, every step declares any
+     * tool that joined `toolsRecord` mid-turn (discovery's search_tools loads
+     * tools into it), so the model can call what it just loaded. Only the
+     * OpenAI-compatible `generate()` path supplies it; the other providers that
+     * run this loop do not declare a tool `search_tools` loaded mid-turn.
+     */
+    declareTool?: (name: string, tool: Tool) => Record<string, unknown>;
     /** The turn's resolved tool choice, applied per step via `resolveStepToolChoice`. */
     toolChoice?: unknown;
     /** Leading steps a forced `toolChoice` stays in force (default 1). */

package/dist/types/toolResolution.d.ts

@@ -35,8 +35,12 @@ export type ResolvedToolPolicy = {
     includeBound?: string[];
     /** Denylist of tool-name patterns (exact names or `*` globs), applied after include. */
     exclude: string[];
-    /** Defer external MCP tool schemas behind the search_tools meta-tool. */
+    /** Defer tool schemas behind the search_tools meta-tool. */
     discovery: boolean;
+    /** Which tools discovery may defer. Absent means "external". */
+    discoveryScope?: "external" | "all";
+    /** Tool-name patterns (exact names or `*` globs) discovery never defers. Absent means none. */
+    discoveryAlwaysVisible?: string[];
     /** Which option/config sources contributed to this policy (telemetry/debugging). */
     sources: string[];
 };

package/dist/utils/toolExecutionId.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @description Builds the id that pairs one tool call's `tool:start` and `tool:end` events.
+ * @param toolName {string} - Name of the tool being run.
+ * @param startTime {number} - When the call started, in epoch milliseconds.
+ * @returns {string} `<toolName>-<startTime>-<nine random base-36 characters>`.
+ */
+export declare function createToolExecutionId(toolName: string, startTime?: number): string;

package/dist/utils/toolExecutionId.js

@@ -0,0 +1,9 @@
+/**
+ * @description Builds the id that pairs one tool call's `tool:start` and `tool:end` events.
+ * @param toolName {string} - Name of the tool being run.
+ * @param startTime {number} - When the call started, in epoch milliseconds.
+ * @returns {string} `<toolName>-<startTime>-<nine random base-36 characters>`.
+ */
+export function createToolExecutionId(toolName, startTime = Date.now()) {
+    return `${toolName}-${startTime}-${Math.random().toString(36).slice(2, 11)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "13.5.1",
+  "version": "13.6.1",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {