@frontmcp/plugins 0.4.1 → 0.5.1

package/src/codecall/services/tool-search.service.js

@@ -0,0 +1,587 @@
+"use strict";
+// file: libs/plugins/src/codecall/services/tool-search.service.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolSearchService = void 0;
+const vectoriadb_1 = require("vectoriadb");
+const synonym_expansion_service_1 = require("./synonym-expansion.service");
+/**
+ * Universal Intent Mapping & Query Normalization
+ * - This module defines the semantic knowledge base for the MCP tool search engine.
+ *   It is designed to bridge the gap between natural language user intents
+ *   (e.g., "fix," "chat," "buy") and technical tool definitions (e.g., "update," "post," "create").
+ * - Key Parts:
+ *   1. DEFAULT_SYNONYM_GROUPS: A domain-agnostic mapping of bidirectional synonyms covering
+ *      CRUD, DevOps, Financial, Social, and Lifecycle operations. This ensures that a
+ *      query for "Show me the bill" matches a tool named "get_invoice".
+ *   2. STOP_WORDS: A curated exclusion list strictly optimized for Command-Line/Chat
+ *      interfaces. Unlike standard NLP stop lists, this PRESERVES action verbs
+ *      ("find", "start", "make") as they are critical signals of user intent in a
+ *      tool-execution context.
+ */
+const STOP_WORDS = new Set([
+    // Articles & Determiners
+    'the',
+    'a',
+    'an',
+    'this',
+    'that',
+    'these',
+    'those',
+    // Prepositions
+    'in',
+    'on',
+    'at',
+    'to',
+    'for',
+    'of',
+    'with',
+    'by',
+    'from',
+    'into',
+    'over',
+    'after',
+    'before',
+    'between',
+    'under',
+    'about',
+    'against',
+    'during',
+    'through',
+    // Conjunctions
+    'and',
+    'or',
+    'but',
+    'nor',
+    'so',
+    'yet',
+    'as',
+    'than',
+    'if',
+    'because',
+    'while',
+    'when',
+    'where',
+    'unless',
+    // Pronouns (Subject/Object/Possessive)
+    'i',
+    'me',
+    'my',
+    'mine',
+    'myself',
+    'you',
+    'your',
+    'yours',
+    'yourself',
+    'he',
+    'him',
+    'his',
+    'himself',
+    'she',
+    'her',
+    'hers',
+    'herself',
+    'it',
+    'its',
+    'itself',
+    'we',
+    'us',
+    'our',
+    'ours',
+    'ourselves',
+    'they',
+    'them',
+    'their',
+    'theirs',
+    'themselves',
+    'who',
+    'whom',
+    'whose',
+    'which',
+    'what',
+    // Auxiliary/Linking Verbs (State of being is usually noise, Action is signal)
+    'is',
+    'was',
+    'are',
+    'were',
+    'been',
+    'be',
+    'being',
+    'have',
+    'has',
+    'had',
+    'having',
+    'do',
+    'does',
+    'did',
+    'doing', // "do" is usually auxiliary ("do you have..."). "run" or "execute" is better.
+    'will',
+    'would',
+    'shall',
+    'should',
+    'can',
+    'could',
+    'may',
+    'might',
+    'must',
+    // Quantifiers / Adverbs of degree
+    'all',
+    'any',
+    'both',
+    'each',
+    'few',
+    'more',
+    'most',
+    'other',
+    'some',
+    'such',
+    'no',
+    'nor',
+    'not',
+    'only',
+    'own',
+    'same',
+    'too',
+    'very',
+    'just',
+    'even',
+    // Conversational / Chat Fillers (Common in LLM prompts)
+    'please',
+    'pls',
+    'plz',
+    'thanks',
+    'thank',
+    'thx',
+    'hello',
+    'hi',
+    'hey',
+    'ok',
+    'okay',
+    'yes',
+    'no',
+    'actually',
+    'basically',
+    'literally',
+    'maybe',
+    'perhaps',
+    'now',
+    'then',
+    'here',
+    'there',
+    'again',
+    'once',
+    'back', // "back" can be tricky, but usually implies direction not action
+    // Meta/Structural words
+    'example',
+    'context',
+    'optionally',
+    'optional', // Users rarely search for "optional", they search for the thing itself.
+    'etc',
+    'ie',
+    'eg',
+]);
+/**
+ * Service that maintains a searchable index of tools from the ToolRegistry
+ * Supports both TF-IDF (lightweight, synchronous) and ML-based (semantic) embeddings
+ * Implements the ToolSearch interface for dependency injection
+ */
+class ToolSearchService {
+    static MAX_SUBSCRIPTION_RETRIES = 100;
+    vectorDB;
+    strategy;
+    initialized = false;
+    mlInitialized = false;
+    subscriptionRetries = 0;
+    config;
+    scope;
+    unsubscribe;
+    synonymService = null;
+    constructor(config = {}, scope) {
+        this.scope = scope;
+        const embeddingOptions = config.embeddingOptions || {
+            strategy: 'tfidf',
+            modelName: 'Xenova/all-MiniLM-L6-v2',
+            cacheDir: './.cache/transformers',
+            useHNSW: false,
+            synonymExpansion: { enabled: true, replaceDefaults: false, maxExpansionsPerTerm: 5 },
+        };
+        this.strategy = config.strategy || embeddingOptions.strategy || 'tfidf';
+        this.config = {
+            strategy: this.strategy,
+            embeddingOptions,
+            defaultTopK: config.defaultTopK ?? 8,
+            defaultSimilarityThreshold: config.defaultSimilarityThreshold ?? 0.0,
+            mode: config.mode ?? 'codecall_only',
+            includeTools: config.includeTools,
+        };
+        // Validate mode parameter at runtime
+        const validModes = ['codecall_only', 'codecall_opt_in', 'metadata_driven'];
+        if (!validModes.includes(this.config.mode)) {
+            throw new Error(`Invalid CodeCall mode: ${this.config.mode}. Valid modes: ${validModes.join(', ')}`);
+        }
+        // Initialize the appropriate vector database
+        if (this.strategy === 'ml') {
+            this.vectorDB = new vectoriadb_1.VectoriaDB({
+                modelName: embeddingOptions.modelName || 'Xenova/all-MiniLM-L6-v2',
+                cacheDir: embeddingOptions.cacheDir || './.cache/transformers',
+                defaultTopK: this.config.defaultTopK,
+                defaultSimilarityThreshold: this.config.defaultSimilarityThreshold,
+                useHNSW: embeddingOptions.useHNSW || false,
+            });
+        }
+        else {
+            this.vectorDB = new vectoriadb_1.TFIDFVectoria({
+                defaultTopK: this.config.defaultTopK,
+                defaultSimilarityThreshold: this.config.defaultSimilarityThreshold,
+            });
+        }
+        // Initialize synonym expansion for TF-IDF strategy (ML already handles semantic similarity)
+        if (config.synonymExpansion === false) {
+            this.synonymService = null;
+        }
+        else if (this.strategy === 'tfidf') {
+            const synonymConfig = typeof config.synonymExpansion === 'object' ? config.synonymExpansion : {};
+            // Only enable if not explicitly disabled
+            if (synonymConfig.enabled !== false) {
+                this.synonymService = new synonym_expansion_service_1.SynonymExpansionService(synonymConfig);
+            }
+        }
+        // Defer subscription until scope.tools is available
+        // During plugin initialization, scope.tools may not exist yet
+        this.setupSubscription();
+    }
+    /**
+     * Sets up subscription to tool changes. Handles the case where scope.tools
+     * may not be available yet during plugin initialization.
+     */
+    setupSubscription() {
+        // If tools registry is not yet available, retry after a microtask
+        if (!this.scope.tools) {
+            if (this.subscriptionRetries++ >= ToolSearchService.MAX_SUBSCRIPTION_RETRIES) {
+                console.warn('ToolSearchService: scope.tools not available after max retries');
+                return;
+            }
+            // Use queueMicrotask to defer until after current initialization
+            queueMicrotask(() => this.setupSubscription());
+            return;
+        }
+        // Reset retry counter on success
+        this.subscriptionRetries = 0;
+        // Subscribe to tool changes with immediate=true to get current snapshot
+        // This ensures tools are indexed as they become available, regardless of loading order
+        this.unsubscribe = this.scope.tools.subscribe({ immediate: true }, (event) => {
+            // Handle tool change event - reindex all tools from the snapshot
+            this.handleToolChange(event.snapshot);
+        });
+    }
+    /**
+     * Handles tool change events by reindexing all tools from the snapshot
+     */
+    async handleToolChange(tools) {
+        // Clear and rebuild index
+        this.vectorDB.clear();
+        if (tools.length === 0) {
+            this.initialized = true;
+            return;
+        }
+        // Initialize ML model if needed (first time only, and only when we have tools)
+        // Deferred initialization avoids async operations when there's nothing to index
+        if (!this.mlInitialized && this.strategy === 'ml' && this.vectorDB instanceof vectoriadb_1.VectoriaDB) {
+            await this.vectorDB.initialize();
+            this.mlInitialized = true;
+        }
+        // Filter tools based on CodeCall config and per-tool metadata
+        const filteredTools = tools.filter((tool) => this.shouldIndexTool(tool));
+        if (filteredTools.length === 0) {
+            this.initialized = true;
+            return;
+        }
+        const documents = filteredTools.map((tool) => {
+            const searchableText = this.extractSearchableText(tool);
+            const appId = this.extractAppId(tool);
+            const toolName = tool.name;
+            const qualifiedName = tool.fullName || toolName;
+            return {
+                id: toolName,
+                text: searchableText,
+                metadata: {
+                    id: toolName,
+                    toolName,
+                    qualifiedName,
+                    appId,
+                    toolInstance: tool,
+                },
+            };
+        });
+        if (this.strategy === 'ml' && this.vectorDB instanceof vectoriadb_1.VectoriaDB) {
+            await this.vectorDB.addMany(documents);
+        }
+        else if (this.vectorDB instanceof vectoriadb_1.TFIDFVectoria) {
+            this.vectorDB.addDocuments(documents);
+            this.vectorDB.reindex();
+        }
+        this.initialized = true;
+    }
+    /**
+     * Determines if a tool should be indexed in the search database.
+     * Filters based on:
+     * - Excludes codecall:* meta-tools (they should not be searchable)
+     * - Mode-based filtering (codecall_only, codecall_opt_in, metadata_driven)
+     * - Per-tool metadata.codecall.enabledInCodeCall
+     * - Custom includeTools filter function
+     */
+    shouldIndexTool(tool) {
+        const toolName = tool.name || tool.fullName;
+        // Never index codecall:* meta-tools - they are for orchestration, not for search
+        if (toolName.startsWith('codecall:')) {
+            return false;
+        }
+        // Get CodeCall-specific metadata from the tool
+        const codecallMeta = this.getCodeCallMetadata(tool);
+        // Apply mode-based filtering
+        switch (this.config.mode) {
+            case 'codecall_only':
+                // In codecall_only mode, all non-codecall tools are searchable
+                // unless explicitly disabled via metadata
+                if (codecallMeta?.enabledInCodeCall === false) {
+                    return false;
+                }
+                break;
+            case 'codecall_opt_in':
+                // In opt_in mode, tools must explicitly opt-in via metadata
+                if (codecallMeta?.enabledInCodeCall !== true) {
+                    return false;
+                }
+                break;
+            case 'metadata_driven':
+                // In metadata_driven mode, default to enabled unless explicitly disabled
+                if (codecallMeta?.enabledInCodeCall === false) {
+                    return false;
+                }
+                break;
+            default:
+                // This should never happen due to constructor validation
+                // but provides defense-in-depth and satisfies exhaustive checking
+                throw new Error(`Unknown CodeCall mode: ${this.config.mode}`);
+        }
+        // Apply custom includeTools filter if provided
+        if (this.config.includeTools) {
+            const appId = this.extractAppId(tool);
+            const filterInfo = {
+                name: toolName,
+                appId,
+                source: codecallMeta?.source,
+                description: tool.metadata.description,
+                tags: codecallMeta?.tags || tool.metadata.tags,
+            };
+            if (!this.config.includeTools(filterInfo)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Extract CodeCall-specific metadata from a tool.
+     */
+    getCodeCallMetadata(tool) {
+        // NOTE: `any` cast is intentional - ToolMetadata has constrained generics
+        return tool.metadata?.codecall;
+    }
+    /**
+     * Initializes the search service by indexing all tools from the registry.
+     * NOTE: This method is now a no-op. Initialization is handled reactively
+     * via subscription to tool change events in the constructor.
+     * This method exists for interface compatibility.
+     */
+    async initialize() {
+        // Initialization is now handled reactively via subscription
+        // The subscription with immediate=true in the constructor ensures tools are indexed
+        // This method exists for interface compatibility
+    }
+    /**
+     * Cleanup subscription when service is destroyed
+     */
+    dispose() {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = undefined;
+        }
+    }
+    /**
+     * Extracts searchable text from a tool instance.
+     * Uses term weighting to improve relevance:
+     * - Description terms are heavily weighted (most important for semantic matching)
+     * - Tool name parts are tokenized and weighted
+     * - Tags provide additional context
+     */
+    extractSearchableText(tool) {
+        const parts = [];
+        // Extract and weight tool name parts
+        // Split on common delimiters (: - _ .) to get meaningful tokens
+        if (tool.name) {
+            const nameParts = tool.name.split(/[:\-_.]/).filter(Boolean);
+            // Add each part twice for moderate weighting
+            for (const part of nameParts) {
+                parts.push(part, part);
+            }
+        }
+        // Description is the most important for semantic matching
+        // Weight it heavily by repeating 3x
+        if (tool.metadata.description) {
+            const description = tool.metadata.description;
+            parts.push(description, description, description);
+            // Also extract key terms from description (words 4+ chars) for extra weight
+            const keyTerms = description
+                .toLowerCase()
+                .split(/\s+/)
+                .filter((word) => word.length >= 4 && !this.isStopWord(word));
+            parts.push(...keyTerms);
+        }
+        // Add tags with moderate weight (2x)
+        if (tool.metadata.tags && tool.metadata.tags.length > 0) {
+            for (const tag of tool.metadata.tags) {
+                parts.push(tag, tag);
+            }
+        }
+        // Add input schema property names (useful for parameter-based searches)
+        if (tool.rawInputSchema && typeof tool.rawInputSchema === 'object') {
+            const schema = tool.rawInputSchema;
+            if (schema.properties) {
+                parts.push(...Object.keys(schema.properties));
+            }
+        }
+        // Add example descriptions and input values to searchable text
+        // Examples help users find tools by use-case descriptions
+        const examples = tool.metadata?.examples;
+        if (examples && Array.isArray(examples)) {
+            for (const ex of examples) {
+                // Add example description (2x weight for relevance)
+                if (ex.description) {
+                    parts.push(ex.description, ex.description);
+                }
+                // Add example input keys and string values
+                if (ex.input && typeof ex.input === 'object') {
+                    for (const [key, value] of Object.entries(ex.input)) {
+                        parts.push(key);
+                        if (typeof value === 'string') {
+                            parts.push(value);
+                        }
+                    }
+                }
+            }
+        }
+        return parts.join(' ');
+    }
+    /**
+     * Checks if a word is a common stop word that should not receive extra weighting.
+     * Uses module-level STOP_WORDS constant to avoid recreating the Set on each call.
+     */
+    isStopWord(word) {
+        return STOP_WORDS.has(word);
+    }
+    /**
+     * Extracts app ID from tool's owner lineage
+     */
+    extractAppId(tool) {
+        if (!tool.owner)
+            return undefined;
+        // The owner structure has kind and id
+        if (tool.owner.kind === 'app') {
+            return tool.owner.id;
+        }
+        // If the tool is owned by a plugin, we need to look at its parent scope
+        // For now, we'll return undefined and rely on the lineage if needed
+        return undefined;
+    }
+    /**
+     * Searches for tools matching the query
+     * Implements the ToolSearch interface
+     */
+    async search(query, options = {}) {
+        const { topK = this.config.defaultTopK, appIds, excludeToolNames = [] } = options;
+        const minScore = this.config.defaultSimilarityThreshold;
+        // Build filter function
+        const filter = (metadata) => {
+            // Exclude tools
+            if (excludeToolNames.includes(metadata.toolName)) {
+                return false;
+            }
+            // Filter by appId if specified
+            if (appIds && appIds.length > 0) {
+                if (!metadata.appId || !appIds.includes(metadata.appId)) {
+                    return false;
+                }
+            }
+            return true;
+        };
+        // Expand query with synonyms for TF-IDF strategy to improve relevance
+        // For example: "add user" -> "add create new insert make user account member profile"
+        const effectiveQuery = this.synonymService ? this.synonymService.expandQuery(query) : query;
+        // Search using vectoriadb
+        const results = await this.vectorDB.search(effectiveQuery, {
+            topK,
+            threshold: minScore,
+            filter,
+        });
+        // Transform results to match the ToolSearch interface
+        return results.map((result) => ({
+            toolName: result.metadata.toolName,
+            appId: result.metadata.appId,
+            description: result.metadata.toolInstance.metadata.description || '',
+            relevanceScore: result.score,
+        }));
+    }
+    /**
+     * Gets all indexed tool names
+     */
+    getAllToolNames() {
+        if (this.vectorDB instanceof vectoriadb_1.VectoriaDB) {
+            return this.vectorDB.getAll().map((doc) => doc.id);
+        }
+        else {
+            return this.vectorDB.getAllDocumentIds();
+        }
+    }
+    /**
+     * Gets the total number of indexed tools
+     */
+    getTotalCount() {
+        if (this.vectorDB instanceof vectoriadb_1.VectoriaDB) {
+            return this.vectorDB.size();
+        }
+        else {
+            return this.vectorDB.getDocumentCount();
+        }
+    }
+    /**
+     * Checks if a tool exists in the index
+     */
+    hasTool(toolName) {
+        if (this.vectorDB instanceof vectoriadb_1.VectoriaDB) {
+            return this.vectorDB.has(toolName);
+        }
+        else {
+            return this.vectorDB.hasDocument(toolName);
+        }
+    }
+    /**
+     * Clears the entire index
+     */
+    clear() {
+        this.vectorDB.clear();
+        this.initialized = false;
+    }
+    /**
+     * Get the current embedding strategy
+     */
+    getStrategy() {
+        return this.strategy;
+    }
+    /**
+     * Check if the service is initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+}
+exports.ToolSearchService = ToolSearchService;
+//# sourceMappingURL=tool-search.service.js.map

package/src/codecall/services/tool-search.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-search.service.js","sourceRoot":"","sources":["../../../../src/codecall/services/tool-search.service.ts"],"names":[],"mappings":";AAAA,kEAAkE;;;AAGlE,2CAAyE;AAYzE,2EAA8F;AAE9F;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IAC9C,yBAAyB;IACzB,KAAK;IACL,GAAG;IACH,IAAI;IACJ,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IAEP,eAAe;IACf,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,MAAM;IACN,IAAI;IACJ,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,QAAQ;IACR,SAAS;IACT,OAAO;IACP,OAAO;IACP,SAAS;IACT,QAAQ;IACR,SAAS;IAET,eAAe;IACf,KAAK;IACL,IAAI;IACJ,KAAK;IACL,KAAK;IACL,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,MAAM;IACN,IAAI;IACJ,SAAS;IACT,OAAO;IACP,MAAM;IACN,OAAO;IACP,QAAQ;IAER,uCAAuC;IACvC,GAAG;IACH,IAAI;IACJ,IAAI;IACJ,MAAM;IACN,QAAQ;IACR,KAAK;IACL,MAAM;IACN,OAAO;IACP,UAAU;IACV,IAAI;IACJ,KAAK;IACL,KAAK;IACL,SAAS;IACT,KAAK;IACL,KAAK;IACL,MAAM;IACN,SAAS;IACT,IAAI;IACJ,KAAK;IACL,QAAQ;IACR,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,MAAM;IACN,WAAW;IACX,MAAM;IACN,MAAM;IACN,OAAO;IACP,QAAQ;IACR,YAAY;IACZ,KAAK;IACL,MAAM;IACN,OAAO;IACP,OAAO;IACP,MAAM;IAEN,8EAA8E;IAC9E,IAAI;IACJ,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,IAAI;IACJ,OAAO;IACP,MAAM;IACN,KAAK;IACL,KAAK;IACL,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,KAAK;IACL,OAAO,EAAE,8EAA8E;IACvF,MAAM;IACN,OAAO;IACP,OAAO;IACP,QAAQ;IACR,KAAK;IACL,OAAO;IACP,KAAK;IACL,OAAO;IACP,MAAM;IAEN,kCAAkC;IAClC,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,MAAM;IACN,IAAI;IACJ,KAAK;IACL,KAAK;IACL,MAAM;IACN,KAAK;IACL,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IAEN,wDAAwD;IACxD,QAAQ;IACR,KAAK;IACL,KAAK;IACL,QAAQ;IACR,OAAO;IACP,KAAK;IACL,OAAO;IACP,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,MAAM;IACN,KAAK;IACL,IAAI;IACJ,UAAU;IACV,WAAW;IACX,WAAW;IACX,OAAO;IACP,SAAS;IACT,KAAK;IACL,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,MAAM;IACN,MAAM,EAAE,iEAAiE;IAEzE,wBAAwB;IACxB,SAAS;IACT,SAAS;IACT,YAAY;IACZ,UAAU,EAAE,wEAAwE;IACpF,KAAK;IACL,IAAI;IACJ,IAAI;CACL,CAAC,CAAC;AAgGH;;;;GAIG;AACH,MAAa,iBAAiB;IACpB,MAAM,CAAU,wBAAwB,GAAG,GAAG,CAAC;IAC/C,QAAQ,CAAyD;IACjE,QAAQ,CAAoB;IAC5B,WAAW,GAAG,KAAK,CAAC;IACpB,aAAa,GAAG,KAAK,CAAC;IACtB,mBAAmB,GAAG,CAAC,CAAC;IACxB,MAAM,CAGZ;IACM,KAAK,CAAa;IAClB,WAAW,CAAc;IACzB,cAAc,GAAmC,IAAI,CAAC;IAE9D,YAAY,SAAkC,EAAE,EAAE,KAAiB;QACjE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,MAAM,gBAAgB,GAA6B,MAAM,CAAC,gBAAgB,IAAI;YAC5E,QAAQ,EAAE,OAAO;YACjB,SAAS,EAAE,yBAAyB;YACpC,QAAQ,EAAE,uBAAuB;YACjC,OAAO,EAAE,KAAK;YACd,gBAAgB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC,EAAE;SACrF,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC,QAAQ,IAAI,OAAO,CAAC;QAExE,IAAI,CAAC,MAAM,GAAG;YACZ,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,gBAAgB;YAChB,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,CAAC;YACpC,0BAA0B,EAAE,MAAM,CAAC,0BAA0B,IAAI,GAAG;YACpE,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,eAAe;YACpC,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC;QAEF,qCAAqC;QACrC,MAAM,UAAU,GAAG,CAAC,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,CAAU,CAAC;QACpF,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAmC,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,MAAM,CAAC,IAAI,kBAAkB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvG,CAAC;QAED,6CAA6C;QAC7C,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ,GAAG,IAAI,uBAAU,CAAe;gBAC3C,SAAS,EAAE,gBAAgB,CAAC,SAAS,IAAI,yBAAyB;gBAClE,QAAQ,EAAE,gBAAgB,CAAC,QAAQ,IAAI,uBAAuB;gBAC9D,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;gBACpC,0BAA0B,EAAE,IAAI,CAAC,MAAM,CAAC,0BAA0B;gBAClE,OAAO,EAAE,gBAAgB,CAAC,OAAO,IAAI,KAAK;aAC3C,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,GAAG,IAAI,0BAAa,CAAe;gBAC9C,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;gBACpC,0BAA0B,EAAE,IAAI,CAAC,MAAM,CAAC,0BAA0B;aACnE,CAAC,CAAC;QACL,CAAC;QAED,4FAA4F;QAC5F,IAAI,MAAM,CAAC,gBAAgB,KAAK,KAAK,EAAE,CAAC;YACtC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;aAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACrC,MAAM,aAAa,GAAG,OAAO,MAAM,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;YACjG,yCAAyC;YACzC,IAAI,aAAa,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBACpC,IAAI,CAAC,cAAc,GAAG,IAAI,mDAAuB,CAAC,aAAa,CAAC,CAAC;YACnE,CAAC;QACH,CAAC;QAED,oDAAoD;QACpD,8DAA8D;QAC9D,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACK,iBAAiB;QACvB,kEAAkE;QAClE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACtB,IAAI,IAAI,CAAC,mBAAmB,EAAE,IAAI,iBAAiB,CAAC,wBAAwB,EAAE,CAAC;gBAC7E,OAAO,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;gBAC/E,OAAO;YACT,CAAC;YACD,iEAAiE;YACjE,cAAc,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC;YAC/C,OAAO;QACT,CAAC;QACD,iCAAiC;QACjC,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;QAE7B,wEAAwE;QACxE,uFAAuF;QACvF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3E,iEAAiE;YACjE,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAA4C,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,gBAAgB,CAAC,KAA4B;QACzD,0BAA0B;QAC1B,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QAEtB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,OAAO;QACT,CAAC;QAED,+EAA+E;QAC/E,gFAAgF;QAChF,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,YAAY,uBAAU,EAAE,CAAC;YACzF,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;YACjC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC5B,CAAC;QAED,8DAA8D;QAC9D,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QAEzE,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YAC3C,MAAM,cAAc,GAAG,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;YACxD,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;YAC3B,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC;YAEhD,OAAO;gBACL,EAAE,EAAE,QAAQ;gBACZ,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE;oBACR,EAAE,EAAE,QAAQ;oBACZ,QAAQ;oBACR,aAAa;oBACb,KAAK;oBACL,YAAY,EAAE,IAAI;iBACnB;aACF,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,YAAY,uBAAU,EAAE,CAAC;YAClE,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,IAAI,CAAC,QAAQ,YAAY,0BAAa,EAAE,CAAC;YAClD,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;YACtC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACK,eAAe,CAAC,IAAyB;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC;QAE5C,iFAAiF;QACjF,IAAI,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,+CAA+C;QAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAEpD,6BAA6B;QAC7B,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACzB,KAAK,eAAe;gBAClB,+DAA+D;gBAC/D,0CAA0C;gBAC1C,IAAI,YAAY,EAAE,iBAAiB,KAAK,KAAK,EAAE,CAAC;oBAC9C,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,MAAM;YAER,KAAK,iBAAiB;gBACpB,4DAA4D;gBAC5D,IAAI,YAAY,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;oBAC7C,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,MAAM;YAER,KAAK,iBAAiB;gBACpB,yEAAyE;gBACzE,IAAI,YAAY,EAAE,iBAAiB,KAAK,KAAK,EAAE,CAAC;oBAC9C,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,MAAM;YAER;gBACE,yDAAyD;gBACzD,kEAAkE;gBAClE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QAED,+CAA+C;QAC/C,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YACtC,MAAM,UAAU,GAAG;gBACjB,IAAI,EAAE,QAAQ;gBACd,KAAK;gBACL,MAAM,EAAE,YAAY,EAAE,MAAM;gBAC5B,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW;gBACtC,IAAI,EAAE,YAAY,EAAE,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI;aAC/C,CAAC;YAEF,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC1C,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACK,mBAAmB,CAAC,IAAyB;QACnD,0EAA0E;QAC1E,OAAQ,IAAI,CAAC,QAAgB,EAAE,QAA4C,CAAC;IAC9E,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU;QACd,4DAA4D;QAC5D,oFAAoF;QACpF,iDAAiD;IACnD,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACK,qBAAqB,CAAC,IAAyB;QACrD,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,qCAAqC;QACrC,gEAAgE;QAChE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7D,6CAA6C;YAC7C,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,0DAA0D;QAC1D,oCAAoC;QACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;YAC9C,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;YAElD,4EAA4E;YAC5E,MAAM,QAAQ,GAAG,WAAW;iBACzB,WAAW,EAAE;iBACb,KAAK,CAAC,KAAK,CAAC;iBACZ,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;YAChE,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC1B,CAAC;QAED,qCAAqC;QACrC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAED,wEAAwE;QACxE,IAAI,IAAI,CAAC,cAAc,IAAI,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;YACnE,MAAM,MAAM,GAAG,IAAI,CAAC,cAAqB,CAAC;YAC1C,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QAED,+DAA+D;QAC/D,0DAA0D;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC;QACzC,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC1B,oDAAoD;gBACpD,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;oBACnB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC;gBAC7C,CAAC;gBACD,2CAA2C;gBAC3C,IAAI,EAAE,CAAC,KAAK,IAAI,OAAO,EAAE,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,KAAgC,CAAC,EAAE,CAAC;wBAC/E,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;wBAChB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;4BAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;wBACpB,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;;OAGG;IACK,UAAU,CAAC,IAAY;QAC7B,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,IAAyB;QAC5C,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAElC,sCAAsC;QACtC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,CAAC;QAED,wEAAwE;QACxE,oEAAoE;QACpE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,UAAmC,EAAE;QAC/D,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,gBAAgB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;QAClF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,0BAA0B,CAAC;QAExD,wBAAwB;QACxB,MAAM,MAAM,GAAG,CAAC,QAAsB,EAAW,EAAE;YACjD,gBAAgB;YAChB,IAAI,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACjD,OAAO,KAAK,CAAC;YACf,CAAC;YAED,+BAA+B;YAC/B,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;oBACxD,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;QAEF,sEAAsE;QACtE,sFAAsF;QACtF,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAE5F,0BAA0B;QAC1B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE;YACzD,IAAI;YACJ,SAAS,EAAE,QAAQ;YACnB,MAAM;SACP,CAAC,CAAC;QAEH,sDAAsD;QACtD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC9B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ;YAClC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK;YAC5B,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,IAAI,EAAE;YACpE,cAAc,EAAE,MAAM,CAAC,KAAK;SAC7B,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;OAEG;IACH,eAAe;QACb,IAAI,IAAI,CAAC,QAAQ,YAAY,uBAAU,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,aAAa;QACX,IAAI,IAAI,CAAC,QAAQ,YAAY,uBAAU,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC;QAC1C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,QAAgB;QACtB,IAAI,IAAI,CAAC,QAAQ,YAAY,uBAAU,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;;AAhcH,8CAicC","sourcesContent":["// file: libs/plugins/src/codecall/services/tool-search.service.ts\n\nimport { ToolEntry, ScopeEntry } from '@frontmcp/sdk';\nimport { TFIDFVectoria, VectoriaDB, DocumentMetadata } from 'vectoriadb';\nimport type {\n  EmbeddingStrategy,\n  CodeCallEmbeddingOptions,\n  CodeCallMode,\n  CodeCallToolMetadata,\n} from '../codecall.types';\nimport type {\n  ToolSearch,\n  ToolSearchResult as SymbolToolSearchResult,\n  ToolSearchOptions as SymbolToolSearchOptions,\n} from '../codecall.symbol';\nimport { SynonymExpansionService, SynonymExpansionConfig } from './synonym-expansion.service';\n\n/**\n * Universal Intent Mapping & Query Normalization\n * - This module defines the semantic knowledge base for the MCP tool search engine.\n *   It is designed to bridge the gap between natural language user intents\n *   (e.g., \"fix,\" \"chat,\" \"buy\") and technical tool definitions (e.g., \"update,\" \"post,\" \"create\").\n * - Key Parts:\n *   1. DEFAULT_SYNONYM_GROUPS: A domain-agnostic mapping of bidirectional synonyms covering\n *      CRUD, DevOps, Financial, Social, and Lifecycle operations. This ensures that a\n *      query for \"Show me the bill\" matches a tool named \"get_invoice\".\n *   2. STOP_WORDS: A curated exclusion list strictly optimized for Command-Line/Chat\n *      interfaces. Unlike standard NLP stop lists, this PRESERVES action verbs\n *      (\"find\", \"start\", \"make\") as they are critical signals of user intent in a\n *      tool-execution context.\n */\nconst STOP_WORDS: ReadonlySet<string> = new Set([\n  // Articles & Determiners\n  'the',\n  'a',\n  'an',\n  'this',\n  'that',\n  'these',\n  'those',\n\n  // Prepositions\n  'in',\n  'on',\n  'at',\n  'to',\n  'for',\n  'of',\n  'with',\n  'by',\n  'from',\n  'into',\n  'over',\n  'after',\n  'before',\n  'between',\n  'under',\n  'about',\n  'against',\n  'during',\n  'through',\n\n  // Conjunctions\n  'and',\n  'or',\n  'but',\n  'nor',\n  'so',\n  'yet',\n  'as',\n  'than',\n  'if',\n  'because',\n  'while',\n  'when',\n  'where',\n  'unless',\n\n  // Pronouns (Subject/Object/Possessive)\n  'i',\n  'me',\n  'my',\n  'mine',\n  'myself',\n  'you',\n  'your',\n  'yours',\n  'yourself',\n  'he',\n  'him',\n  'his',\n  'himself',\n  'she',\n  'her',\n  'hers',\n  'herself',\n  'it',\n  'its',\n  'itself',\n  'we',\n  'us',\n  'our',\n  'ours',\n  'ourselves',\n  'they',\n  'them',\n  'their',\n  'theirs',\n  'themselves',\n  'who',\n  'whom',\n  'whose',\n  'which',\n  'what',\n\n  // Auxiliary/Linking Verbs (State of being is usually noise, Action is signal)\n  'is',\n  'was',\n  'are',\n  'were',\n  'been',\n  'be',\n  'being',\n  'have',\n  'has',\n  'had',\n  'having',\n  'do',\n  'does',\n  'did',\n  'doing', // \"do\" is usually auxiliary (\"do you have...\"). \"run\" or \"execute\" is better.\n  'will',\n  'would',\n  'shall',\n  'should',\n  'can',\n  'could',\n  'may',\n  'might',\n  'must',\n\n  // Quantifiers / Adverbs of degree\n  'all',\n  'any',\n  'both',\n  'each',\n  'few',\n  'more',\n  'most',\n  'other',\n  'some',\n  'such',\n  'no',\n  'nor',\n  'not',\n  'only',\n  'own',\n  'same',\n  'too',\n  'very',\n  'just',\n  'even',\n\n  // Conversational / Chat Fillers (Common in LLM prompts)\n  'please',\n  'pls',\n  'plz',\n  'thanks',\n  'thank',\n  'thx',\n  'hello',\n  'hi',\n  'hey',\n  'ok',\n  'okay',\n  'yes',\n  'no',\n  'actually',\n  'basically',\n  'literally',\n  'maybe',\n  'perhaps',\n  'now',\n  'then',\n  'here',\n  'there',\n  'again',\n  'once',\n  'back', // \"back\" can be tricky, but usually implies direction not action\n\n  // Meta/Structural words\n  'example',\n  'context',\n  'optionally',\n  'optional', // Users rarely search for \"optional\", they search for the thing itself.\n  'etc',\n  'ie',\n  'eg',\n]);\n/**\n * Metadata structure for tool documents in the vector database\n */\n// NOTE: `any` is intentional - ToolEntry has constrained generics that don't work with `unknown`\ninterface ToolMetadata extends DocumentMetadata {\n  id: string;\n  toolName: string;\n  qualifiedName: string;\n  appId?: string;\n  toolInstance: ToolEntry<any, any>;\n}\n\n/**\n * Search result for tool search\n */\n// NOTE: `any` is intentional - ToolEntry has constrained generics that don't work with `unknown`\nexport interface SearchResult {\n  tool: ToolEntry<any, any>;\n  score: number;\n  toolName: string;\n  qualifiedName: string;\n  appId?: string;\n}\n\n/**\n * Search options for tool search\n */\nexport interface SearchOptions {\n  topK?: number;\n  appIds?: string[];\n  excludeToolNames?: string[];\n  minScore?: number;\n}\n\n/**\n * Filter function type for including tools\n */\nexport type IncludeToolsFilter = (info: {\n  name: string;\n  appId?: string;\n  source?: string;\n  description?: string;\n  tags?: string[];\n}) => boolean;\n\n/**\n * Configuration for tool search service\n */\nexport interface ToolSearchServiceConfig {\n  /**\n   * Embedding strategy to use\n   * @default 'tfidf'\n   */\n  strategy?: EmbeddingStrategy;\n\n  /**\n   * Full embedding options (alternative to just strategy)\n   */\n  embeddingOptions?: CodeCallEmbeddingOptions;\n\n  /**\n   * Default number of results to return\n   * @default 8\n   */\n  defaultTopK?: number;\n\n  /**\n   * Default similarity threshold\n   * @default 0.0\n   */\n  defaultSimilarityThreshold?: number;\n\n  /**\n   * CodeCall mode for filtering tools\n   * @default 'codecall_only'\n   */\n  mode?: CodeCallMode;\n\n  /**\n   * Optional filter function for including tools in the search index\n   */\n  includeTools?: IncludeToolsFilter;\n\n  /**\n   * Synonym expansion configuration.\n   * When enabled, queries are expanded with synonyms to improve search relevance.\n   * For example, \"add user\" will also match tools containing \"create user\".\n   * Only applies when strategy is 'tfidf' (ML already handles semantic similarity).\n   *\n   * Set to false to disable, or provide a config object to customize.\n   * @default { enabled: true } when strategy is 'tfidf'\n   */\n  synonymExpansion?: false | (SynonymExpansionConfig & { enabled?: boolean });\n}\n\n/**\n * Service that maintains a searchable index of tools from the ToolRegistry\n * Supports both TF-IDF (lightweight, synchronous) and ML-based (semantic) embeddings\n * Implements the ToolSearch interface for dependency injection\n */\nexport class ToolSearchService implements ToolSearch {\n  private static readonly MAX_SUBSCRIPTION_RETRIES = 100;\n  private vectorDB: TFIDFVectoria<ToolMetadata> | VectoriaDB<ToolMetadata>;\n  private strategy: EmbeddingStrategy;\n  private initialized = false;\n  private mlInitialized = false;\n  private subscriptionRetries = 0;\n  private config: Required<Omit<ToolSearchServiceConfig, 'includeTools' | 'mode' | 'synonymExpansion'>> & {\n    mode: CodeCallMode;\n    includeTools?: IncludeToolsFilter;\n  };\n  private scope: ScopeEntry;\n  private unsubscribe?: () => void;\n  private synonymService: SynonymExpansionService | null = null;\n\n  constructor(config: ToolSearchServiceConfig = {}, scope: ScopeEntry) {\n    this.scope = scope;\n    const embeddingOptions: CodeCallEmbeddingOptions = config.embeddingOptions || {\n      strategy: 'tfidf',\n      modelName: 'Xenova/all-MiniLM-L6-v2',\n      cacheDir: './.cache/transformers',\n      useHNSW: false,\n      synonymExpansion: { enabled: true, replaceDefaults: false, maxExpansionsPerTerm: 5 },\n    };\n    this.strategy = config.strategy || embeddingOptions.strategy || 'tfidf';\n\n    this.config = {\n      strategy: this.strategy,\n      embeddingOptions,\n      defaultTopK: config.defaultTopK ?? 8,\n      defaultSimilarityThreshold: config.defaultSimilarityThreshold ?? 0.0,\n      mode: config.mode ?? 'codecall_only',\n      includeTools: config.includeTools,\n    };\n\n    // Validate mode parameter at runtime\n    const validModes = ['codecall_only', 'codecall_opt_in', 'metadata_driven'] as const;\n    if (!validModes.includes(this.config.mode as (typeof validModes)[number])) {\n      throw new Error(`Invalid CodeCall mode: ${this.config.mode}. Valid modes: ${validModes.join(', ')}`);\n    }\n\n    // Initialize the appropriate vector database\n    if (this.strategy === 'ml') {\n      this.vectorDB = new VectoriaDB<ToolMetadata>({\n        modelName: embeddingOptions.modelName || 'Xenova/all-MiniLM-L6-v2',\n        cacheDir: embeddingOptions.cacheDir || './.cache/transformers',\n        defaultTopK: this.config.defaultTopK,\n        defaultSimilarityThreshold: this.config.defaultSimilarityThreshold,\n        useHNSW: embeddingOptions.useHNSW || false,\n      });\n    } else {\n      this.vectorDB = new TFIDFVectoria<ToolMetadata>({\n        defaultTopK: this.config.defaultTopK,\n        defaultSimilarityThreshold: this.config.defaultSimilarityThreshold,\n      });\n    }\n\n    // Initialize synonym expansion for TF-IDF strategy (ML already handles semantic similarity)\n    if (config.synonymExpansion === false) {\n      this.synonymService = null;\n    } else if (this.strategy === 'tfidf') {\n      const synonymConfig = typeof config.synonymExpansion === 'object' ? config.synonymExpansion : {};\n      // Only enable if not explicitly disabled\n      if (synonymConfig.enabled !== false) {\n        this.synonymService = new SynonymExpansionService(synonymConfig);\n      }\n    }\n\n    // Defer subscription until scope.tools is available\n    // During plugin initialization, scope.tools may not exist yet\n    this.setupSubscription();\n  }\n\n  /**\n   * Sets up subscription to tool changes. Handles the case where scope.tools\n   * may not be available yet during plugin initialization.\n   */\n  private setupSubscription(): void {\n    // If tools registry is not yet available, retry after a microtask\n    if (!this.scope.tools) {\n      if (this.subscriptionRetries++ >= ToolSearchService.MAX_SUBSCRIPTION_RETRIES) {\n        console.warn('ToolSearchService: scope.tools not available after max retries');\n        return;\n      }\n      // Use queueMicrotask to defer until after current initialization\n      queueMicrotask(() => this.setupSubscription());\n      return;\n    }\n    // Reset retry counter on success\n    this.subscriptionRetries = 0;\n\n    // Subscribe to tool changes with immediate=true to get current snapshot\n    // This ensures tools are indexed as they become available, regardless of loading order\n    this.unsubscribe = this.scope.tools.subscribe({ immediate: true }, (event) => {\n      // Handle tool change event - reindex all tools from the snapshot\n      this.handleToolChange(event.snapshot as unknown as ToolEntry<any, any>[]);\n    });\n  }\n\n  /**\n   * Handles tool change events by reindexing all tools from the snapshot\n   */\n  private async handleToolChange(tools: ToolEntry<any, any>[]): Promise<void> {\n    // Clear and rebuild index\n    this.vectorDB.clear();\n\n    if (tools.length === 0) {\n      this.initialized = true;\n      return;\n    }\n\n    // Initialize ML model if needed (first time only, and only when we have tools)\n    // Deferred initialization avoids async operations when there's nothing to index\n    if (!this.mlInitialized && this.strategy === 'ml' && this.vectorDB instanceof VectoriaDB) {\n      await this.vectorDB.initialize();\n      this.mlInitialized = true;\n    }\n\n    // Filter tools based on CodeCall config and per-tool metadata\n    const filteredTools = tools.filter((tool) => this.shouldIndexTool(tool));\n\n    if (filteredTools.length === 0) {\n      this.initialized = true;\n      return;\n    }\n\n    const documents = filteredTools.map((tool) => {\n      const searchableText = this.extractSearchableText(tool);\n      const appId = this.extractAppId(tool);\n      const toolName = tool.name;\n      const qualifiedName = tool.fullName || toolName;\n\n      return {\n        id: toolName,\n        text: searchableText,\n        metadata: {\n          id: toolName,\n          toolName,\n          qualifiedName,\n          appId,\n          toolInstance: tool,\n        },\n      };\n    });\n\n    if (this.strategy === 'ml' && this.vectorDB instanceof VectoriaDB) {\n      await this.vectorDB.addMany(documents);\n    } else if (this.vectorDB instanceof TFIDFVectoria) {\n      this.vectorDB.addDocuments(documents);\n      this.vectorDB.reindex();\n    }\n\n    this.initialized = true;\n  }\n\n  /**\n   * Determines if a tool should be indexed in the search database.\n   * Filters based on:\n   * - Excludes codecall:* meta-tools (they should not be searchable)\n   * - Mode-based filtering (codecall_only, codecall_opt_in, metadata_driven)\n   * - Per-tool metadata.codecall.enabledInCodeCall\n   * - Custom includeTools filter function\n   */\n  private shouldIndexTool(tool: ToolEntry<any, any>): boolean {\n    const toolName = tool.name || tool.fullName;\n\n    // Never index codecall:* meta-tools - they are for orchestration, not for search\n    if (toolName.startsWith('codecall:')) {\n      return false;\n    }\n\n    // Get CodeCall-specific metadata from the tool\n    const codecallMeta = this.getCodeCallMetadata(tool);\n\n    // Apply mode-based filtering\n    switch (this.config.mode) {\n      case 'codecall_only':\n        // In codecall_only mode, all non-codecall tools are searchable\n        // unless explicitly disabled via metadata\n        if (codecallMeta?.enabledInCodeCall === false) {\n          return false;\n        }\n        break;\n\n      case 'codecall_opt_in':\n        // In opt_in mode, tools must explicitly opt-in via metadata\n        if (codecallMeta?.enabledInCodeCall !== true) {\n          return false;\n        }\n        break;\n\n      case 'metadata_driven':\n        // In metadata_driven mode, default to enabled unless explicitly disabled\n        if (codecallMeta?.enabledInCodeCall === false) {\n          return false;\n        }\n        break;\n\n      default:\n        // This should never happen due to constructor validation\n        // but provides defense-in-depth and satisfies exhaustive checking\n        throw new Error(`Unknown CodeCall mode: ${this.config.mode}`);\n    }\n\n    // Apply custom includeTools filter if provided\n    if (this.config.includeTools) {\n      const appId = this.extractAppId(tool);\n      const filterInfo = {\n        name: toolName,\n        appId,\n        source: codecallMeta?.source,\n        description: tool.metadata.description,\n        tags: codecallMeta?.tags || tool.metadata.tags,\n      };\n\n      if (!this.config.includeTools(filterInfo)) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n\n  /**\n   * Extract CodeCall-specific metadata from a tool.\n   */\n  private getCodeCallMetadata(tool: ToolEntry<any, any>): CodeCallToolMetadata | undefined {\n    // NOTE: `any` cast is intentional - ToolMetadata has constrained generics\n    return (tool.metadata as any)?.codecall as CodeCallToolMetadata | undefined;\n  }\n\n  /**\n   * Initializes the search service by indexing all tools from the registry.\n   * NOTE: This method is now a no-op. Initialization is handled reactively\n   * via subscription to tool change events in the constructor.\n   * This method exists for interface compatibility.\n   */\n  async initialize(): Promise<void> {\n    // Initialization is now handled reactively via subscription\n    // The subscription with immediate=true in the constructor ensures tools are indexed\n    // This method exists for interface compatibility\n  }\n\n  /**\n   * Cleanup subscription when service is destroyed\n   */\n  dispose(): void {\n    if (this.unsubscribe) {\n      this.unsubscribe();\n      this.unsubscribe = undefined;\n    }\n  }\n\n  /**\n   * Extracts searchable text from a tool instance.\n   * Uses term weighting to improve relevance:\n   * - Description terms are heavily weighted (most important for semantic matching)\n   * - Tool name parts are tokenized and weighted\n   * - Tags provide additional context\n   */\n  private extractSearchableText(tool: ToolEntry<any, any>): string {\n    const parts: string[] = [];\n\n    // Extract and weight tool name parts\n    // Split on common delimiters (: - _ .) to get meaningful tokens\n    if (tool.name) {\n      const nameParts = tool.name.split(/[:\\-_.]/).filter(Boolean);\n      // Add each part twice for moderate weighting\n      for (const part of nameParts) {\n        parts.push(part, part);\n      }\n    }\n\n    // Description is the most important for semantic matching\n    // Weight it heavily by repeating 3x\n    if (tool.metadata.description) {\n      const description = tool.metadata.description;\n      parts.push(description, description, description);\n\n      // Also extract key terms from description (words 4+ chars) for extra weight\n      const keyTerms = description\n        .toLowerCase()\n        .split(/\\s+/)\n        .filter((word) => word.length >= 4 && !this.isStopWord(word));\n      parts.push(...keyTerms);\n    }\n\n    // Add tags with moderate weight (2x)\n    if (tool.metadata.tags && tool.metadata.tags.length > 0) {\n      for (const tag of tool.metadata.tags) {\n        parts.push(tag, tag);\n      }\n    }\n\n    // Add input schema property names (useful for parameter-based searches)\n    if (tool.rawInputSchema && typeof tool.rawInputSchema === 'object') {\n      const schema = tool.rawInputSchema as any;\n      if (schema.properties) {\n        parts.push(...Object.keys(schema.properties));\n      }\n    }\n\n    // Add example descriptions and input values to searchable text\n    // Examples help users find tools by use-case descriptions\n    const examples = tool.metadata?.examples;\n    if (examples && Array.isArray(examples)) {\n      for (const ex of examples) {\n        // Add example description (2x weight for relevance)\n        if (ex.description) {\n          parts.push(ex.description, ex.description);\n        }\n        // Add example input keys and string values\n        if (ex.input && typeof ex.input === 'object') {\n          for (const [key, value] of Object.entries(ex.input as Record<string, unknown>)) {\n            parts.push(key);\n            if (typeof value === 'string') {\n              parts.push(value);\n            }\n          }\n        }\n      }\n    }\n\n    return parts.join(' ');\n  }\n\n  /**\n   * Checks if a word is a common stop word that should not receive extra weighting.\n   * Uses module-level STOP_WORDS constant to avoid recreating the Set on each call.\n   */\n  private isStopWord(word: string): boolean {\n    return STOP_WORDS.has(word);\n  }\n\n  /**\n   * Extracts app ID from tool's owner lineage\n   */\n  private extractAppId(tool: ToolEntry<any, any>): string | undefined {\n    if (!tool.owner) return undefined;\n\n    // The owner structure has kind and id\n    if (tool.owner.kind === 'app') {\n      return tool.owner.id;\n    }\n\n    // If the tool is owned by a plugin, we need to look at its parent scope\n    // For now, we'll return undefined and rely on the lineage if needed\n    return undefined;\n  }\n\n  /**\n   * Searches for tools matching the query\n   * Implements the ToolSearch interface\n   */\n  async search(query: string, options: SymbolToolSearchOptions = {}): Promise<SymbolToolSearchResult[]> {\n    const { topK = this.config.defaultTopK, appIds, excludeToolNames = [] } = options;\n    const minScore = this.config.defaultSimilarityThreshold;\n\n    // Build filter function\n    const filter = (metadata: ToolMetadata): boolean => {\n      // Exclude tools\n      if (excludeToolNames.includes(metadata.toolName)) {\n        return false;\n      }\n\n      // Filter by appId if specified\n      if (appIds && appIds.length > 0) {\n        if (!metadata.appId || !appIds.includes(metadata.appId)) {\n          return false;\n        }\n      }\n\n      return true;\n    };\n\n    // Expand query with synonyms for TF-IDF strategy to improve relevance\n    // For example: \"add user\" -> \"add create new insert make user account member profile\"\n    const effectiveQuery = this.synonymService ? this.synonymService.expandQuery(query) : query;\n\n    // Search using vectoriadb\n    const results = await this.vectorDB.search(effectiveQuery, {\n      topK,\n      threshold: minScore,\n      filter,\n    });\n\n    // Transform results to match the ToolSearch interface\n    return results.map((result) => ({\n      toolName: result.metadata.toolName,\n      appId: result.metadata.appId,\n      description: result.metadata.toolInstance.metadata.description || '',\n      relevanceScore: result.score,\n    }));\n  }\n\n  /**\n   * Gets all indexed tool names\n   */\n  getAllToolNames(): string[] {\n    if (this.vectorDB instanceof VectoriaDB) {\n      return this.vectorDB.getAll().map((doc) => doc.id);\n    } else {\n      return this.vectorDB.getAllDocumentIds();\n    }\n  }\n\n  /**\n   * Gets the total number of indexed tools\n   */\n  getTotalCount(): number {\n    if (this.vectorDB instanceof VectoriaDB) {\n      return this.vectorDB.size();\n    } else {\n      return this.vectorDB.getDocumentCount();\n    }\n  }\n\n  /**\n   * Checks if a tool exists in the index\n   */\n  hasTool(toolName: string): boolean {\n    if (this.vectorDB instanceof VectoriaDB) {\n      return this.vectorDB.has(toolName);\n    } else {\n      return this.vectorDB.hasDocument(toolName);\n    }\n  }\n\n  /**\n   * Clears the entire index\n   */\n  clear(): void {\n    this.vectorDB.clear();\n    this.initialized = false;\n  }\n\n  /**\n   * Get the current embedding strategy\n   */\n  getStrategy(): EmbeddingStrategy {\n    return this.strategy;\n  }\n\n  /**\n   * Check if the service is initialized\n   */\n  isInitialized(): boolean {\n    return this.initialized;\n  }\n}\n"]}