@juspay/neurolink 9.90.0 → 9.91.1

package/dist/lib/tools/toolDiscovery.d.ts

@@ -0,0 +1,48 @@
+/**
+ * On-demand tool discovery (`tools.discovery: true`).
+ *
+ * Instead of sending every external MCP tool's full schema on every request,
+ * the model receives the hot set (built-in tools, per-call tools, explicitly
+ * 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
+ *  - into the session pin set (all providers include them in full on every
+ *    subsequent call of the session).
+ *
+ * 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).
+ * The catalog construction (byte-stable, name-sorted, char-budgeted with a
+ * degradation ladder) mirrors the proven skills-index pattern in
+ * src/lib/skills/skillTools.ts.
+ */
+import type { Tool } from "../types/index.js";
+/**
+ * Above this many tools, a WARN suggests enabling `tools.discovery` when it
+ * is off. Chosen from the measured degradation range (30-50 tools).
+ */
+export declare const LARGE_CATALOG_WARN_THRESHOLD = 40;
+/** True when the value is a search_tools meta-tool generated by this module. */
+export declare function isDiscoveryMetaTool(tool: unknown): boolean;
+/**
+ * Partition a (post-gate) tools record for discovery: deferrable tools that
+ * are not pinned are removed from the record and replaced by one
+ * `search_tools` meta-tool. Returns the hot record; when nothing is
+ * deferrable the input record is returned unchanged.
+ *
+ * The returned record is mutated by search_tools on hydration (call-scoped —
+ * BaseProvider builds a fresh merged record per call), which is what makes
+ * discovered tools callable on subsequent steps of the same agent loop on
+ * providers that re-read the record between steps.
+ */
+export declare function partitionToolsForDiscovery(tools: Record<string, Tool>, args: {
+    /** External-tool names present in `tools` that are allowed to defer. */
+    deferrableNames: string[];
+    /** Session-pinned names (previously discovered) — never deferred. */
+    pinnedNames: ReadonlySet<string>;
+    /** Called with newly discovered names — persists session pins. */
+    onHydrate: (names: string[]) => void;
+}): Record<string, Tool>;

package/dist/lib/tools/toolDiscovery.js

@@ -0,0 +1,231 @@
+/**
+ * On-demand tool discovery (`tools.discovery: true`).
+ *
+ * Instead of sending every external MCP tool's full schema on every request,
+ * the model receives the hot set (built-in tools, per-call tools, explicitly
+ * 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
+ *  - into the session pin set (all providers include them in full on every
+ *    subsequent call of the session).
+ *
+ * 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).
+ * The catalog construction (byte-stable, name-sorted, char-budgeted with a
+ * degradation ladder) mirrors the proven skills-index pattern in
+ * src/lib/skills/skillTools.ts.
+ */
+import { z } from "zod";
+import { tool as createAISDKTool } from "../utils/tool.js";
+import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Above this many tools, a WARN suggests enabling `tools.discovery` when it
+ * is off. Chosen from the measured degradation range (30-50 tools).
+ */
+export const LARGE_CATALOG_WARN_THRESHOLD = 40;
+/** Char budget for the catalog embedded in the search_tools description. */
+const CATALOG_CHAR_BUDGET = 15_000;
+/** Max tools loaded per search_tools call. */
+const MAX_SEARCH_RESULTS = 5;
+const SUMMARY_MAX_CHARS = 100;
+/**
+ * Marker property stamped on the generated search_tools meta-tool so
+ * re-entrant resolution passes (e.g. the stream → generate fallback, whose
+ * options.tools already contain a partitioned record) can distinguish OUR
+ * stale meta-tool from a real user tool that happens to share the name.
+ */
+const DISCOVERY_META_TOOL_MARKER = "__nlDiscoveryMetaTool";
+/** True when the value is a search_tools meta-tool generated by this module. */
+export function isDiscoveryMetaTool(tool) {
+    return (!!tool &&
+        typeof tool === "object" &&
+        tool[DISCOVERY_META_TOOL_MARKER] === true);
+}
+let warnedSearchToolsCollision = false;
+function warnSearchToolsCollisionOnce() {
+    if (warnedSearchToolsCollision) {
+        return;
+    }
+    warnedSearchToolsCollision = true;
+    logger.warn("[ToolDiscovery] A registered tool is already named 'search_tools' — on-demand discovery is skipped to avoid shadowing it. Rename that tool to use tools.discovery.");
+}
+/** First sentence of a description, capped for the catalog line. */
+function summarize(description) {
+    const firstSentence = description.split(/(?<=[.!?])\s/)[0] ?? description;
+    const trimmed = firstSentence.trim().replace(/\s+/g, " ");
+    return trimmed.length > SUMMARY_MAX_CHARS
+        ? trimmed.slice(0, SUMMARY_MAX_CHARS - 1) + "…"
+        : trimmed;
+}
+/**
+ * Render the deferred-tool catalog, byte-stable (name-sorted input) and
+ * char-budgeted with a degradation ladder: full one-liners → name-only lines
+ * → truncated with a count note. Entries are never silently dropped without
+ * the note, so the model always knows the catalog's true size.
+ */
+function renderCatalog(entries) {
+    const full = entries.map((e) => `- ${e.name}: ${e.summary}`);
+    let text = full.join("\n");
+    if (text.length <= CATALOG_CHAR_BUDGET) {
+        return text;
+    }
+    const nameOnly = entries.map((e) => `- ${e.name}`);
+    text = nameOnly.join("\n");
+    if (text.length <= CATALOG_CHAR_BUDGET) {
+        return text;
+    }
+    const kept = [];
+    let used = 0;
+    for (const line of nameOnly) {
+        if (used + line.length + 1 > CATALOG_CHAR_BUDGET - 80) {
+            break;
+        }
+        kept.push(line);
+        used += line.length + 1;
+    }
+    const remaining = entries.length - kept.length;
+    return `${kept.join("\n")}\n… and ${remaining} more (search by task description to find them)`;
+}
+/** Lexical relevance score of one catalog entry for a query. Zero = no match. */
+function scoreEntry(queryLower, queryTokens, entry, fullDescription) {
+    const nameLower = entry.name.toLowerCase();
+    if (nameLower === queryLower) {
+        return 100;
+    }
+    let score = 0;
+    if (queryLower.includes(nameLower) || nameLower.includes(queryLower)) {
+        score += 20;
+    }
+    const haystack = `${nameLower} ${fullDescription.toLowerCase()}`;
+    for (const token of queryTokens) {
+        if (token.length < 3) {
+            continue;
+        }
+        if (nameLower.includes(token)) {
+            score += 8;
+        }
+        else if (haystack.includes(token)) {
+            score += 2;
+        }
+    }
+    if (entry.serverId && queryLower.includes(entry.serverId.toLowerCase())) {
+        score += 3;
+    }
+    return score;
+}
+/**
+ * Partition a (post-gate) tools record for discovery: deferrable tools that
+ * are not pinned are removed from the record and replaced by one
+ * `search_tools` meta-tool. Returns the hot record; when nothing is
+ * deferrable the input record is returned unchanged.
+ *
+ * The returned record is mutated by search_tools on hydration (call-scoped —
+ * BaseProvider builds a fresh merged record per call), which is what makes
+ * discovered tools callable on subsequent steps of the same agent loop on
+ * providers that re-read the record between steps.
+ */
+export function partitionToolsForDiscovery(tools, args) {
+    const deferredNames = args.deferrableNames
+        .filter((n) => n in tools && !args.pinnedNames.has(n))
+        .sort();
+    if (deferredNames.length === 0) {
+        return tools;
+    }
+    // Never shadow a real tool that happens to be named "search_tools" (a
+    // custom tool or an external MCP tool could claim the name). Discovery is
+    // skipped for the request rather than silently replacing the caller's tool.
+    if ("search_tools" in tools) {
+        warnSearchToolsCollisionOnce();
+        return tools;
+    }
+    const deferredSet = new Set(deferredNames);
+    // Null prototype: a tool named "__proto__" must become an own entry, not a
+    // prototype mutation (mirrors BaseProvider.sortToolRecord) — this record is
+    // also mutated later by search_tools hydration.
+    const hot = Object.create(null);
+    for (const [name, toolDef] of Object.entries(tools)) {
+        if (!deferredSet.has(name)) {
+            hot[name] = toolDef;
+        }
+    }
+    const entries = deferredNames.map((name) => {
+        const t = tools[name];
+        return {
+            name,
+            summary: summarize(t.description ?? ""),
+            serverId: typeof t.serverId === "string" ? t.serverId : undefined,
+        };
+    });
+    hot["search_tools"] = buildSearchTool(entries, tools, hot, args.onHydrate);
+    logger.debug("[ToolDiscovery] Deferred external tools behind search_tools", {
+        hotCount: Object.keys(hot).length - 1,
+        deferredCount: deferredNames.length,
+        pinnedCount: args.pinnedNames.size,
+    });
+    return hot;
+}
+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` +
+            `${catalog}\n` +
+            `Call this with a task description or an exact tool name; matching tools are loaded and become directly callable.`,
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe("What you need to do, or an exact tool name to load"),
+        }),
+        execute: async ({ query }) => {
+            const queryLower = query.toLowerCase().trim();
+            const queryTokens = queryLower.split(/[^a-z0-9_.-]+/).filter(Boolean);
+            const scored = entries
+                .map((entry) => {
+                const full = allTools[entry.name];
+                return {
+                    entry,
+                    score: scoreEntry(queryLower, queryTokens, entry, full?.description ?? ""),
+                };
+            })
+                .filter((s) => s.score > 0)
+                .sort((a, b) => b.score - a.score || (a.entry.name < b.entry.name ? -1 : 1))
+                .slice(0, MAX_SEARCH_RESULTS);
+            if (scored.length === 0) {
+                return {
+                    found: 0,
+                    message: "No tools matched. Try different words, or use one of the exact names from the catalog in this tool's description.",
+                };
+            }
+            const loaded = scored.map(({ entry }) => {
+                const toolDef = allTools[entry.name];
+                // Live hydration: callable on subsequent loop steps where the
+                // provider re-reads the record.
+                hotRecord[entry.name] = toolDef;
+                const def = toolDef;
+                return {
+                    name: entry.name,
+                    description: def.description ?? "",
+                    inputSchema: convertZodToJsonSchema(def.inputSchema),
+                };
+            });
+            // Session pinning: included in full on every subsequent call.
+            onHydrate(loaded.map((t) => t.name));
+            logger.debug("[ToolDiscovery] search_tools hydrated tools", {
+                query,
+                loaded: loaded.map((t) => t.name),
+            });
+            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.",
+            };
+        },
+    });
+    searchTool[DISCOVERY_META_TOOL_MARKER] = true;
+    return searchTool;
+}
+//# sourceMappingURL=toolDiscovery.js.map

package/dist/lib/tools/toolGate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tool gate — applies a ResolvedToolPolicy to a tools record. This is the
+ * ONE place where include/exclude filtering of the native tool set happens;
+ * every generate/stream path reaches it via BaseProvider.
+ *
+ * Generic over the tool value type so it works for AI-SDK Tool records,
+ * ToolInfo listings, and provider wire formats alike.
+ */
+import type { ResolvedToolPolicy } from "../types/index.js";
+/**
+ * Filter a tools record according to the resolved policy.
+ * Order: enabled kill-switch → include allowlist → exclude denylist.
+ * Preserves the input record's key order for surviving tools (callers rely
+ * on deterministic ordering for provider prompt-cache stability).
+ */
+export declare function applyToolGate<T>(tools: Record<string, T>, policy: ResolvedToolPolicy): Record<string, T>;

package/dist/lib/tools/toolGate.js

@@ -0,0 +1,51 @@
+/**
+ * Tool gate — applies a ResolvedToolPolicy to a tools record. This is the
+ * ONE place where include/exclude filtering of the native tool set happens;
+ * every generate/stream path reaches it via BaseProvider.
+ *
+ * Generic over the tool value type so it works for AI-SDK Tool records,
+ * ToolInfo listings, and provider wire formats alike.
+ */
+import { toolNameMatcher } from "./toolPolicy.js";
+/**
+ * Filter a tools record according to the resolved policy.
+ * Order: enabled kill-switch → include allowlist → exclude denylist.
+ * Preserves the input record's key order for surviving tools (callers rely
+ * on deterministic ordering for provider prompt-cache stability).
+ */
+export function applyToolGate(tools, policy) {
+    if (!policy.enabled) {
+        return {};
+    }
+    const include = policy.include;
+    const includeBound = policy.includeBound;
+    const hasExclude = policy.exclude.length > 0;
+    if (include === undefined && includeBound === undefined && !hasExclude) {
+        return tools;
+    }
+    const includeMatcher = include !== undefined ? toolNameMatcher(include) : undefined;
+    // Secondary allowlist clause ANDed with `include` (see ResolvedToolPolicy):
+    // a name must match BOTH when a per-call filter is bounded by the
+    // instance-level tools.include.
+    const boundMatcher = includeBound !== undefined ? toolNameMatcher(includeBound) : undefined;
+    const excludeMatcher = hasExclude
+        ? toolNameMatcher(policy.exclude)
+        : undefined;
+    // Null prototype: a tool named "__proto__" must become an own entry, not
+    // a prototype mutation (mirrors BaseProvider.sortToolRecord).
+    const result = Object.create(null);
+    for (const [name, tool] of Object.entries(tools)) {
+        if (includeMatcher && !includeMatcher(name)) {
+            continue;
+        }
+        if (boundMatcher && !boundMatcher(name)) {
+            continue;
+        }
+        if (excludeMatcher && excludeMatcher(name)) {
+            continue;
+        }
+        result[name] = tool;
+    }
+    return result;
+}
+//# sourceMappingURL=toolGate.js.map

package/dist/lib/tools/toolPolicy.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Tool policy resolution — the single, pure mapping from every tool-selection
+ * surface (per-call legacy options + instance-level `tools` config) to one
+ * ResolvedToolPolicy that the gate applies.
+ *
+ * Legacy semantics are preserved deliberately:
+ * - `toolFilter: []` and `enabledToolNames: []` are no-ops (fail-open), as
+ *   they always were.
+ * - Malformed shapes (non-string-arrays) are ignored with a once-per-process
+ *   WARN instead of throwing — some internal callers historically passed
+ *   wrong shapes and relied on the silent no-op.
+ * - `enabledToolNames` now filters the native tool set (its docs always
+ *   promised this; it previously only filtered the system-prompt listing) —
+ *   but ONLY when `toolFilter` is absent. When both are set, `toolFilter`
+ *   alone bounds the native set, exactly as before this refactor: the native
+ *   set must never become WIDER than a caller's `toolFilter`.
+ *
+ * New semantics:
+ * - `tools.include: []` (the instance config surface) means NO tools
+ *   (fail-closed); legacy empty arrays stay fail-open as above.
+ * - A per-call `toolFilter` is bounded by `tools.include` — it can narrow
+ *   the instance allowlist but never widen past it.
+ * - Pattern entries containing `*` match as globs (e.g. `"github*"`) on ALL
+ *   surfaces. Real tool names cannot contain `*` (MCP names are sanitized),
+ *   so a legacy list entry with `*` previously matched nothing (dead entry);
+ *   it now matches as a glob. Entries without `*` match exactly, unchanged.
+ */
+import type { ResolvedToolPolicy, ToolPolicyResolutionInput } from "../types/index.js";
+/**
+ * Compile a list of tool-name patterns into a matcher. Patterns without `*`
+ * match exactly (case-sensitive, preserving legacy toolFilter semantics);
+ * patterns containing `*` match as globs.
+ */
+export declare function toolNameMatcher(patterns: string[]): (name: string) => boolean;
+/**
+ * Resolve the effective tool policy for one request. Pure function — all
+ * inputs are explicit, so the legacy→policy mapping is unit-testable as a
+ * table.
+ */
+export declare function resolveToolPolicy(input: ToolPolicyResolutionInput): ResolvedToolPolicy;

package/dist/lib/tools/toolPolicy.js

@@ -0,0 +1,194 @@
+/**
+ * Tool policy resolution — the single, pure mapping from every tool-selection
+ * surface (per-call legacy options + instance-level `tools` config) to one
+ * ResolvedToolPolicy that the gate applies.
+ *
+ * Legacy semantics are preserved deliberately:
+ * - `toolFilter: []` and `enabledToolNames: []` are no-ops (fail-open), as
+ *   they always were.
+ * - Malformed shapes (non-string-arrays) are ignored with a once-per-process
+ *   WARN instead of throwing — some internal callers historically passed
+ *   wrong shapes and relied on the silent no-op.
+ * - `enabledToolNames` now filters the native tool set (its docs always
+ *   promised this; it previously only filtered the system-prompt listing) —
+ *   but ONLY when `toolFilter` is absent. When both are set, `toolFilter`
+ *   alone bounds the native set, exactly as before this refactor: the native
+ *   set must never become WIDER than a caller's `toolFilter`.
+ *
+ * New semantics:
+ * - `tools.include: []` (the instance config surface) means NO tools
+ *   (fail-closed); legacy empty arrays stay fail-open as above.
+ * - A per-call `toolFilter` is bounded by `tools.include` — it can narrow
+ *   the instance allowlist but never widen past it.
+ * - Pattern entries containing `*` match as globs (e.g. `"github*"`) on ALL
+ *   surfaces. Real tool names cannot contain `*` (MCP names are sanitized),
+ *   so a legacy list entry with `*` previously matched nothing (dead entry);
+ *   it now matches as a glob. Entries without `*` match exactly, unchanged.
+ */
+import { logger } from "../utils/logger.js";
+const warnedOnce = new Set();
+function warnOnce(key, message, detail) {
+    if (!warnedOnce.has(key)) {
+        warnedOnce.add(key);
+        logger.warn(message, detail);
+    }
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Compile a list of tool-name patterns into a matcher. Patterns without `*`
+ * match exactly (case-sensitive, preserving legacy toolFilter semantics);
+ * patterns containing `*` match as globs.
+ */
+export function toolNameMatcher(patterns) {
+    const exact = new Set();
+    const globs = [];
+    for (const pattern of patterns) {
+        if (pattern.includes("*")) {
+            // Split on RUNS of asterisks: "a**b" must compile to /^a.*b$/, not
+            // /^a.*.*b$/ — adjacent .* pairs invite catastrophic backtracking on
+            // long non-matching names (ReDoS).
+            const source = "^" + pattern.split(/\*+/).map(escapeRegExp).join(".*") + "$";
+            globs.push(new RegExp(source));
+        }
+        else {
+            exact.add(pattern);
+        }
+    }
+    return (name) => exact.has(name) || globs.some((g) => g.test(name));
+}
+/**
+ * Normalize a possibly-malformed option value to a string array.
+ * Returns undefined (and WARNs once per source) for anything that is not a
+ * proper string array — preserving the historical silent-no-op behavior for
+ * wrong shapes while making it observable. Used for the LEGACY per-call
+ * surfaces only; the new config surface uses normalizeConfigList, which does
+ * not fail open.
+ */
+function asStringArray(value, sourceName) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        return value;
+    }
+    warnOnce(`shape:${sourceName}`, `[ToolPolicy] Ignoring ${sourceName}: expected string[]`, { receivedType: typeof value });
+    return undefined;
+}
+/**
+ * Normalize a `tools.include`/`tools.exclude` config value. Unlike the
+ * legacy surfaces, the NEW config surface must not silently fail open — a
+ * caller who fat-fingers `tools.include` intending to lock an instance down
+ * must not get every tool exposed:
+ * - a bare string is coerced to a one-element list (obvious intent),
+ * - an array is salvaged to its string entries (dropping the rest, WARNed —
+ *   for `include` this converges toward fewer tools, never more),
+ * - anything else fails CLOSED for `include` (empty list = no tools) and is
+ *   ignored-with-WARN for `exclude` (a denylist has no safe "closed" other
+ *   than excluding everything, which would be equally surprising).
+ */
+function normalizeConfigList(value, sourceName, failClosed) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === "string") {
+        warnOnce(`shape:${sourceName}`, `[ToolPolicy] ${sourceName} was a bare string; coercing to a one-element list`, { received: value });
+        return [value];
+    }
+    if (Array.isArray(value)) {
+        const strings = value.filter((v) => typeof v === "string");
+        if (strings.length !== value.length) {
+            warnOnce(`shape:${sourceName}`, `[ToolPolicy] Dropped ${value.length - strings.length} non-string entr(ies) from ${sourceName}`);
+        }
+        return strings;
+    }
+    warnOnce(`shape:${sourceName}`, failClosed
+        ? `[ToolPolicy] ${sourceName} is malformed (expected string[]); failing CLOSED — no tools will be sent until it is fixed`
+        : `[ToolPolicy] Ignoring malformed ${sourceName}: expected string[]`, { receivedType: typeof value });
+    return failClosed ? [] : undefined;
+}
+/**
+ * Resolve the effective tool policy for one request. Pure function — all
+ * inputs are explicit, so the legacy→policy mapping is unit-testable as a
+ * table.
+ */
+export function resolveToolPolicy(input) {
+    const { options, instanceConfig, builtinToolNames } = input;
+    const sources = [];
+    // --- enabled -------------------------------------------------------------
+    let enabled = true;
+    if (options.disableTools === true) {
+        enabled = false;
+        sources.push("options.disableTools");
+    }
+    if (instanceConfig?.enabled === false) {
+        enabled = false;
+        sources.push("tools.enabled");
+    }
+    // --- allowlist -----------------------------------------------------------
+    // Legacy per-call allowlists: fail-open on empty (historical behavior).
+    const toolFilter = asStringArray(options.toolFilter, "options.toolFilter");
+    const enabledNames = asStringArray(options.enabledToolNames, "options.enabledToolNames");
+    let legacyInclude;
+    if (toolFilter && toolFilter.length > 0) {
+        // toolFilter alone bounds the native set — merging enabledToolNames in
+        // as a union would WIDEN the set beyond toolFilter, breaking the
+        // pre-refactor contract in the unsafe direction.
+        legacyInclude = [...new Set(toolFilter)];
+        sources.push("options.toolFilter");
+        if (enabledNames && enabledNames.length > 0) {
+            warnOnce("both-allowlists", "[ToolPolicy] Both toolFilter and enabledToolNames are set; toolFilter bounds the native tool set and enabledToolNames is ignored for it (pre-existing contract).");
+        }
+    }
+    else if (enabledNames && enabledNames.length > 0) {
+        legacyInclude = [...new Set(enabledNames)];
+        sources.push("options.enabledToolNames");
+    }
+    // New instance allowlist: fail-closed on empty ([] = no tools) AND on
+    // malformed shapes — a broken lockdown config must never expose all tools.
+    const configInclude = normalizeConfigList(instanceConfig?.include, "tools.include", true);
+    if (configInclude !== undefined) {
+        sources.push("tools.include");
+    }
+    let include;
+    let includeBound;
+    if (legacyInclude !== undefined && configInclude !== undefined) {
+        // Per-call filter is bounded by the instance allowlist: a tool must
+        // match BOTH lists. Kept as two matcher clauses (include AND
+        // includeBound) because glob pattern lists cannot be losslessly
+        // pre-intersected into one pattern array — filtering one list's pattern
+        // STRINGS through the other list's matcher would zero out overlapping
+        // globs like toolFilter:["github*"] vs include:["github_read*"].
+        include = legacyInclude;
+        includeBound = configInclude;
+    }
+    else {
+        include = legacyInclude ?? configInclude;
+    }
+    // --- denylist ------------------------------------------------------------
+    const exclude = [];
+    const optExclude = asStringArray(options.excludeTools, "options.excludeTools");
+    if (optExclude && optExclude.length > 0) {
+        exclude.push(...optExclude);
+        sources.push("options.excludeTools");
+    }
+    const cfgExclude = normalizeConfigList(instanceConfig?.exclude, "tools.exclude", false);
+    if (cfgExclude && cfgExclude.length > 0) {
+        exclude.push(...cfgExclude);
+        sources.push("tools.exclude");
+    }
+    if (instanceConfig?.disableBuiltinTools === true &&
+        builtinToolNames &&
+        builtinToolNames.length > 0) {
+        exclude.push(...builtinToolNames);
+        sources.push("tools.disableBuiltinTools");
+    }
+    // --- discovery -----------------------------------------------------------
+    const discovery = instanceConfig?.discovery === true;
+    if (discovery) {
+        sources.push("tools.discovery");
+    }
+    return { enabled, include, includeBound, exclude, discovery, sources };
+}
+//# sourceMappingURL=toolPolicy.js.map

package/dist/lib/types/config.d.ts

@@ -42,6 +42,12 @@ export type NeurolinkConstructorConfig = {
     conversationMemory?: Partial<ConversationMemoryConfig>;
     enableOrchestration?: boolean;
     hitl?: HITLConfig;
+    /**
+     * Instance-level tool policy: master switch, include/exclude lists
+     * (with `*` glob support), and on-demand MCP tool discovery.
+     * See {@link ToolConfig}.
+     */
+    tools?: ToolConfig;
     toolRegistry?: MCPToolRegistry;
     observability?: ObservabilityConfig;
     modelAliasConfig?: ModelAliasConfig;
@@ -329,14 +335,48 @@ export type AnalyticsConfig = {
     };
 };
 /**
- * Tool configuration
+ * Instance-level tool configuration (`new NeuroLink({ tools: {...} })`).
+ *
+ * The four primary keys (`enabled`, `include`, `exclude`, `discovery`) form
+ * the complete modern surface; per-call options (`toolFilter`,
+ * `excludeTools`, `enabledToolNames`, `disableTools`) keep working and are
+ * merged with this config by `resolveToolPolicy()`.
  */
 export type ToolConfig = {
-    /** Whether built-in tools should be disabled */
+    /**
+     * Master switch. `false` disables all tools for every call from this
+     * instance (equivalent to passing `disableTools: true` on each call).
+     * Default: true.
+     */
+    enabled?: boolean;
+    /**
+     * Allowlist of tool names. Supports `*` globs (e.g. `"github*"`).
+     * Undefined = all tools; an EMPTY array means no tools (fail-closed).
+     * Per-call `toolFilter` is bounded by this list (a per-call filter can
+     * narrow it further but never widen past it).
+     */
+    include?: string[];
+    /** Denylist of tool names (supports `*` globs). Applied after `include`. */
+    exclude?: string[];
+    /**
+     * Defer external MCP tool schemas behind a `search_tools` meta-tool: the
+     * model sees a compact name+summary catalog instead of full schemas and
+     * loads a tool on demand by searching for it. Built-in tools, per-call
+     * tools, per-call whitelists (`toolFilter`/`enabledToolNames`), forced
+     * `toolChoice` tools, and already-discovered tools are always sent in
+     * 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).
+     * Default: false.
+     */
+    discovery?: boolean;
+    /** Whether built-in tools should be disabled (equivalent to excluding all direct tools) */
     disableBuiltinTools?: boolean;
     /** Whether custom tools are allowed */
     allowCustomTools?: boolean;
-    /** Maximum number of tools per provider */
+    /**
+     * @deprecated Never enforced; retained for compile compatibility only.
+     */
     maxToolsPerProvider?: number;
     /** Whether MCP tools should be enabled */
     enableMCPTools?: boolean;

package/dist/lib/types/index.d.ts

@@ -52,6 +52,7 @@ export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
 export * from "./toolDedup.js";
+export * from "./toolResolution.js";
 export * from "./toolRouting.js";
 export * from "./tools.js";
 export * from "./vectorStoreChroma.js";

package/dist/lib/types/index.js

@@ -53,6 +53,7 @@ export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
 export * from "./toolDedup.js";
+export * from "./toolResolution.js";
 export * from "./toolRouting.js";
 export * from "./tools.js";
 export * from "./vectorStoreChroma.js";