@juspay/neurolink 9.89.0 → 9.91.0

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,8 +52,11 @@ 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";
+export * from "./vectorStorePinecone.js";
 export * from "./voice.js";
 export * from "./universalProviderOptions.js";
 export * from "./utilities.js";

package/dist/lib/types/index.js

@@ -53,8 +53,11 @@ 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";
+export * from "./vectorStorePinecone.js";
 export * from "./voice.js";
 export * from "./universalProviderOptions.js";
 export * from "./utilities.js";

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

@@ -593,6 +593,14 @@ export type AIProvider = {
         traceId: string;
         parentSpanId: string;
     } | null): void;
+    /**
+     * Whether this provider supports native tool/function calling for the
+     * current model. Implemented by BaseProvider (default true); overridden by
+     * providers with model-dependent or absent tool support (ollama,
+     * huggingface, image providers). Optional for compile compatibility with
+     * external AIProvider implementations — callers treat absence as `true`.
+     */
+    supportsTools?(): boolean;
 };
 /**
  * Provider attempt result for iteration tracking (converted from interface)

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

@@ -419,6 +419,36 @@ export type VectorStore = {
         includeVectors?: boolean;
     }): Promise<VectorQueryResult[]>;
 };
+/** Minimal shape of a query result, satisfied by both `pg` and `pglite`. */
+export type PgQueryResult<T = unknown> = {
+    rows: T[];
+};
+/**
+ * Minimal structural interface a caller-supplied Postgres client must
+ * satisfy. Both `pg.Pool` (`node-postgres`) and `@electric-sql/pglite`
+ * instances already expose a compatible `query(text, values?)` method —
+ * neither is a dependency of this package. Callers construct and own the
+ * client; `PgVectorStore` only ever calls `query()` on it.
+ */
+export type PgClientLike = {
+    query(text: string, values?: unknown[]): Promise<PgQueryResult>;
+};
+/** Construction options for `PgVectorStore`. */
+export type PgVectorStoreOptions = {
+    /**
+     * Prefix prepended to `indexName` to derive the backing table name.
+     * Must itself be a valid, unquoted Postgres identifier.
+     * @default "neurolink_vs_"
+     */
+    tablePrefix?: string;
+};
+/** Row shape returned by `PgVectorStore`'s SELECT queries. */
+export type PgVectorStoreRow = {
+    id: string;
+    metadata: unknown;
+    score: unknown;
+    embedding?: unknown;
+};
 /**
  * Document loader options
  */

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

@@ -0,0 +1,73 @@
+/**
+ * Tool resolution types — the single tool-policy pipeline that decides which
+ * tools are sent to a provider for a given request.
+ *
+ * One policy object is resolved per request from (a) per-call legacy options
+ * (`toolFilter`, `excludeTools`, `enabledToolNames`, `disableTools`) and
+ * (b) the instance-level `tools` config, then applied at the single gate in
+ * `BaseProvider` that every generate/stream path passes through.
+ */
+import type { ToolConfig } from "./config.js";
+/**
+ * The resolved, merged tool policy for one request. Produced by
+ * `resolveToolPolicy()` (src/lib/tools/toolPolicy.ts) and consumed by
+ * `applyToolGate()` (src/lib/tools/toolGate.ts).
+ */
+export type ResolvedToolPolicy = {
+    /** false = no tools at all for this request (drops caller-supplied tools too). */
+    enabled: boolean;
+    /**
+     * Allowlist of tool-name patterns (exact names or `*` globs).
+     * `undefined` = all tools pass. An empty array means "no tools" — it can
+     * only come from the new `tools.include` config surface; legacy
+     * `toolFilter: []` is normalized to `undefined` (fail-open, preserving
+     * historical behavior) before it reaches here.
+     */
+    include?: string[];
+    /**
+     * Secondary allowlist clause ANDed with `include` — set when both a
+     * legacy per-call allowlist and the instance `tools.include` are present.
+     * Kept as a separate clause because two glob pattern lists cannot be
+     * losslessly pre-intersected into a single pattern array (a name must
+     * match BOTH lists to pass).
+     */
+    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. */
+    discovery: boolean;
+    /** Which option/config sources contributed to this policy (telemetry/debugging). */
+    sources: string[];
+};
+/**
+ * Inputs to `resolveToolPolicy()`. Kept as a named type so the mapping is
+ * unit-testable as a pure function.
+ */
+export type ToolPolicyResolutionInput = {
+    /** Per-call options (the legacy per-call filtering surface). */
+    options: {
+        disableTools?: boolean;
+        toolFilter?: string[];
+        enabledToolNames?: string[];
+        excludeTools?: string[];
+    };
+    /** Instance-level `tools` config passed to the NeuroLink constructor. */
+    instanceConfig?: ToolConfig;
+    /**
+     * Names of the built-in (direct) tools of the calling provider — used to
+     * honor `tools.disableBuiltinTools` without this module importing the
+     * direct-tools registry.
+     */
+    builtinToolNames?: string[];
+};
+/**
+ * One entry in the deferred-tool catalog embedded in the `search_tools`
+ * meta-tool description when `tools.discovery` is enabled.
+ */
+export type DeferredToolIndexEntry = {
+    name: string;
+    /** One-line description (truncated) shown in the search_tools catalog. */
+    summary: string;
+    /** Originating MCP server id, when known. */
+    serverId?: string;
+};

