@juspay/neurolink 9.89.0 → 9.91.0

package/dist/rag/stores/pinecone.js

@@ -0,0 +1,158 @@
+/**
+ * Pinecone Vector Store Adapter
+ *
+ * Implements the `VectorStore` contract (see `src/lib/types/rag.ts`) against
+ * a Pinecone index, using client injection: callers construct their own
+ * `@pinecone-database/pinecone` client/index and pass it in. No Pinecone SDK
+ * is a runtime dependency of this package — `PineconeIndexLike` below is a
+ * minimal structural interface satisfied by the real `Index` object (and by
+ * hand-written mocks in tests).
+ *
+ * ## indexName -> namespace mapping
+ *
+ * The `VectorStore` contract's `indexName` parameter is mapped onto a
+ * Pinecone **namespace**, not a Pinecone index. Pinecone ties one client
+ * `Index` object to a single physical index (created ahead of time via
+ * Pinecone's control-plane API); namespaces are Pinecone's mechanism for
+ * partitioning data *within* that one index, and are the closest match to
+ * this SDK's per-call `indexName` concept.
+ *
+ * - If the injected client exposes `.namespace(name)` (as the real
+ *   `@pinecone-database/pinecone` `Index.namespace()` does), every
+ *   query/upsert/delete call routes through `client.namespace(indexName)`.
+ * - If the injected client does not expose `.namespace` (e.g. a caller
+ *   already pre-scoped their client to a fixed namespace, or a minimal
+ *   mock), calls go straight to the injected client and `indexName` has
+ *   no further effect. Document this for your callers if you construct a
+ *   `PineconeVectorStore` from a namespace-fixed client.
+ *
+ * ## Metadata filter translation
+ *
+ * `MetadataFilter` (Mongo/Sift-style) is translated to Pinecone's native
+ * filter DSL, which already shares the same `$op` shape for comparison
+ * operators. Supported operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`,
+ * `$lte`, `$in`, `$nin` (field-level) and `$and` / `$or` (logical,
+ * recursively translated). Any other operator — `$not`, `$nor`, `$exists`,
+ * `$contains`, `$regex`, `$size` — has no Pinecone equivalent and throws a
+ * clear `Error` naming the offending operator/field rather than silently
+ * mis-filtering (Pinecone's filter DSL has no negation, existence, string
+ * containment, regex, or array-length operators).
+ */
+/** Comparison operators Pinecone's filter DSL can express, verbatim. */
+const SUPPORTED_COMPARISON_OPS = new Set([
+    "$eq",
+    "$ne",
+    "$gt",
+    "$gte",
+    "$lt",
+    "$lte",
+    "$in",
+    "$nin",
+]);
+/** Logical operators Pinecone's filter DSL can express, verbatim. */
+const SUPPORTED_LOGICAL_OPS = new Set(["$and", "$or"]);
+/**
+ * Translate a `MetadataFilter` into Pinecone's native filter object.
+ *
+ * Throws a descriptive `Error` for any operator Pinecone cannot express
+ * ($not, $nor, $exists, $contains, $regex, $size) instead of silently
+ * dropping or mis-applying it.
+ */
+export function translatePineconeFilter(filter) {
+    const result = {};
+    for (const [key, value] of Object.entries(filter)) {
+        if (key.startsWith("$")) {
+            if (!SUPPORTED_LOGICAL_OPS.has(key)) {
+                throw new Error(`PineconeVectorStore: MetadataFilter operator "${key}" cannot be translated to Pinecone's filter DSL ` +
+                    `(supported logical operators: ${[...SUPPORTED_LOGICAL_OPS].join(", ")}). ` +
+                    `Restructure the filter to avoid "${key}".`);
+            }
+            const subFilters = value;
+            result[key] = subFilters.map((sub) => translatePineconeFilter(sub));
+            continue;
+        }
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            const ops = value;
+            const translatedOps = {};
+            for (const opKey of Object.keys(ops)) {
+                if (!SUPPORTED_COMPARISON_OPS.has(opKey)) {
+                    throw new Error(`PineconeVectorStore: MetadataFilter operator "${opKey}" on field "${key}" cannot be translated to ` +
+                        `Pinecone's filter DSL (supported: ${[...SUPPORTED_COMPARISON_OPS].join(", ")}). ` +
+                        `Restructure the filter to avoid "${opKey}" on "${key}".`);
+                }
+                translatedOps[opKey] = ops[opKey];
+            }
+            result[key] = translatedOps;
+        }
+        else {
+            // Primitive/array/null value: Pinecone treats a bare value as
+            // implicit equality, matching InMemoryVectorStore's direct-equality
+            // fallback for non-object filter values.
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Pinecone-backed implementation of the `VectorStore` contract.
+ *
+ * @example
+ * ```typescript
+ * import { Pinecone } from '@pinecone-database/pinecone';
+ * import { PineconeVectorStore } from '@juspay/neurolink/rag';
+ *
+ * const client = new Pinecone({ apiKey: process.env.PINECONE_API_KEY! });
+ * const store = new PineconeVectorStore(client.index('my-index'));
+ *
+ * await store.upsert('tenant-a', [{ id: '1', vector: [...], metadata: { text: 'hello' } }]);
+ * const results = await store.query({ indexName: 'tenant-a', queryVector: [...], topK: 5 });
+ * ```
+ */
+export class PineconeVectorStore {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Resolve the Pinecone client scoped to `indexName` (see class docs re: namespace mapping). */
+    resolveClient(indexName) {
+        return this.client.namespace
+            ? this.client.namespace(indexName)
+            : this.client;
+    }
+    async query(params) {
+        const { indexName, queryVector, topK = 10, filter, includeVectors = false, } = params;
+        const target = this.resolveClient(indexName);
+        const response = await target.query({
+            vector: queryVector,
+            topK,
+            ...(filter ? { filter: translatePineconeFilter(filter) } : {}),
+            includeMetadata: true,
+            includeValues: includeVectors,
+        });
+        const matches = response.matches ?? [];
+        return matches.map((match) => {
+            const metadata = match.metadata ?? {};
+            return {
+                id: match.id,
+                score: match.score,
+                text: metadata.text,
+                metadata,
+                ...(includeVectors && match.values ? { vector: match.values } : {}),
+            };
+        });
+    }
+    /** Add or update vectors in the namespace mapped from `indexName`. */
+    async upsert(indexName, items) {
+        const target = this.resolveClient(indexName);
+        await target.upsert(items.map((item) => ({
+            id: item.id,
+            values: item.vector,
+            metadata: item.metadata ?? {},
+        })));
+    }
+    /** Delete vectors by id from the namespace mapped from `indexName`. */
+    async delete(indexName, ids) {
+        const target = this.resolveClient(indexName);
+        await target.deleteMany(ids);
+    }
+}

package/dist/server/routes/agentRoutes.js

@@ -6,6 +6,27 @@ import { SpanStatusCode } from "@opentelemetry/api";
 import { ProviderFactory } from "../../factories/providerFactory.js";
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * Resolve `request.tools` (an array of tool NAMES shared by the execute and
+ * stream endpoints) into a `toolFilter` whitelist. The field was previously
+ * accepted and silently ignored, so entries are validated against registered
+ * names and the whole field fails open (undefined — keep all tools) when
+ * nothing matches: existing clients sending unknown names must not lose
+ * their tool set.
+ */
+async function resolveRequestToolFilter(ctx, requestedTools) {
+    if (!Array.isArray(requestedTools) || requestedTools.length === 0) {
+        return undefined;
+    }
+    const registered = new Set((await ctx.neurolink.getAllAvailableTools()).map((t) => t.name));
+    const known = requestedTools.filter((name) => typeof name === "string" && registered.has(name));
+    if (known.length > 0) {
+        return known;
+    }
+    logger.warn("[agentRoutes] Ignoring request.tools — no entries match registered tool names (legacy fail-open)", { requested: requestedTools });
+    return undefined;
+}
 import { createStreamRedactor } from "../utils/redaction.js";
 import { AgentExecuteRequestSchema, createErrorResponse as createError, EmbedManyRequestSchema, EmbedRequestSchema, SkillCreateRequestSchema, SkillUpdateRequestSchema, validateRequest, } from "../utils/validation.js";
 /**
@@ -65,6 +86,7 @@ export function createAgentRoutes(basePath = "/api") {
                         const input = typeof request.input === "string"
                             ? { text: request.input }
                             : request.input;
+                        const requestToolFilter = await resolveRequestToolFilter(ctx, request.tools);
                         const result = await ctx.neurolink.generate({
                             input,
                             provider: request.provider,
@@ -72,8 +94,7 @@ export function createAgentRoutes(basePath = "/api") {
                             systemPrompt: request.systemPrompt,
                             temperature: request.temperature,
                             maxTokens: request.maxTokens,
-                            // Note: tools should be passed as Record<string, Tool> in generate options
-                            // If request.tools is an array of tool names, we skip them
+                            ...(requestToolFilter ? { toolFilter: requestToolFilter } : {}),
                             context: {
                                 // When an authenticated user context exists (set by auth middleware),
                                 // always use its IDs to prevent caller-supplied impersonation.
@@ -118,6 +139,7 @@ export function createAgentRoutes(basePath = "/api") {
                     const input = typeof request.input === "string"
                         ? { text: request.input }
                         : request.input;
+                    const streamToolFilter = await resolveRequestToolFilter(ctx, request.tools);
                     const result = await ctx.neurolink.stream({
                         input,
                         provider: request.provider,
@@ -125,6 +147,7 @@ export function createAgentRoutes(basePath = "/api") {
                         systemPrompt: request.systemPrompt,
                         temperature: request.temperature,
                         maxTokens: request.maxTokens,
+                        ...(streamToolFilter ? { toolFilter: streamToolFilter } : {}),
                         context: {
                             // When an authenticated user context exists (set by auth middleware),
                             // always use its IDs to prevent caller-supplied impersonation.

package/dist/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/tools/toolDiscovery.js

@@ -0,0 +1,230 @@
+/**
+ * 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;
+}

package/dist/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/tools/toolGate.js

@@ -0,0 +1,50 @@
+/**
+ * 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;
+}

package/dist/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;