package/dist/lib/types/toolResolution.js

@@ -0,0 +1,11 @@
+/**
+ * Tool resolution types — the single tool-policy pipeline that decides which
+ * tools are sent to a provider for a given request.
+ *
+ * One policy object is resolved per request from (a) per-call legacy options
+ * (`toolFilter`, `excludeTools`, `enabledToolNames`, `disableTools`) and
+ * (b) the instance-level `tools` config, then applied at the single gate in
+ * `BaseProvider` that every generate/stream path passes through.
+ */
+export {};
+//# sourceMappingURL=toolResolution.js.map

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

@@ -0,0 +1,67 @@
+/**
+ * Structural types for the Chroma vector store adapter
+ * (`src/lib/rag/stores/chroma.ts`).
+ *
+ * These mirror the subset of the `chromadb` package's API the adapter
+ * calls (`ChromaClient.getOrCreateCollection`, `Collection.upsert/query/
+ * delete`). NeuroLink has zero runtime dependency on `chromadb` — callers
+ * construct their own client and inject an object satisfying
+ * `ChromaClientLike`.
+ */
+export type ChromaMetadataValue = string | number | boolean;
+export type ChromaMetadata = Record<string, ChromaMetadataValue>;
+/** Chroma's metadata `where` filter payload shape. */
+export type ChromaWhere = Record<string, unknown>;
+export type ChromaIncludeField = "embeddings" | "metadatas" | "documents" | "distances";
+export type ChromaUpsertParams = {
+    ids: string[];
+    embeddings?: number[][];
+    metadatas?: Array<ChromaMetadata | null>;
+    documents?: Array<string | null>;
+};
+export type ChromaQueryParams = {
+    queryEmbeddings: number[][];
+    nResults?: number;
+    where?: ChromaWhere;
+    include?: ChromaIncludeField[];
+};
+export type ChromaQueryResponse = {
+    ids: string[][];
+    embeddings?: Array<Array<number[] | null>> | null;
+    metadatas?: Array<Array<ChromaMetadata | null>> | null;
+    documents?: Array<Array<string | null>> | null;
+    distances?: Array<Array<number | null>> | null;
+};
+export type ChromaDeleteParams = {
+    ids?: string[];
+    where?: ChromaWhere;
+};
+/**
+ * Minimal structural interface for a Chroma collection handle, matching the
+ * subset of `Collection` (from `chromadb`) the adapter calls.
+ */
+export type ChromaCollectionLike = {
+    upsert(params: ChromaUpsertParams): Promise<unknown>;
+    query(params: ChromaQueryParams): Promise<ChromaQueryResponse>;
+    delete(params: ChromaDeleteParams): Promise<unknown>;
+};
+/**
+ * Minimal structural interface for a Chroma client, matching the subset of
+ * `ChromaClient` (from `chromadb`) the adapter calls.
+ */
+export type ChromaClientLike = {
+    getOrCreateCollection(params: {
+        name: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<ChromaCollectionLike>;
+};
+export type ChromaDistanceMetric = "cosine" | "l2" | "ip";
+export type ChromaVectorStoreOptions = {
+    /**
+     * The distance metric configured on the underlying Chroma collection(s)
+     * (Chroma's `hnsw:space`). Used only to convert returned distances into a
+     * `score`; see `src/lib/rag/stores/chroma.ts` module doc comment.
+     * Defaults to `"cosine"`.
+     */
+    distanceMetric?: ChromaDistanceMetric;
+};

package/dist/lib/types/vectorStoreChroma.js

@@ -0,0 +1,12 @@
+/**
+ * Structural types for the Chroma vector store adapter
+ * (`src/lib/rag/stores/chroma.ts`).
+ *
+ * These mirror the subset of the `chromadb` package's API the adapter
+ * calls (`ChromaClient.getOrCreateCollection`, `Collection.upsert/query/
+ * delete`). NeuroLink has zero runtime dependency on `chromadb` — callers
+ * construct their own client and inject an object satisfying
+ * `ChromaClientLike`.
+ */
+export {};
+//# sourceMappingURL=vectorStoreChroma.js.map

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

@@ -0,0 +1,48 @@
+/**
+ * Structural types for the Pinecone vector store adapter
+ * (`src/lib/rag/stores/pinecone.ts`).
+ *
+ * These mirror the subset of the `@pinecone-database/pinecone` package's API
+ * the adapter calls (`Index.query/upsert/deleteMany`, optional
+ * `Index.namespace`). NeuroLink has zero runtime dependency on the Pinecone
+ * SDK — callers construct their own client/index and inject an object
+ * satisfying `PineconeIndexLike`.
+ */
+/** A single scored match as returned by Pinecone's query API. */
+export type PineconeMatch = {
+    id: string;
+    score?: number;
+    values?: number[];
+    metadata?: Record<string, unknown>;
+};
+/** Shape of the response returned by `PineconeIndexLike.query()`. */
+export type PineconeQueryResponse = {
+    matches?: PineconeMatch[];
+};
+/** Request payload accepted by `PineconeIndexLike.query()`. */
+export type PineconeQueryRequest = {
+    vector: number[];
+    topK: number;
+    filter?: Record<string, unknown>;
+    includeMetadata?: boolean;
+    includeValues?: boolean;
+};
+/** A single record accepted by `PineconeIndexLike.upsert()`. */
+export type PineconeUpsertRecord = {
+    id: string;
+    values: number[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Minimal structural interface modeled on the `@pinecone-database/pinecone`
+ * `Index` object. Satisfied by the real SDK's `Index` without modification;
+ * callers never need to install the Pinecone SDK as a dependency of this
+ * package — they bring their own already-constructed client instance.
+ */
+export type PineconeIndexLike = {
+    /** Returns a client scoped to the given namespace, if the client supports namespacing. */
+    namespace?(ns: string): PineconeIndexLike;
+    query(request: PineconeQueryRequest): Promise<PineconeQueryResponse>;
+    upsert(records: PineconeUpsertRecord[]): Promise<unknown>;
+    deleteMany(ids: string[]): Promise<unknown>;
+};

package/dist/lib/types/vectorStorePinecone.js

@@ -0,0 +1,12 @@
+/**
+ * Structural types for the Pinecone vector store adapter
+ * (`src/lib/rag/stores/pinecone.ts`).
+ *
+ * These mirror the subset of the `@pinecone-database/pinecone` package's API
+ * the adapter calls (`Index.query/upsert/deleteMany`, optional
+ * `Index.namespace`). NeuroLink has zero runtime dependency on the Pinecone
+ * SDK — callers construct their own client/index and inject an object
+ * satisfying `PineconeIndexLike`.
+ */
+export {};
+//# sourceMappingURL=vectorStorePinecone.js.map

package/dist/mcp/toolRegistry.js

@@ -7,6 +7,7 @@ import { registryLogger } from "../utils/logger.js";
 import { randomUUID } from "crypto";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { directAgentTools } from "../agent/directTools.js";
+import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
 import { detectCategory, createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { FlexibleToolValidator } from "./flexibleToolValidator.js";
 import { ErrorFactory } from "../utils/errorHandling.js";
@@ -57,10 +58,14 @@ export class MCPToolRegistry extends MCPRegistry {
                 continue;
             }
             const toolId = `direct.${toolName}`;
+            // Register the tool's real parameter schema (converted from Zod) instead
+            // of a `{}` placeholder — token-budget accounting and tool listings read
+            // this ToolInfo, and an empty schema makes both under-count reality.
+            const inputSchema = convertZodToJsonSchema(toolDef.inputSchema);
             const toolInfo = {
                 name: toolName,
                 description: toolDef.description || `Direct tool: ${toolName}`,
-                inputSchema: {},
+                inputSchema,
                 serverId: "direct",
                 category: detectCategory({ isBuiltIn: true, serverId: "direct" }),
             };
@@ -98,7 +103,7 @@ export class MCPToolRegistry extends MCPRegistry {
                     }
                 },
                 description: toolDef.description,
-                inputSchema: {},
+                inputSchema,
             });
             registryLogger.debug(`Registered direct tool: ${toolName} as ${toolId}`);
         }

package/dist/neurolink.d.ts

@@ -6,7 +6,7 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 import type { AgentDefinition, AgentNetworkConfig, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -107,6 +107,9 @@ export declare class NeuroLink {
     private toolRoutingCacheInstance?;
     private toolRoutingVectorCache?;
     private toolDedupConfig?;
+    private toolsConfig?;
+    /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
+    private discoveryPins;
     private enableOrchestration;
     private authProvider?;
     private pendingAuthConfig?;
@@ -812,6 +815,11 @@ export declare class NeuroLink {
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a ToolInfo array.
      * Used to filter the tool list before building the system prompt.
+     *
+     * Resolves the SAME policy as the native gate (`BaseProvider`
+     * `applyToolFiltering`) — per-call options plus the instance-level `tools`
+     * config — so what the model is told about tools never diverges from the
+     * tools it can actually call.
      */
     private applyToolInfoFiltering;
     private createToolAwareSystemPrompt;
@@ -1194,6 +1202,28 @@ export declare class NeuroLink {
      * parameter through the full call stack.
      */
     getToolDedupConfig(): ToolDedupConfig | undefined;
+    /**
+     * Returns the instance-level `tools` config (master switch, include/exclude
+     * lists, discovery mode), or `undefined` when not provided at construction.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the tool gate composes the
+     * instance policy with per-call options on every generate/stream call.
+     */
+    getToolsConfig(): ToolConfig | undefined;
+    /**
+     * Tools discovered via `search_tools` for a session (`tools.discovery`
+     * mode). Pinned tools are sent in full on every subsequent call of that
+     * session instead of being deferred — discovery cost is paid once.
+     * Reading refreshes the session's recency (LRU), so active conversations
+     * are never the ones evicted at the session cap.
+     */
+    getDiscoveryPins(sessionKey: string): ReadonlySet<string>;
+    /**
+     * Pin discovered tools to a session (called by the `search_tools`
+     * meta-tool on hydration). Append-only within a session; the map is
+     * bounded by evicting the least-recently-used session past 1000 sessions.
+     */
+    pinDiscoveredTools(sessionKey: string, toolNames: string[]): void;
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *