@librechat/agents 3.3.4 → 3.3.6

package/dist/esm/tools/ToolSearch.mjs

@@ -1,5 +1,6 @@
 import "../common/enum.mjs";
 import "../common/index.mjs";
+import { INTENT_PROPERTY } from "./intentArg.mjs";
 import { getCodeBaseURL } from "./CodeExecutor.mjs";
 import { tool } from "@langchain/core/tools";
 import { config } from "dotenv";
@@ -29,6 +30,7 @@ const MCP_SERVER_DESCRIPTION = "Filter to tools from specific MCP server(s). Can
 const ToolSearchToolSchema = {
 	type: "object",
 	properties: {
+		intent: { ...INTENT_PROPERTY },
 		query: {
 			type: "string",
 			maxLength: MAX_PATTERN_LENGTH,
@@ -80,14 +82,16 @@ const SEARCH_TIMEOUT = 5e3;
 * @returns JSON schema for tool search parameters
 */
 function createToolSearchSchema(mode) {
+	const queryDescription = mode === "local" ? QUERY_DESCRIPTION_LOCAL : QUERY_DESCRIPTION_REGEX;
 	return {
 		type: "object",
 		properties: {
+			intent: { ...INTENT_PROPERTY },
 			query: {
 				type: "string",
 				maxLength: MAX_PATTERN_LENGTH,
 				default: "",
-				description: mode === "local" ? QUERY_DESCRIPTION_LOCAL : QUERY_DESCRIPTION_REGEX
+				description: queryDescription
 			},
 			fields: {
 				type: "array",

package/dist/esm/tools/ToolSearch.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ToolSearch.mjs","names":["params"],"sources":["../../../src/tools/ToolSearch.ts"],"sourcesContent":["// src/tools/ToolSearch.ts\nimport { config } from 'dotenv';\nimport * as okapibm25Module from 'okapibm25';\n\ntype BM25Fn = (\n  documents: string[],\n  keywords: string[],\n  constants?: { k1?: number; b?: number }\n) => number[];\n\nfunction getBM25Function(): BM25Fn {\n  const mod = okapibm25Module as unknown as {\n    default: BM25Fn | { default: BM25Fn } | undefined;\n  };\n  if (typeof mod === 'function') return mod;\n  if (typeof mod.default === 'function') return mod.default;\n  if (mod.default != null && typeof mod.default.default === 'function')\n    return mod.default.default;\n  throw new Error('Could not resolve BM25 function from okapibm25 module');\n}\n\nconst BM25 = getBM25Function();\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type * as t from '@/types';\nimport { getCodeBaseURL } from './CodeExecutor';\nimport { Constants } from '@/common';\n\nconfig();\n\n/** Maximum allowed regex pattern length */\nconst MAX_PATTERN_LENGTH = 200;\n\nexport const ToolSearchToolName = Constants.TOOL_SEARCH;\n\nexport const ToolSearchToolDescription =\n  'Searches deferred tools using BM25 ranking. Multi-word queries supported. Use mcp_server param to filter by server.';\n\nconst QUERY_DESCRIPTION_LOCAL =\n  'Search term to find in tool names and descriptions. Case-insensitive substring matching. Optional if mcp_server is provided.';\nconst QUERY_DESCRIPTION_REGEX =\n  'Regex pattern to search tool names and descriptions. Optional if mcp_server is provided.';\nconst FIELDS_DESCRIPTION =\n  'Which fields to search. Default: name and description';\nconst MAX_RESULTS_DESCRIPTION = 'Maximum number of matching tools to return';\nconst DEFAULT_MAX_RESULTS = 5;\nconst MCP_SERVER_DESCRIPTION =\n  'Filter to tools from specific MCP server(s). Can be a single server name or array of names. If provided without a query, lists all tools from those servers.';\n\nexport const ToolSearchToolSchema = {\n  type: 'object',\n  properties: {\n    query: {\n      type: 'string',\n      maxLength: MAX_PATTERN_LENGTH,\n      default: '',\n      description: QUERY_DESCRIPTION_LOCAL,\n    },\n    fields: {\n      type: 'array',\n      items: { type: 'string', enum: ['name', 'description', 'parameters'] },\n      default: ['name', 'description'],\n      description: FIELDS_DESCRIPTION,\n    },\n    max_results: {\n      type: 'integer',\n      minimum: 1,\n      maximum: 50,\n      default: DEFAULT_MAX_RESULTS,\n      description: MAX_RESULTS_DESCRIPTION,\n    },\n    mcp_server: {\n      oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],\n      description: MCP_SERVER_DESCRIPTION,\n    },\n  },\n  required: [],\n} as const;\n\nexport const ToolSearchToolDefinition = {\n  name: ToolSearchToolName,\n  description: ToolSearchToolDescription,\n  schema: ToolSearchToolSchema,\n} as const;\n\n/** Maximum allowed regex nesting depth */\nconst MAX_REGEX_COMPLEXITY = 5;\n\n/** Default search timeout in milliseconds */\nconst SEARCH_TIMEOUT = 5000;\n\n/** JSON schema type for tool search parameters */\ninterface ToolSearchSchema {\n  type: 'object';\n  properties: Record<string, unknown>;\n  required: string[];\n}\n\n/** Input params type for tool search */\ninterface ToolSearchParams {\n  query?: string;\n  fields?: ('name' | 'description' | 'parameters')[];\n  max_results?: number;\n  mcp_server?: string | string[];\n}\n\n/**\n * Creates the JSON schema with dynamic query description based on mode.\n * @param mode - The search mode determining query interpretation\n * @returns JSON schema for tool search parameters\n */\nfunction createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema {\n  const queryDescription =\n    mode === 'local' ? QUERY_DESCRIPTION_LOCAL : QUERY_DESCRIPTION_REGEX;\n\n  return {\n    type: 'object',\n    properties: {\n      query: {\n        type: 'string',\n        maxLength: MAX_PATTERN_LENGTH,\n        default: '',\n        description: queryDescription,\n      },\n      fields: {\n        type: 'array',\n        items: { type: 'string', enum: ['name', 'description', 'parameters'] },\n        default: ['name', 'description'],\n        description: FIELDS_DESCRIPTION,\n      },\n      max_results: {\n        type: 'integer',\n        minimum: 1,\n        maximum: 50,\n        default: DEFAULT_MAX_RESULTS,\n        description: MAX_RESULTS_DESCRIPTION,\n      },\n      mcp_server: {\n        oneOf: [\n          { type: 'string' },\n          { type: 'array', items: { type: 'string' } },\n        ],\n        description: MCP_SERVER_DESCRIPTION,\n      },\n    },\n    required: [],\n  };\n}\n\n/**\n * Extracts the MCP server name from a tool name.\n * MCP tools follow the pattern: toolName_mcp_serverName\n * @param toolName - The full tool name\n * @returns The server name if it's an MCP tool, undefined otherwise\n */\nfunction extractMcpServerName(toolName: string): string | undefined {\n  const delimiterIndex = toolName.indexOf(Constants.MCP_DELIMITER);\n  if (delimiterIndex === -1) {\n    return undefined;\n  }\n  return toolName.substring(delimiterIndex + Constants.MCP_DELIMITER.length);\n}\n\n/**\n * Checks if a tool belongs to a specific MCP server.\n * @param toolName - The full tool name\n * @param serverName - The server name to match\n * @returns True if the tool belongs to the specified server\n */\nfunction isFromMcpServer(toolName: string, serverName: string): boolean {\n  const toolServer = extractMcpServerName(toolName);\n  return toolServer === serverName;\n}\n\n/**\n * Checks if a tool belongs to any of the specified MCP servers.\n * @param toolName - The full tool name\n * @param serverNames - Array of server names to match\n * @returns True if the tool belongs to any of the specified servers\n */\nfunction isFromAnyMcpServer(toolName: string, serverNames: string[]): boolean {\n  const toolServer = extractMcpServerName(toolName);\n  if (toolServer === undefined) {\n    return false;\n  }\n  return serverNames.includes(toolServer);\n}\n\n/**\n * Normalizes server filter input to always be an array.\n * @param serverFilter - String, array of strings, or undefined\n * @returns Array of server names (empty if none specified)\n */\nfunction normalizeServerFilter(\n  serverFilter: string | string[] | undefined\n): string[] {\n  if (serverFilter === undefined) {\n    return [];\n  }\n  if (typeof serverFilter === 'string') {\n    return serverFilter === '' ? [] : [serverFilter];\n  }\n  return serverFilter.filter((s) => s !== '');\n}\n\n/**\n * Extracts all unique MCP server names from a tool registry.\n * @param toolRegistry - The tool registry to scan\n * @param onlyDeferred - If true, only considers deferred tools\n * @returns Array of unique server names, sorted alphabetically\n */\nfunction getAvailableMcpServers(\n  toolRegistry: t.LCToolRegistry | undefined,\n  onlyDeferred: boolean = true\n): string[] {\n  if (!toolRegistry) {\n    return [];\n  }\n\n  const servers = new Set<string>();\n  for (const [, toolDef] of toolRegistry) {\n    if (onlyDeferred && toolDef.defer_loading !== true) {\n      continue;\n    }\n    const server = extractMcpServerName(toolDef.name);\n    if (server !== undefined && server !== '') {\n      servers.add(server);\n    }\n  }\n\n  return Array.from(servers).sort();\n}\n\n/**\n * Escapes special regex characters in a string to use as a literal pattern.\n * @param pattern - The string to escape\n * @returns The escaped string safe for use in a RegExp\n */\nfunction escapeRegexSpecialChars(pattern: string): string {\n  return pattern.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * Counts the maximum nesting depth of groups in a regex pattern.\n * @param pattern - The regex pattern to analyze\n * @returns The maximum nesting depth\n */\nfunction countNestedGroups(pattern: string): number {\n  let maxDepth = 0;\n  let currentDepth = 0;\n\n  for (let i = 0; i < pattern.length; i++) {\n    if (pattern[i] === '(' && (i === 0 || pattern[i - 1] !== '\\\\')) {\n      currentDepth++;\n      maxDepth = Math.max(maxDepth, currentDepth);\n    } else if (pattern[i] === ')' && (i === 0 || pattern[i - 1] !== '\\\\')) {\n      currentDepth = Math.max(0, currentDepth - 1);\n    }\n  }\n\n  return maxDepth;\n}\n\n/**\n * Detects nested quantifiers that can cause catastrophic backtracking.\n * Patterns like (a+)+, (a*)*, (a+)*, etc.\n * @param pattern - The regex pattern to check\n * @returns True if nested quantifiers are detected\n */\nfunction hasNestedQuantifiers(pattern: string): boolean {\n  const nestedQuantifierPattern = /\\([^)]*[+*][^)]*\\)[+*?]/;\n  return nestedQuantifierPattern.test(pattern);\n}\n\n/**\n * Checks if a regex pattern contains potentially dangerous constructs.\n * @param pattern - The regex pattern to validate\n * @returns True if the pattern is dangerous\n */\nfunction isDangerousPattern(pattern: string): boolean {\n  if (hasNestedQuantifiers(pattern)) {\n    return true;\n  }\n\n  if (countNestedGroups(pattern) > MAX_REGEX_COMPLEXITY) {\n    return true;\n  }\n\n  const dangerousPatterns = [\n    /\\.\\{1000,\\}/, // Excessive wildcards\n    /\\(\\?=\\.\\{100,\\}\\)/, // Runaway lookaheads\n    /\\([^)]*\\|\\s*\\){20,}/, // Excessive alternation (rough check)\n    /\\(\\.\\*\\)\\+/, // (.*)+\n    /\\(\\.\\+\\)\\+/, // (.+)+\n    /\\(\\.\\*\\)\\*/, // (.*)*\n    /\\(\\.\\+\\)\\*/, // (.+)*\n  ];\n\n  for (const dangerous of dangerousPatterns) {\n    if (dangerous.test(pattern)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Sanitizes a regex pattern for safe execution.\n * If the pattern is dangerous, it will be escaped to a literal string search.\n * @param pattern - The regex pattern to sanitize\n * @returns Object containing the safe pattern and whether it was escaped\n */\nfunction sanitizeRegex(pattern: string): { safe: string; wasEscaped: boolean } {\n  if (isDangerousPattern(pattern)) {\n    return {\n      safe: escapeRegexSpecialChars(pattern),\n      wasEscaped: true,\n    };\n  }\n\n  try {\n    new RegExp(pattern);\n    return { safe: pattern, wasEscaped: false };\n  } catch {\n    return {\n      safe: escapeRegexSpecialChars(pattern),\n      wasEscaped: true,\n    };\n  }\n}\n\n/**\n * Simplifies tool parameters for search purposes.\n * Extracts only the essential structure needed for parameter name searching.\n * @param parameters - The tool's JSON schema parameters\n * @returns Simplified parameters object\n */\nfunction simplifyParametersForSearch(\n  parameters?: t.JsonSchemaType\n): t.JsonSchemaType | undefined {\n  if (!parameters) {\n    return undefined;\n  }\n\n  if (parameters.properties) {\n    return {\n      type: parameters.type,\n      properties: Object.fromEntries(\n        Object.entries(parameters.properties).map(([key, value]) => [\n          key,\n          { type: (value as t.JsonSchemaType).type },\n        ])\n      ),\n    } as t.JsonSchemaType;\n  }\n\n  return { type: parameters.type };\n}\n\n/**\n * Splits one alphanumeric identifier segment on case boundaries without\n * emitting artificial one-character acronym fragments.\n */\nfunction splitCaseSegment(segment: string): string[] {\n  const splitTokens = segment\n    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')\n    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')\n    .toLowerCase()\n    .split(/\\s+/)\n    .filter(Boolean);\n\n  if (splitTokens.length < 2) return splitTokens;\n\n  const mergedTokens: string[] = [];\n  let prefix = '';\n  for (const token of splitTokens) {\n    if (token.length === 1) {\n      prefix += token;\n      continue;\n    }\n    mergedTokens.push(`${prefix}${token}`);\n    prefix = '';\n  }\n\n  if (prefix && mergedTokens.length > 0) {\n    mergedTokens[mergedTokens.length - 1] += prefix;\n  }\n  return mergedTokens.length > 0 ? mergedTokens : [prefix];\n}\n\n/**\n * Tokenizes a string into lowercase words for BM25.\n * Splits camelCase, underscores, and non-alphanumeric characters for consistent matching.\n * @param text - The text to tokenize\n * @returns Array of lowercase tokens\n */\nfunction tokenize(text: string): string[] {\n  return text\n    .split(/[^a-zA-Z0-9]+/)\n    .filter(Boolean)\n    .flatMap(splitCaseSegment);\n}\n\n/**\n * Creates a searchable document string from tool metadata.\n * @param tool - The tool metadata\n * @param fields - Which fields to include\n * @returns Combined document string for BM25\n */\nfunction createToolDocument(tool: t.ToolMetadata, fields: string[]): string {\n  const parts: string[] = [];\n\n  if (fields.includes('name')) {\n    const baseName = tool.name.replace(/_/g, ' ');\n    parts.push(baseName, baseName);\n  }\n\n  if (fields.includes('description') && tool.description) {\n    parts.push(tool.description);\n  }\n\n  if (fields.includes('parameters') && tool.parameters?.properties) {\n    const paramNames = Object.keys(tool.parameters.properties).join(' ');\n    parts.push(paramNames);\n  }\n\n  return tokenize(parts.join(' ')).join(' ');\n}\n\n/**\n * Determines which field had the best match for a query.\n * @param tool - The tool to check\n * @param queryTokens - Tokenized query\n * @param fields - Fields to check\n * @returns The matched field and a snippet\n */\nfunction findMatchedField(\n  tool: t.ToolMetadata,\n  queryTokens: string[],\n  fields: string[]\n): { field: string; snippet: string } {\n  if (fields.includes('name')) {\n    const nameLower = tool.name.toLowerCase();\n    for (const token of queryTokens) {\n      if (nameLower.includes(token)) {\n        return { field: 'name', snippet: tool.name };\n      }\n    }\n  }\n\n  if (fields.includes('description') && tool.description) {\n    const descLower = tool.description.toLowerCase();\n    for (const token of queryTokens) {\n      if (descLower.includes(token)) {\n        return {\n          field: 'description',\n          snippet: tool.description.substring(0, 100),\n        };\n      }\n    }\n  }\n\n  if (fields.includes('parameters') && tool.parameters?.properties) {\n    const paramNames = Object.keys(tool.parameters.properties);\n    const paramLower = paramNames.join(' ').toLowerCase();\n    for (const token of queryTokens) {\n      if (paramLower.includes(token)) {\n        return { field: 'parameters', snippet: paramNames.join(', ') };\n      }\n    }\n  }\n\n  const fallbackSnippet = tool.description\n    ? tool.description.substring(0, 100)\n    : tool.name;\n  return { field: 'unknown', snippet: fallbackSnippet };\n}\n\n/**\n * Performs BM25-based search for better relevance ranking.\n * Uses Okapi BM25 algorithm for term frequency and document length normalization.\n * If query is empty, returns all tools (up to maxResults) sorted alphabetically.\n * @param tools - Array of tool metadata to search\n * @param query - The search query (empty returns all tools)\n * @param fields - Which fields to search\n * @param maxResults - Maximum results to return\n * @returns Search response with matching tools ranked by BM25 score\n */\nfunction performLocalSearch(\n  tools: t.ToolMetadata[],\n  query: string,\n  fields: string[],\n  maxResults: number\n): t.ToolSearchResponse {\n  if (tools.length === 0) {\n    return {\n      tool_references: [],\n      total_tools_searched: 0,\n      pattern_used: query,\n    };\n  }\n\n  const queryTokens = tokenize(query);\n\n  if (queryTokens.length === 0) {\n    const allTools = tools\n      .slice()\n      .sort((a, b) => a.name.localeCompare(b.name))\n      .slice(0, maxResults)\n      .map((tool) => ({\n        tool_name: tool.name,\n        match_score: 1.0,\n        matched_field: 'name',\n        snippet: tool.description.substring(0, 100) || tool.name,\n      }));\n\n    return {\n      tool_references: allTools,\n      total_tools_searched: tools.length,\n      pattern_used: query,\n    };\n  }\n\n  const documents = tools.map((tool) => createToolDocument(tool, fields));\n  const scores = BM25(documents, queryTokens, { k1: 1.5, b: 0.75 }) as number[];\n\n  const maxScore = Math.max(...scores.filter((s) => s > 0), 1);\n  const queryLower = query.toLowerCase().trim();\n  const queryIdentifier = queryTokens.join('');\n  const matchesIdentifiers = fields.includes('name');\n\n  const results: Array<{\n    result: t.ToolSearchResult;\n    identifierPriority: number;\n  }> = [];\n  for (let i = 0; i < tools.length; i++) {\n    const score = scores[i];\n    const hasSearchScore = Number.isFinite(score) && score > 0;\n    let identifierPriority = 0;\n    let normalizedScore = hasSearchScore ? Math.min(score / maxScore, 1.0) : 0;\n\n    if (matchesIdentifiers) {\n      const rawBaseName = getBaseToolName(tools[i].name).toLowerCase();\n      const rawFullName = tools[i].name.toLowerCase();\n      const baseIdentifier = tokenize(rawBaseName).join('');\n      const fullIdentifier = tokenize(rawFullName).join('');\n\n      if (rawFullName === queryLower) {\n        identifierPriority = 4;\n        normalizedScore = 1.0;\n      } else if (rawBaseName === queryLower) {\n        identifierPriority = 3;\n        normalizedScore = 1.0;\n      } else if (\n        baseIdentifier === queryIdentifier ||\n        fullIdentifier === queryIdentifier\n      ) {\n        identifierPriority = 2;\n        normalizedScore = 1.0;\n      } else if (baseIdentifier.startsWith(queryIdentifier)) {\n        identifierPriority = 1;\n        normalizedScore = Math.max(normalizedScore, 0.95);\n      }\n    }\n\n    if (!hasSearchScore && identifierPriority === 0) continue;\n\n    const { field, snippet } = findMatchedField(tools[i], queryTokens, fields);\n    results.push({\n      result: {\n        tool_name: tools[i].name,\n        match_score: normalizedScore,\n        matched_field: field,\n        snippet,\n      },\n      identifierPriority,\n    });\n  }\n\n  results.sort(\n    (a, b) =>\n      b.identifierPriority - a.identifierPriority ||\n      b.result.match_score - a.result.match_score\n  );\n  const topResults = results.slice(0, maxResults).map(({ result }) => result);\n\n  return {\n    tool_references: topResults,\n    total_tools_searched: tools.length,\n    pattern_used: query,\n  };\n}\n\n/**\n * Generates the JavaScript search script to be executed in the sandbox.\n * Uses plain JavaScript for maximum compatibility with the Code API.\n * @param deferredTools - Array of tool metadata to search through\n * @param fields - Which fields to search\n * @param maxResults - Maximum number of results to return\n * @param sanitizedPattern - The sanitized regex pattern\n * @returns The JavaScript code string\n */\nfunction generateSearchScript(\n  deferredTools: t.ToolMetadata[],\n  fields: string[],\n  maxResults: number,\n  sanitizedPattern: string\n): string {\n  const lines = [\n    '// Tool definitions (injected)',\n    'var tools = ' + JSON.stringify(deferredTools) + ';',\n    'var searchFields = ' + JSON.stringify(fields) + ';',\n    'var maxResults = ' + maxResults + ';',\n    'var pattern = ' + JSON.stringify(sanitizedPattern) + ';',\n    '',\n    '// Compile regex (pattern is sanitized client-side)',\n    'var regex;',\n    'try {',\n    '  regex = new RegExp(pattern, \\'i\\');',\n    '} catch (e) {',\n    '  regex = new RegExp(pattern.replace(/[.*+?^${}()[\\\\]\\\\\\\\|]/g, \"\\\\\\\\$&\"), \"i\");',\n    '}',\n    '',\n    '// Search logic',\n    'var results = [];',\n    '',\n    'for (var j = 0; j < tools.length; j++) {',\n    '  var tool = tools[j];',\n    '  var bestScore = 0;',\n    '  var matchedField = \\'\\';',\n    '  var snippet = \\'\\';',\n    '',\n    '  // Search name (highest priority)',\n    '  if (searchFields.indexOf(\\'name\\') >= 0 && regex.test(tool.name)) {',\n    '    bestScore = 0.95;',\n    '    matchedField = \\'name\\';',\n    '    snippet = tool.name;',\n    '  }',\n    '',\n    '  // Search description (medium priority)',\n    '  if (searchFields.indexOf(\\'description\\') >= 0 && tool.description && regex.test(tool.description)) {',\n    '    if (bestScore === 0) {',\n    '      bestScore = 0.75;',\n    '      matchedField = \\'description\\';',\n    '      snippet = tool.description.substring(0, 100);',\n    '    }',\n    '  }',\n    '',\n    '  // Search parameter names (lower priority)',\n    '  if (searchFields.indexOf(\\'parameters\\') >= 0 && tool.parameters && tool.parameters.properties) {',\n    '    var paramNames = Object.keys(tool.parameters.properties).join(\\' \\');',\n    '    if (regex.test(paramNames)) {',\n    '      if (bestScore === 0) {',\n    '        bestScore = 0.60;',\n    '        matchedField = \\'parameters\\';',\n    '        snippet = paramNames;',\n    '      }',\n    '    }',\n    '  }',\n    '',\n    '  if (bestScore > 0) {',\n    '    results.push({',\n    '      tool_name: tool.name,',\n    '      match_score: bestScore,',\n    '      matched_field: matchedField,',\n    '      snippet: snippet',\n    '    });',\n    '  }',\n    '}',\n    '',\n    '// Sort by score (descending) and limit results',\n    'results.sort(function(a, b) { return b.match_score - a.match_score; });',\n    'var topResults = results.slice(0, maxResults);',\n    '',\n    '// Output as JSON',\n    'console.log(JSON.stringify({',\n    '  tool_references: topResults.map(function(r) {',\n    '    return {',\n    '      tool_name: r.tool_name,',\n    '      match_score: r.match_score,',\n    '      matched_field: r.matched_field,',\n    '      snippet: r.snippet',\n    '    };',\n    '  }),',\n    '  total_tools_searched: tools.length,',\n    '  pattern_used: pattern',\n    '}));',\n  ];\n  return lines.join('\\n');\n}\n\n/**\n * Parses the search results from stdout JSON.\n * @param stdout - The stdout string containing JSON results\n * @returns Parsed search response\n */\nfunction parseSearchResults(stdout: string): t.ToolSearchResponse {\n  const jsonMatch = stdout.trim();\n  const parsed = JSON.parse(jsonMatch) as t.ToolSearchResponse;\n  return parsed;\n}\n\n/**\n * Formats search results as structured JSON for efficient parsing.\n * @param searchResponse - The parsed search response\n * @param nameFormat - Whether to show 'full' names (tool_mcp_server) or 'base' names (tool only)\n * @returns JSON string with search results\n */\nfunction formatSearchResults(\n  searchResponse: t.ToolSearchResponse,\n  nameFormat: t.McpNameFormat = 'full'\n): string {\n  const { tool_references, total_tools_searched, pattern_used } =\n    searchResponse;\n  const useFullName = nameFormat === 'full';\n\n  const output = {\n    found: tool_references.length,\n    tools: tool_references.map((ref) => ({\n      name: useFullName ? ref.tool_name : getBaseToolName(ref.tool_name),\n      score: Number(ref.match_score.toFixed(2)),\n      matched_in: ref.matched_field,\n      snippet: ref.snippet,\n    })),\n    total_searched: total_tools_searched,\n    query: pattern_used,\n  };\n\n  return JSON.stringify(output, null, 2);\n}\n\n/**\n * Extracts the base tool name (without MCP server suffix) from a full tool name.\n * @param toolName - The full tool name\n * @returns The base tool name without server suffix\n */\nfunction getBaseToolName(toolName: string): string {\n  const delimiterIndex = toolName.indexOf(Constants.MCP_DELIMITER);\n  if (delimiterIndex === -1) {\n    return toolName;\n  }\n  return toolName.substring(0, delimiterIndex);\n}\n\n/**\n * Checks whether a tool has any defined parameters in its JSON schema.\n * @param parameters - The tool's JSON schema parameters\n * @returns true if the tool has at least one parameter property\n */\nfunction hasParams(parameters?: t.JsonSchemaType): boolean {\n  return (\n    parameters?.properties != null &&\n    Object.keys(parameters.properties).length > 0\n  );\n}\n\n/**\n * Generates a compact listing of deferred tools grouped by server.\n * Format: \"server: tool1, tool2(\\u2026), tool3\"\n * Tools with parameters are annotated with (\\u2026) to signal\n * that the LLM should discover the schema via tool_search before calling.\n * Non-MCP tools are grouped under \"other\".\n * @param toolRegistry - The tool registry\n * @param onlyDeferred - Whether to only include deferred tools\n * @returns Formatted string with tools grouped by server\n */\nfunction getDeferredToolsListing(\n  toolRegistry: t.LCToolRegistry | undefined,\n  onlyDeferred: boolean\n): string {\n  if (!toolRegistry) {\n    return '';\n  }\n\n  const toolsByServer: Record<string, string[]> = {};\n\n  for (const lcTool of toolRegistry.values()) {\n    if (onlyDeferred && lcTool.defer_loading !== true) {\n      continue;\n    }\n\n    const toolName = lcTool.name;\n    const serverName = extractMcpServerName(toolName) ?? 'other';\n    const baseName = getBaseToolName(toolName);\n    const displayName = hasParams(lcTool.parameters)\n      ? `${baseName}(\\u2026)`\n      : baseName;\n\n    if (!(serverName in toolsByServer)) {\n      toolsByServer[serverName] = [];\n    }\n    toolsByServer[serverName].push(displayName);\n  }\n\n  const serverNames = Object.keys(toolsByServer).sort((a, b) => {\n    if (a === 'other') return 1;\n    if (b === 'other') return -1;\n    return a.localeCompare(b);\n  });\n\n  if (serverNames.length === 0) {\n    return '';\n  }\n\n  const lines = serverNames.map(\n    (server) => `${server}: ${toolsByServer[server].join(', ')}`\n  );\n\n  return lines.join('\\n');\n}\n\n/**\n * Formats a server listing response as structured JSON.\n * NOTE: This is a PREVIEW only - tools are NOT discovered/loaded.\n * @param tools - Array of tool metadata from the server(s)\n * @param serverNames - The MCP server name(s)\n * @param nameFormat - Whether to show 'full' names (tool_mcp_server) or 'base' names (tool only)\n * @returns JSON string showing all tools grouped by server\n */\nfunction formatServerListing(\n  tools: t.ToolMetadata[],\n  serverNames: string | string[],\n  nameFormat: t.McpNameFormat = 'full'\n): string {\n  const servers = Array.isArray(serverNames) ? serverNames : [serverNames];\n  const useFullName = nameFormat === 'full';\n\n  if (tools.length === 0) {\n    return JSON.stringify(\n      {\n        listing_mode: true,\n        servers,\n        total_tools: 0,\n        tools_by_server: {},\n        hint: 'No tools found from the specified MCP server(s).',\n      },\n      null,\n      2\n    );\n  }\n\n  const toolsByServer: Record<\n    string,\n    Array<{ name: string; description: string }>\n  > = {};\n  for (const tool of tools) {\n    const server = extractMcpServerName(tool.name) ?? 'unknown';\n    if (!(server in toolsByServer)) {\n      toolsByServer[server] = [];\n    }\n    toolsByServer[server].push({\n      name: useFullName ? tool.name : getBaseToolName(tool.name),\n      description:\n        tool.description.length > 100\n          ? tool.description.substring(0, 97) + '...'\n          : tool.description,\n    });\n  }\n\n  const exampleToolName = useFullName\n    ? (tools[0]?.name ?? 'tool_name')\n    : getBaseToolName(tools[0]?.name ?? 'tool_name');\n\n  const output = {\n    listing_mode: true,\n    servers,\n    total_tools: tools.length,\n    tools_by_server: toolsByServer,\n    hint: `To use a tool, search for it by name (e.g., query: \"${exampleToolName}\") to load it.`,\n  };\n\n  return JSON.stringify(output, null, 2);\n}\n\n/**\n * Creates a Tool Search tool for discovering tools from a large registry.\n *\n * This tool enables AI agents to dynamically discover tools from a large library\n * without loading all tool definitions into the LLM context window. The agent\n * can search for relevant tools on-demand.\n *\n * **Modes:**\n * - `code_interpreter` (default): Uses external sandbox for regex search. Safer for complex patterns.\n * - `local`: Uses safe substring matching locally. No network call, faster, completely safe from ReDoS.\n *\n * The tool registry can be provided either:\n * 1. At initialization time via params.toolRegistry\n * 2. At runtime via config.configurable.toolRegistry when invoking\n *\n * @param params - Configuration parameters for the tool (toolRegistry is optional)\n * @returns A LangChain DynamicStructuredTool for tool searching\n *\n * @example\n * // Option 1: Code interpreter mode (regex via sandbox)\n * const tool = createToolSearch({ toolRegistry });\n * await tool.invoke({ query: 'expense.*report' });\n *\n * @example\n * // Option 2: Local mode (safe substring search)\n * const tool = createToolSearch({ mode: 'local', toolRegistry });\n * await tool.invoke({ query: 'expense' });\n */\nfunction createToolSearch(\n  initParams: t.ToolSearchParams = {}\n): DynamicStructuredTool {\n  const mode: t.ToolSearchMode = initParams.mode ?? 'code_interpreter';\n  const defaultOnlyDeferred = initParams.onlyDeferred ?? true;\n  const mcpNameFormat: t.McpNameFormat = initParams.mcpNameFormat ?? 'full';\n  const schema = createToolSearchSchema(mode);\n\n  const baseEndpoint = initParams.baseUrl ?? getCodeBaseURL();\n  const EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\n  const deferredToolsListing = getDeferredToolsListing(\n    initParams.toolRegistry,\n    defaultOnlyDeferred\n  );\n\n  const toolsListSection =\n    deferredToolsListing.length > 0\n      ? `\n\nDeferred tools (search to load; \\u2026 = has params, search first):\n${deferredToolsListing}`\n      : '';\n\n  const mcpNote =\n    deferredToolsListing.includes(Constants.MCP_DELIMITER) ||\n    deferredToolsListing.split('\\n').some((line) => !line.startsWith('other:'))\n      ? `\n- MCP tools use format: toolName${Constants.MCP_DELIMITER}serverName\n- Use mcp_server param to filter by server`\n      : '';\n\n  const description =\n    mode === 'local'\n      ? `\nSearches deferred tools using BM25 ranking. Multi-word queries supported.\n${mcpNote}${toolsListSection}\n`.trim()\n      : `\nSearches deferred tools by regex pattern.\n${mcpNote}${toolsListSection}\n`.trim();\n\n  return tool(\n    async (rawParams, config) => {\n      const params = rawParams as ToolSearchParams;\n      const {\n        query = '',\n        fields = ['name', 'description'],\n        max_results = DEFAULT_MAX_RESULTS,\n        mcp_server,\n      } = params;\n\n      const {\n        toolRegistry: paramToolRegistry,\n        onlyDeferred: paramOnlyDeferred,\n        mcpServer: paramMcpServer,\n      } = config.toolCall ?? {};\n\n      const toolRegistry = paramToolRegistry ?? initParams.toolRegistry;\n      const onlyDeferred =\n        paramOnlyDeferred !== undefined\n          ? paramOnlyDeferred\n          : defaultOnlyDeferred;\n      const rawServerFilter =\n        mcp_server ?? paramMcpServer ?? initParams.mcpServer;\n      const serverFilters = normalizeServerFilter(rawServerFilter);\n      const hasServerFilter = serverFilters.length > 0;\n\n      if (toolRegistry == null) {\n        return [\n          'Error: No tool registry provided. Configure toolRegistry at agent level or initialization.',\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: query,\n              error: 'No tool registry provided',\n            },\n          },\n        ];\n      }\n\n      const toolsArray: t.LCTool[] = Array.from(toolRegistry.values());\n      const deferredTools: t.ToolMetadata[] = toolsArray\n        .filter((lcTool) => {\n          if (onlyDeferred === true && lcTool.defer_loading !== true) {\n            return false;\n          }\n          if (\n            hasServerFilter &&\n            !isFromAnyMcpServer(lcTool.name, serverFilters)\n          ) {\n            return false;\n          }\n          return true;\n        })\n        .map((lcTool) => ({\n          name: lcTool.name,\n          description: lcTool.description ?? '',\n          parameters: simplifyParametersForSearch(lcTool.parameters),\n        }));\n\n      if (deferredTools.length === 0) {\n        const serverMsg = hasServerFilter\n          ? ` from MCP server(s): ${serverFilters.join(', ')}`\n          : '';\n        return [\n          `No tools available to search${serverMsg}. The tool registry is empty or no matching deferred tools are registered.`,\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: query,\n              mcp_server: serverFilters,\n            },\n          },\n        ];\n      }\n\n      const isServerListing = hasServerFilter && query === '';\n\n      if (isServerListing) {\n        const formattedOutput = formatServerListing(\n          deferredTools,\n          serverFilters,\n          mcpNameFormat\n        );\n\n        return [\n          formattedOutput,\n          {\n            tool_references: [],\n            metadata: {\n              total_available: deferredTools.length,\n              mcp_server: serverFilters,\n              listing_mode: true,\n            },\n          },\n        ];\n      }\n\n      if (mode === 'local') {\n        const searchResponse = performLocalSearch(\n          deferredTools,\n          query,\n          fields,\n          max_results\n        );\n        const formattedOutput = formatSearchResults(\n          searchResponse,\n          mcpNameFormat\n        );\n\n        return [\n          formattedOutput,\n          {\n            tool_references: searchResponse.tool_references,\n            metadata: {\n              total_searched: searchResponse.total_tools_searched,\n              pattern: searchResponse.pattern_used,\n              mcp_server: serverFilters.length > 0 ? serverFilters : undefined,\n            },\n          },\n        ];\n      }\n\n      const { safe: sanitizedPattern, wasEscaped } = sanitizeRegex(query);\n      let warningMessage = '';\n      if (wasEscaped) {\n        warningMessage =\n          'Note: The provided pattern was converted to a literal search for safety.\\n\\n';\n      }\n\n      const searchScript = generateSearchScript(\n        deferredTools,\n        fields,\n        max_results,\n        sanitizedPattern\n      );\n\n      const postData = {\n        lang: 'js',\n        code: searchScript,\n        timeout: SEARCH_TIMEOUT,\n      };\n\n      try {\n        const fetchOptions: RequestInit = {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'User-Agent': 'LibreChat/1.0',\n          },\n          body: JSON.stringify(postData),\n        };\n\n        if (process.env.PROXY != null && process.env.PROXY !== '') {\n          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n        }\n\n        const response = await fetch(EXEC_ENDPOINT, fetchOptions);\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const result: t.ExecuteResult = await response.json();\n\n        if (result.stderr && result.stderr.trim()) {\n          // eslint-disable-next-line no-console\n          console.warn('[ToolSearch] stderr:', result.stderr);\n        }\n\n        if (!result.stdout || !result.stdout.trim()) {\n          return [\n            `${warningMessage}No tools matched the pattern \"${sanitizedPattern}\".\\nTotal tools searched: ${deferredTools.length}`,\n            {\n              tool_references: [],\n              metadata: {\n                total_searched: deferredTools.length,\n                pattern: sanitizedPattern,\n              },\n            },\n          ];\n        }\n\n        const searchResponse = parseSearchResults(result.stdout);\n        const formattedOutput = `${warningMessage}${formatSearchResults(searchResponse, mcpNameFormat)}`;\n\n        return [\n          formattedOutput,\n          {\n            tool_references: searchResponse.tool_references,\n            metadata: {\n              total_searched: searchResponse.total_tools_searched,\n              pattern: searchResponse.pattern_used,\n            },\n          },\n        ];\n      } catch (error) {\n        // eslint-disable-next-line no-console\n        console.error('[ToolSearch] Error:', error);\n\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return [\n          `Tool search failed: ${errorMessage}\\n\\nSuggestion: Try a simpler search pattern or search for specific tool names.`,\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: sanitizedPattern,\n              error: errorMessage,\n            },\n          },\n        ];\n      }\n    },\n    {\n      name: Constants.TOOL_SEARCH,\n      description,\n      schema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport {\n  createToolSearch,\n  performLocalSearch,\n  extractMcpServerName,\n  isFromMcpServer,\n  isFromAnyMcpServer,\n  normalizeServerFilter,\n  getAvailableMcpServers,\n  getDeferredToolsListing,\n  getBaseToolName,\n  formatServerListing,\n  sanitizeRegex,\n  escapeRegexSpecialChars,\n  isDangerousPattern,\n  countNestedGroups,\n  hasNestedQuantifiers,\n};\n"],"mappings":"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"}
+{"version":3,"file":"ToolSearch.mjs","names":["params"],"sources":["../../../src/tools/ToolSearch.ts"],"sourcesContent":["// src/tools/ToolSearch.ts\nimport { config } from 'dotenv';\nimport * as okapibm25Module from 'okapibm25';\n\ntype BM25Fn = (\n  documents: string[],\n  keywords: string[],\n  constants?: { k1?: number; b?: number }\n) => number[];\n\nfunction getBM25Function(): BM25Fn {\n  const mod = okapibm25Module as unknown as {\n    default: BM25Fn | { default: BM25Fn } | undefined;\n  };\n  if (typeof mod === 'function') return mod;\n  if (typeof mod.default === 'function') return mod.default;\n  if (mod.default != null && typeof mod.default.default === 'function')\n    return mod.default.default;\n  throw new Error('Could not resolve BM25 function from okapibm25 module');\n}\n\nconst BM25 = getBM25Function();\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type * as t from '@/types';\nimport { INTENT_PROPERTY } from '@/tools/intentArg';\nimport { getCodeBaseURL } from './CodeExecutor';\nimport { Constants } from '@/common';\n\nconfig();\n\n/** Maximum allowed regex pattern length */\nconst MAX_PATTERN_LENGTH = 200;\n\nexport const ToolSearchToolName = Constants.TOOL_SEARCH;\n\nexport const ToolSearchToolDescription =\n  'Searches deferred tools using BM25 ranking. Multi-word queries supported. Use mcp_server param to filter by server.';\n\nconst QUERY_DESCRIPTION_LOCAL =\n  'Search term to find in tool names and descriptions. Case-insensitive substring matching. Optional if mcp_server is provided.';\nconst QUERY_DESCRIPTION_REGEX =\n  'Regex pattern to search tool names and descriptions. Optional if mcp_server is provided.';\nconst FIELDS_DESCRIPTION =\n  'Which fields to search. Default: name and description';\nconst MAX_RESULTS_DESCRIPTION = 'Maximum number of matching tools to return';\nconst DEFAULT_MAX_RESULTS = 5;\nconst MCP_SERVER_DESCRIPTION =\n  'Filter to tools from specific MCP server(s). Can be a single server name or array of names. If provided without a query, lists all tools from those servers.';\n\nexport const ToolSearchToolSchema = {\n  type: 'object',\n  properties: {\n    intent: { ...INTENT_PROPERTY },\n    query: {\n      type: 'string',\n      maxLength: MAX_PATTERN_LENGTH,\n      default: '',\n      description: QUERY_DESCRIPTION_LOCAL,\n    },\n    fields: {\n      type: 'array',\n      items: { type: 'string', enum: ['name', 'description', 'parameters'] },\n      default: ['name', 'description'],\n      description: FIELDS_DESCRIPTION,\n    },\n    max_results: {\n      type: 'integer',\n      minimum: 1,\n      maximum: 50,\n      default: DEFAULT_MAX_RESULTS,\n      description: MAX_RESULTS_DESCRIPTION,\n    },\n    mcp_server: {\n      oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],\n      description: MCP_SERVER_DESCRIPTION,\n    },\n  },\n  required: [],\n} as const;\n\nexport const ToolSearchToolDefinition = {\n  name: ToolSearchToolName,\n  description: ToolSearchToolDescription,\n  schema: ToolSearchToolSchema,\n} as const;\n\n/** Maximum allowed regex nesting depth */\nconst MAX_REGEX_COMPLEXITY = 5;\n\n/** Default search timeout in milliseconds */\nconst SEARCH_TIMEOUT = 5000;\n\n/** JSON schema type for tool search parameters */\ninterface ToolSearchSchema {\n  type: 'object';\n  properties: Record<string, unknown>;\n  required: string[];\n}\n\n/** Input params type for tool search */\ninterface ToolSearchParams {\n  query?: string;\n  fields?: ('name' | 'description' | 'parameters')[];\n  max_results?: number;\n  mcp_server?: string | string[];\n}\n\n/**\n * Creates the JSON schema with dynamic query description based on mode.\n * @param mode - The search mode determining query interpretation\n * @returns JSON schema for tool search parameters\n */\nfunction createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema {\n  const queryDescription =\n    mode === 'local' ? QUERY_DESCRIPTION_LOCAL : QUERY_DESCRIPTION_REGEX;\n\n  return {\n    type: 'object',\n    properties: {\n      intent: { ...INTENT_PROPERTY },\n      query: {\n        type: 'string',\n        maxLength: MAX_PATTERN_LENGTH,\n        default: '',\n        description: queryDescription,\n      },\n      fields: {\n        type: 'array',\n        items: { type: 'string', enum: ['name', 'description', 'parameters'] },\n        default: ['name', 'description'],\n        description: FIELDS_DESCRIPTION,\n      },\n      max_results: {\n        type: 'integer',\n        minimum: 1,\n        maximum: 50,\n        default: DEFAULT_MAX_RESULTS,\n        description: MAX_RESULTS_DESCRIPTION,\n      },\n      mcp_server: {\n        oneOf: [\n          { type: 'string' },\n          { type: 'array', items: { type: 'string' } },\n        ],\n        description: MCP_SERVER_DESCRIPTION,\n      },\n    },\n    required: [],\n  };\n}\n\n/**\n * Extracts the MCP server name from a tool name.\n * MCP tools follow the pattern: toolName_mcp_serverName\n * @param toolName - The full tool name\n * @returns The server name if it's an MCP tool, undefined otherwise\n */\nfunction extractMcpServerName(toolName: string): string | undefined {\n  const delimiterIndex = toolName.indexOf(Constants.MCP_DELIMITER);\n  if (delimiterIndex === -1) {\n    return undefined;\n  }\n  return toolName.substring(delimiterIndex + Constants.MCP_DELIMITER.length);\n}\n\n/**\n * Checks if a tool belongs to a specific MCP server.\n * @param toolName - The full tool name\n * @param serverName - The server name to match\n * @returns True if the tool belongs to the specified server\n */\nfunction isFromMcpServer(toolName: string, serverName: string): boolean {\n  const toolServer = extractMcpServerName(toolName);\n  return toolServer === serverName;\n}\n\n/**\n * Checks if a tool belongs to any of the specified MCP servers.\n * @param toolName - The full tool name\n * @param serverNames - Array of server names to match\n * @returns True if the tool belongs to any of the specified servers\n */\nfunction isFromAnyMcpServer(toolName: string, serverNames: string[]): boolean {\n  const toolServer = extractMcpServerName(toolName);\n  if (toolServer === undefined) {\n    return false;\n  }\n  return serverNames.includes(toolServer);\n}\n\n/**\n * Normalizes server filter input to always be an array.\n * @param serverFilter - String, array of strings, or undefined\n * @returns Array of server names (empty if none specified)\n */\nfunction normalizeServerFilter(\n  serverFilter: string | string[] | undefined\n): string[] {\n  if (serverFilter === undefined) {\n    return [];\n  }\n  if (typeof serverFilter === 'string') {\n    return serverFilter === '' ? [] : [serverFilter];\n  }\n  return serverFilter.filter((s) => s !== '');\n}\n\n/**\n * Extracts all unique MCP server names from a tool registry.\n * @param toolRegistry - The tool registry to scan\n * @param onlyDeferred - If true, only considers deferred tools\n * @returns Array of unique server names, sorted alphabetically\n */\nfunction getAvailableMcpServers(\n  toolRegistry: t.LCToolRegistry | undefined,\n  onlyDeferred: boolean = true\n): string[] {\n  if (!toolRegistry) {\n    return [];\n  }\n\n  const servers = new Set<string>();\n  for (const [, toolDef] of toolRegistry) {\n    if (onlyDeferred && toolDef.defer_loading !== true) {\n      continue;\n    }\n    const server = extractMcpServerName(toolDef.name);\n    if (server !== undefined && server !== '') {\n      servers.add(server);\n    }\n  }\n\n  return Array.from(servers).sort();\n}\n\n/**\n * Escapes special regex characters in a string to use as a literal pattern.\n * @param pattern - The string to escape\n * @returns The escaped string safe for use in a RegExp\n */\nfunction escapeRegexSpecialChars(pattern: string): string {\n  return pattern.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * Counts the maximum nesting depth of groups in a regex pattern.\n * @param pattern - The regex pattern to analyze\n * @returns The maximum nesting depth\n */\nfunction countNestedGroups(pattern: string): number {\n  let maxDepth = 0;\n  let currentDepth = 0;\n\n  for (let i = 0; i < pattern.length; i++) {\n    if (pattern[i] === '(' && (i === 0 || pattern[i - 1] !== '\\\\')) {\n      currentDepth++;\n      maxDepth = Math.max(maxDepth, currentDepth);\n    } else if (pattern[i] === ')' && (i === 0 || pattern[i - 1] !== '\\\\')) {\n      currentDepth = Math.max(0, currentDepth - 1);\n    }\n  }\n\n  return maxDepth;\n}\n\n/**\n * Detects nested quantifiers that can cause catastrophic backtracking.\n * Patterns like (a+)+, (a*)*, (a+)*, etc.\n * @param pattern - The regex pattern to check\n * @returns True if nested quantifiers are detected\n */\nfunction hasNestedQuantifiers(pattern: string): boolean {\n  const nestedQuantifierPattern = /\\([^)]*[+*][^)]*\\)[+*?]/;\n  return nestedQuantifierPattern.test(pattern);\n}\n\n/**\n * Checks if a regex pattern contains potentially dangerous constructs.\n * @param pattern - The regex pattern to validate\n * @returns True if the pattern is dangerous\n */\nfunction isDangerousPattern(pattern: string): boolean {\n  if (hasNestedQuantifiers(pattern)) {\n    return true;\n  }\n\n  if (countNestedGroups(pattern) > MAX_REGEX_COMPLEXITY) {\n    return true;\n  }\n\n  const dangerousPatterns = [\n    /\\.\\{1000,\\}/, // Excessive wildcards\n    /\\(\\?=\\.\\{100,\\}\\)/, // Runaway lookaheads\n    /\\([^)]*\\|\\s*\\){20,}/, // Excessive alternation (rough check)\n    /\\(\\.\\*\\)\\+/, // (.*)+\n    /\\(\\.\\+\\)\\+/, // (.+)+\n    /\\(\\.\\*\\)\\*/, // (.*)*\n    /\\(\\.\\+\\)\\*/, // (.+)*\n  ];\n\n  for (const dangerous of dangerousPatterns) {\n    if (dangerous.test(pattern)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Sanitizes a regex pattern for safe execution.\n * If the pattern is dangerous, it will be escaped to a literal string search.\n * @param pattern - The regex pattern to sanitize\n * @returns Object containing the safe pattern and whether it was escaped\n */\nfunction sanitizeRegex(pattern: string): { safe: string; wasEscaped: boolean } {\n  if (isDangerousPattern(pattern)) {\n    return {\n      safe: escapeRegexSpecialChars(pattern),\n      wasEscaped: true,\n    };\n  }\n\n  try {\n    new RegExp(pattern);\n    return { safe: pattern, wasEscaped: false };\n  } catch {\n    return {\n      safe: escapeRegexSpecialChars(pattern),\n      wasEscaped: true,\n    };\n  }\n}\n\n/**\n * Simplifies tool parameters for search purposes.\n * Extracts only the essential structure needed for parameter name searching.\n * @param parameters - The tool's JSON schema parameters\n * @returns Simplified parameters object\n */\nfunction simplifyParametersForSearch(\n  parameters?: t.JsonSchemaType\n): t.JsonSchemaType | undefined {\n  if (!parameters) {\n    return undefined;\n  }\n\n  if (parameters.properties) {\n    return {\n      type: parameters.type,\n      properties: Object.fromEntries(\n        Object.entries(parameters.properties).map(([key, value]) => [\n          key,\n          { type: (value as t.JsonSchemaType).type },\n        ])\n      ),\n    } as t.JsonSchemaType;\n  }\n\n  return { type: parameters.type };\n}\n\n/**\n * Splits one alphanumeric identifier segment on case boundaries without\n * emitting artificial one-character acronym fragments.\n */\nfunction splitCaseSegment(segment: string): string[] {\n  const splitTokens = segment\n    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')\n    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')\n    .toLowerCase()\n    .split(/\\s+/)\n    .filter(Boolean);\n\n  if (splitTokens.length < 2) return splitTokens;\n\n  const mergedTokens: string[] = [];\n  let prefix = '';\n  for (const token of splitTokens) {\n    if (token.length === 1) {\n      prefix += token;\n      continue;\n    }\n    mergedTokens.push(`${prefix}${token}`);\n    prefix = '';\n  }\n\n  if (prefix && mergedTokens.length > 0) {\n    mergedTokens[mergedTokens.length - 1] += prefix;\n  }\n  return mergedTokens.length > 0 ? mergedTokens : [prefix];\n}\n\n/**\n * Tokenizes a string into lowercase words for BM25.\n * Splits camelCase, underscores, and non-alphanumeric characters for consistent matching.\n * @param text - The text to tokenize\n * @returns Array of lowercase tokens\n */\nfunction tokenize(text: string): string[] {\n  return text\n    .split(/[^a-zA-Z0-9]+/)\n    .filter(Boolean)\n    .flatMap(splitCaseSegment);\n}\n\n/**\n * Creates a searchable document string from tool metadata.\n * @param tool - The tool metadata\n * @param fields - Which fields to include\n * @returns Combined document string for BM25\n */\nfunction createToolDocument(tool: t.ToolMetadata, fields: string[]): string {\n  const parts: string[] = [];\n\n  if (fields.includes('name')) {\n    const baseName = tool.name.replace(/_/g, ' ');\n    parts.push(baseName, baseName);\n  }\n\n  if (fields.includes('description') && tool.description) {\n    parts.push(tool.description);\n  }\n\n  if (fields.includes('parameters') && tool.parameters?.properties) {\n    const paramNames = Object.keys(tool.parameters.properties).join(' ');\n    parts.push(paramNames);\n  }\n\n  return tokenize(parts.join(' ')).join(' ');\n}\n\n/**\n * Determines which field had the best match for a query.\n * @param tool - The tool to check\n * @param queryTokens - Tokenized query\n * @param fields - Fields to check\n * @returns The matched field and a snippet\n */\nfunction findMatchedField(\n  tool: t.ToolMetadata,\n  queryTokens: string[],\n  fields: string[]\n): { field: string; snippet: string } {\n  if (fields.includes('name')) {\n    const nameLower = tool.name.toLowerCase();\n    for (const token of queryTokens) {\n      if (nameLower.includes(token)) {\n        return { field: 'name', snippet: tool.name };\n      }\n    }\n  }\n\n  if (fields.includes('description') && tool.description) {\n    const descLower = tool.description.toLowerCase();\n    for (const token of queryTokens) {\n      if (descLower.includes(token)) {\n        return {\n          field: 'description',\n          snippet: tool.description.substring(0, 100),\n        };\n      }\n    }\n  }\n\n  if (fields.includes('parameters') && tool.parameters?.properties) {\n    const paramNames = Object.keys(tool.parameters.properties);\n    const paramLower = paramNames.join(' ').toLowerCase();\n    for (const token of queryTokens) {\n      if (paramLower.includes(token)) {\n        return { field: 'parameters', snippet: paramNames.join(', ') };\n      }\n    }\n  }\n\n  const fallbackSnippet = tool.description\n    ? tool.description.substring(0, 100)\n    : tool.name;\n  return { field: 'unknown', snippet: fallbackSnippet };\n}\n\n/**\n * Performs BM25-based search for better relevance ranking.\n * Uses Okapi BM25 algorithm for term frequency and document length normalization.\n * If query is empty, returns all tools (up to maxResults) sorted alphabetically.\n * @param tools - Array of tool metadata to search\n * @param query - The search query (empty returns all tools)\n * @param fields - Which fields to search\n * @param maxResults - Maximum results to return\n * @returns Search response with matching tools ranked by BM25 score\n */\nfunction performLocalSearch(\n  tools: t.ToolMetadata[],\n  query: string,\n  fields: string[],\n  maxResults: number\n): t.ToolSearchResponse {\n  if (tools.length === 0) {\n    return {\n      tool_references: [],\n      total_tools_searched: 0,\n      pattern_used: query,\n    };\n  }\n\n  const queryTokens = tokenize(query);\n\n  if (queryTokens.length === 0) {\n    const allTools = tools\n      .slice()\n      .sort((a, b) => a.name.localeCompare(b.name))\n      .slice(0, maxResults)\n      .map((tool) => ({\n        tool_name: tool.name,\n        match_score: 1.0,\n        matched_field: 'name',\n        snippet: tool.description.substring(0, 100) || tool.name,\n      }));\n\n    return {\n      tool_references: allTools,\n      total_tools_searched: tools.length,\n      pattern_used: query,\n    };\n  }\n\n  const documents = tools.map((tool) => createToolDocument(tool, fields));\n  const scores = BM25(documents, queryTokens, { k1: 1.5, b: 0.75 }) as number[];\n\n  const maxScore = Math.max(...scores.filter((s) => s > 0), 1);\n  const queryLower = query.toLowerCase().trim();\n  const queryIdentifier = queryTokens.join('');\n  const matchesIdentifiers = fields.includes('name');\n\n  const results: Array<{\n    result: t.ToolSearchResult;\n    identifierPriority: number;\n  }> = [];\n  for (let i = 0; i < tools.length; i++) {\n    const score = scores[i];\n    const hasSearchScore = Number.isFinite(score) && score > 0;\n    let identifierPriority = 0;\n    let normalizedScore = hasSearchScore ? Math.min(score / maxScore, 1.0) : 0;\n\n    if (matchesIdentifiers) {\n      const rawBaseName = getBaseToolName(tools[i].name).toLowerCase();\n      const rawFullName = tools[i].name.toLowerCase();\n      const baseIdentifier = tokenize(rawBaseName).join('');\n      const fullIdentifier = tokenize(rawFullName).join('');\n\n      if (rawFullName === queryLower) {\n        identifierPriority = 4;\n        normalizedScore = 1.0;\n      } else if (rawBaseName === queryLower) {\n        identifierPriority = 3;\n        normalizedScore = 1.0;\n      } else if (\n        baseIdentifier === queryIdentifier ||\n        fullIdentifier === queryIdentifier\n      ) {\n        identifierPriority = 2;\n        normalizedScore = 1.0;\n      } else if (baseIdentifier.startsWith(queryIdentifier)) {\n        identifierPriority = 1;\n        normalizedScore = Math.max(normalizedScore, 0.95);\n      }\n    }\n\n    if (!hasSearchScore && identifierPriority === 0) continue;\n\n    const { field, snippet } = findMatchedField(tools[i], queryTokens, fields);\n    results.push({\n      result: {\n        tool_name: tools[i].name,\n        match_score: normalizedScore,\n        matched_field: field,\n        snippet,\n      },\n      identifierPriority,\n    });\n  }\n\n  results.sort(\n    (a, b) =>\n      b.identifierPriority - a.identifierPriority ||\n      b.result.match_score - a.result.match_score\n  );\n  const topResults = results.slice(0, maxResults).map(({ result }) => result);\n\n  return {\n    tool_references: topResults,\n    total_tools_searched: tools.length,\n    pattern_used: query,\n  };\n}\n\n/**\n * Generates the JavaScript search script to be executed in the sandbox.\n * Uses plain JavaScript for maximum compatibility with the Code API.\n * @param deferredTools - Array of tool metadata to search through\n * @param fields - Which fields to search\n * @param maxResults - Maximum number of results to return\n * @param sanitizedPattern - The sanitized regex pattern\n * @returns The JavaScript code string\n */\nfunction generateSearchScript(\n  deferredTools: t.ToolMetadata[],\n  fields: string[],\n  maxResults: number,\n  sanitizedPattern: string\n): string {\n  const lines = [\n    '// Tool definitions (injected)',\n    'var tools = ' + JSON.stringify(deferredTools) + ';',\n    'var searchFields = ' + JSON.stringify(fields) + ';',\n    'var maxResults = ' + maxResults + ';',\n    'var pattern = ' + JSON.stringify(sanitizedPattern) + ';',\n    '',\n    '// Compile regex (pattern is sanitized client-side)',\n    'var regex;',\n    'try {',\n    '  regex = new RegExp(pattern, \\'i\\');',\n    '} catch (e) {',\n    '  regex = new RegExp(pattern.replace(/[.*+?^${}()[\\\\]\\\\\\\\|]/g, \"\\\\\\\\$&\"), \"i\");',\n    '}',\n    '',\n    '// Search logic',\n    'var results = [];',\n    '',\n    'for (var j = 0; j < tools.length; j++) {',\n    '  var tool = tools[j];',\n    '  var bestScore = 0;',\n    '  var matchedField = \\'\\';',\n    '  var snippet = \\'\\';',\n    '',\n    '  // Search name (highest priority)',\n    '  if (searchFields.indexOf(\\'name\\') >= 0 && regex.test(tool.name)) {',\n    '    bestScore = 0.95;',\n    '    matchedField = \\'name\\';',\n    '    snippet = tool.name;',\n    '  }',\n    '',\n    '  // Search description (medium priority)',\n    '  if (searchFields.indexOf(\\'description\\') >= 0 && tool.description && regex.test(tool.description)) {',\n    '    if (bestScore === 0) {',\n    '      bestScore = 0.75;',\n    '      matchedField = \\'description\\';',\n    '      snippet = tool.description.substring(0, 100);',\n    '    }',\n    '  }',\n    '',\n    '  // Search parameter names (lower priority)',\n    '  if (searchFields.indexOf(\\'parameters\\') >= 0 && tool.parameters && tool.parameters.properties) {',\n    '    var paramNames = Object.keys(tool.parameters.properties).join(\\' \\');',\n    '    if (regex.test(paramNames)) {',\n    '      if (bestScore === 0) {',\n    '        bestScore = 0.60;',\n    '        matchedField = \\'parameters\\';',\n    '        snippet = paramNames;',\n    '      }',\n    '    }',\n    '  }',\n    '',\n    '  if (bestScore > 0) {',\n    '    results.push({',\n    '      tool_name: tool.name,',\n    '      match_score: bestScore,',\n    '      matched_field: matchedField,',\n    '      snippet: snippet',\n    '    });',\n    '  }',\n    '}',\n    '',\n    '// Sort by score (descending) and limit results',\n    'results.sort(function(a, b) { return b.match_score - a.match_score; });',\n    'var topResults = results.slice(0, maxResults);',\n    '',\n    '// Output as JSON',\n    'console.log(JSON.stringify({',\n    '  tool_references: topResults.map(function(r) {',\n    '    return {',\n    '      tool_name: r.tool_name,',\n    '      match_score: r.match_score,',\n    '      matched_field: r.matched_field,',\n    '      snippet: r.snippet',\n    '    };',\n    '  }),',\n    '  total_tools_searched: tools.length,',\n    '  pattern_used: pattern',\n    '}));',\n  ];\n  return lines.join('\\n');\n}\n\n/**\n * Parses the search results from stdout JSON.\n * @param stdout - The stdout string containing JSON results\n * @returns Parsed search response\n */\nfunction parseSearchResults(stdout: string): t.ToolSearchResponse {\n  const jsonMatch = stdout.trim();\n  const parsed = JSON.parse(jsonMatch) as t.ToolSearchResponse;\n  return parsed;\n}\n\n/**\n * Formats search results as structured JSON for efficient parsing.\n * @param searchResponse - The parsed search response\n * @param nameFormat - Whether to show 'full' names (tool_mcp_server) or 'base' names (tool only)\n * @returns JSON string with search results\n */\nfunction formatSearchResults(\n  searchResponse: t.ToolSearchResponse,\n  nameFormat: t.McpNameFormat = 'full'\n): string {\n  const { tool_references, total_tools_searched, pattern_used } =\n    searchResponse;\n  const useFullName = nameFormat === 'full';\n\n  const output = {\n    found: tool_references.length,\n    tools: tool_references.map((ref) => ({\n      name: useFullName ? ref.tool_name : getBaseToolName(ref.tool_name),\n      score: Number(ref.match_score.toFixed(2)),\n      matched_in: ref.matched_field,\n      snippet: ref.snippet,\n    })),\n    total_searched: total_tools_searched,\n    query: pattern_used,\n  };\n\n  return JSON.stringify(output, null, 2);\n}\n\n/**\n * Extracts the base tool name (without MCP server suffix) from a full tool name.\n * @param toolName - The full tool name\n * @returns The base tool name without server suffix\n */\nfunction getBaseToolName(toolName: string): string {\n  const delimiterIndex = toolName.indexOf(Constants.MCP_DELIMITER);\n  if (delimiterIndex === -1) {\n    return toolName;\n  }\n  return toolName.substring(0, delimiterIndex);\n}\n\n/**\n * Checks whether a tool has any defined parameters in its JSON schema.\n * @param parameters - The tool's JSON schema parameters\n * @returns true if the tool has at least one parameter property\n */\nfunction hasParams(parameters?: t.JsonSchemaType): boolean {\n  return (\n    parameters?.properties != null &&\n    Object.keys(parameters.properties).length > 0\n  );\n}\n\n/**\n * Generates a compact listing of deferred tools grouped by server.\n * Format: \"server: tool1, tool2(\\u2026), tool3\"\n * Tools with parameters are annotated with (\\u2026) to signal\n * that the LLM should discover the schema via tool_search before calling.\n * Non-MCP tools are grouped under \"other\".\n * @param toolRegistry - The tool registry\n * @param onlyDeferred - Whether to only include deferred tools\n * @returns Formatted string with tools grouped by server\n */\nfunction getDeferredToolsListing(\n  toolRegistry: t.LCToolRegistry | undefined,\n  onlyDeferred: boolean\n): string {\n  if (!toolRegistry) {\n    return '';\n  }\n\n  const toolsByServer: Record<string, string[]> = {};\n\n  for (const lcTool of toolRegistry.values()) {\n    if (onlyDeferred && lcTool.defer_loading !== true) {\n      continue;\n    }\n\n    const toolName = lcTool.name;\n    const serverName = extractMcpServerName(toolName) ?? 'other';\n    const baseName = getBaseToolName(toolName);\n    const displayName = hasParams(lcTool.parameters)\n      ? `${baseName}(\\u2026)`\n      : baseName;\n\n    if (!(serverName in toolsByServer)) {\n      toolsByServer[serverName] = [];\n    }\n    toolsByServer[serverName].push(displayName);\n  }\n\n  const serverNames = Object.keys(toolsByServer).sort((a, b) => {\n    if (a === 'other') return 1;\n    if (b === 'other') return -1;\n    return a.localeCompare(b);\n  });\n\n  if (serverNames.length === 0) {\n    return '';\n  }\n\n  const lines = serverNames.map(\n    (server) => `${server}: ${toolsByServer[server].join(', ')}`\n  );\n\n  return lines.join('\\n');\n}\n\n/**\n * Formats a server listing response as structured JSON.\n * NOTE: This is a PREVIEW only - tools are NOT discovered/loaded.\n * @param tools - Array of tool metadata from the server(s)\n * @param serverNames - The MCP server name(s)\n * @param nameFormat - Whether to show 'full' names (tool_mcp_server) or 'base' names (tool only)\n * @returns JSON string showing all tools grouped by server\n */\nfunction formatServerListing(\n  tools: t.ToolMetadata[],\n  serverNames: string | string[],\n  nameFormat: t.McpNameFormat = 'full'\n): string {\n  const servers = Array.isArray(serverNames) ? serverNames : [serverNames];\n  const useFullName = nameFormat === 'full';\n\n  if (tools.length === 0) {\n    return JSON.stringify(\n      {\n        listing_mode: true,\n        servers,\n        total_tools: 0,\n        tools_by_server: {},\n        hint: 'No tools found from the specified MCP server(s).',\n      },\n      null,\n      2\n    );\n  }\n\n  const toolsByServer: Record<\n    string,\n    Array<{ name: string; description: string }>\n  > = {};\n  for (const tool of tools) {\n    const server = extractMcpServerName(tool.name) ?? 'unknown';\n    if (!(server in toolsByServer)) {\n      toolsByServer[server] = [];\n    }\n    toolsByServer[server].push({\n      name: useFullName ? tool.name : getBaseToolName(tool.name),\n      description:\n        tool.description.length > 100\n          ? tool.description.substring(0, 97) + '...'\n          : tool.description,\n    });\n  }\n\n  const exampleToolName = useFullName\n    ? (tools[0]?.name ?? 'tool_name')\n    : getBaseToolName(tools[0]?.name ?? 'tool_name');\n\n  const output = {\n    listing_mode: true,\n    servers,\n    total_tools: tools.length,\n    tools_by_server: toolsByServer,\n    hint: `To use a tool, search for it by name (e.g., query: \"${exampleToolName}\") to load it.`,\n  };\n\n  return JSON.stringify(output, null, 2);\n}\n\n/**\n * Creates a Tool Search tool for discovering tools from a large registry.\n *\n * This tool enables AI agents to dynamically discover tools from a large library\n * without loading all tool definitions into the LLM context window. The agent\n * can search for relevant tools on-demand.\n *\n * **Modes:**\n * - `code_interpreter` (default): Uses external sandbox for regex search. Safer for complex patterns.\n * - `local`: Uses safe substring matching locally. No network call, faster, completely safe from ReDoS.\n *\n * The tool registry can be provided either:\n * 1. At initialization time via params.toolRegistry\n * 2. At runtime via config.configurable.toolRegistry when invoking\n *\n * @param params - Configuration parameters for the tool (toolRegistry is optional)\n * @returns A LangChain DynamicStructuredTool for tool searching\n *\n * @example\n * // Option 1: Code interpreter mode (regex via sandbox)\n * const tool = createToolSearch({ toolRegistry });\n * await tool.invoke({ query: 'expense.*report' });\n *\n * @example\n * // Option 2: Local mode (safe substring search)\n * const tool = createToolSearch({ mode: 'local', toolRegistry });\n * await tool.invoke({ query: 'expense' });\n */\nfunction createToolSearch(\n  initParams: t.ToolSearchParams = {}\n): DynamicStructuredTool {\n  const mode: t.ToolSearchMode = initParams.mode ?? 'code_interpreter';\n  const defaultOnlyDeferred = initParams.onlyDeferred ?? true;\n  const mcpNameFormat: t.McpNameFormat = initParams.mcpNameFormat ?? 'full';\n  const schema = createToolSearchSchema(mode);\n\n  const baseEndpoint = initParams.baseUrl ?? getCodeBaseURL();\n  const EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\n  const deferredToolsListing = getDeferredToolsListing(\n    initParams.toolRegistry,\n    defaultOnlyDeferred\n  );\n\n  const toolsListSection =\n    deferredToolsListing.length > 0\n      ? `\n\nDeferred tools (search to load; \\u2026 = has params, search first):\n${deferredToolsListing}`\n      : '';\n\n  const mcpNote =\n    deferredToolsListing.includes(Constants.MCP_DELIMITER) ||\n    deferredToolsListing.split('\\n').some((line) => !line.startsWith('other:'))\n      ? `\n- MCP tools use format: toolName${Constants.MCP_DELIMITER}serverName\n- Use mcp_server param to filter by server`\n      : '';\n\n  const description =\n    mode === 'local'\n      ? `\nSearches deferred tools using BM25 ranking. Multi-word queries supported.\n${mcpNote}${toolsListSection}\n`.trim()\n      : `\nSearches deferred tools by regex pattern.\n${mcpNote}${toolsListSection}\n`.trim();\n\n  return tool(\n    async (rawParams, config) => {\n      const params = rawParams as ToolSearchParams;\n      const {\n        query = '',\n        fields = ['name', 'description'],\n        max_results = DEFAULT_MAX_RESULTS,\n        mcp_server,\n      } = params;\n\n      const {\n        toolRegistry: paramToolRegistry,\n        onlyDeferred: paramOnlyDeferred,\n        mcpServer: paramMcpServer,\n      } = config.toolCall ?? {};\n\n      const toolRegistry = paramToolRegistry ?? initParams.toolRegistry;\n      const onlyDeferred =\n        paramOnlyDeferred !== undefined\n          ? paramOnlyDeferred\n          : defaultOnlyDeferred;\n      const rawServerFilter =\n        mcp_server ?? paramMcpServer ?? initParams.mcpServer;\n      const serverFilters = normalizeServerFilter(rawServerFilter);\n      const hasServerFilter = serverFilters.length > 0;\n\n      if (toolRegistry == null) {\n        return [\n          'Error: No tool registry provided. Configure toolRegistry at agent level or initialization.',\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: query,\n              error: 'No tool registry provided',\n            },\n          },\n        ];\n      }\n\n      const toolsArray: t.LCTool[] = Array.from(toolRegistry.values());\n      const deferredTools: t.ToolMetadata[] = toolsArray\n        .filter((lcTool) => {\n          if (onlyDeferred === true && lcTool.defer_loading !== true) {\n            return false;\n          }\n          if (\n            hasServerFilter &&\n            !isFromAnyMcpServer(lcTool.name, serverFilters)\n          ) {\n            return false;\n          }\n          return true;\n        })\n        .map((lcTool) => ({\n          name: lcTool.name,\n          description: lcTool.description ?? '',\n          parameters: simplifyParametersForSearch(lcTool.parameters),\n        }));\n\n      if (deferredTools.length === 0) {\n        const serverMsg = hasServerFilter\n          ? ` from MCP server(s): ${serverFilters.join(', ')}`\n          : '';\n        return [\n          `No tools available to search${serverMsg}. The tool registry is empty or no matching deferred tools are registered.`,\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: query,\n              mcp_server: serverFilters,\n            },\n          },\n        ];\n      }\n\n      const isServerListing = hasServerFilter && query === '';\n\n      if (isServerListing) {\n        const formattedOutput = formatServerListing(\n          deferredTools,\n          serverFilters,\n          mcpNameFormat\n        );\n\n        return [\n          formattedOutput,\n          {\n            tool_references: [],\n            metadata: {\n              total_available: deferredTools.length,\n              mcp_server: serverFilters,\n              listing_mode: true,\n            },\n          },\n        ];\n      }\n\n      if (mode === 'local') {\n        const searchResponse = performLocalSearch(\n          deferredTools,\n          query,\n          fields,\n          max_results\n        );\n        const formattedOutput = formatSearchResults(\n          searchResponse,\n          mcpNameFormat\n        );\n\n        return [\n          formattedOutput,\n          {\n            tool_references: searchResponse.tool_references,\n            metadata: {\n              total_searched: searchResponse.total_tools_searched,\n              pattern: searchResponse.pattern_used,\n              mcp_server: serverFilters.length > 0 ? serverFilters : undefined,\n            },\n          },\n        ];\n      }\n\n      const { safe: sanitizedPattern, wasEscaped } = sanitizeRegex(query);\n      let warningMessage = '';\n      if (wasEscaped) {\n        warningMessage =\n          'Note: The provided pattern was converted to a literal search for safety.\\n\\n';\n      }\n\n      const searchScript = generateSearchScript(\n        deferredTools,\n        fields,\n        max_results,\n        sanitizedPattern\n      );\n\n      const postData = {\n        lang: 'js',\n        code: searchScript,\n        timeout: SEARCH_TIMEOUT,\n      };\n\n      try {\n        const fetchOptions: RequestInit = {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'User-Agent': 'LibreChat/1.0',\n          },\n          body: JSON.stringify(postData),\n        };\n\n        if (process.env.PROXY != null && process.env.PROXY !== '') {\n          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n        }\n\n        const response = await fetch(EXEC_ENDPOINT, fetchOptions);\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const result: t.ExecuteResult = await response.json();\n\n        if (result.stderr && result.stderr.trim()) {\n          // eslint-disable-next-line no-console\n          console.warn('[ToolSearch] stderr:', result.stderr);\n        }\n\n        if (!result.stdout || !result.stdout.trim()) {\n          return [\n            `${warningMessage}No tools matched the pattern \"${sanitizedPattern}\".\\nTotal tools searched: ${deferredTools.length}`,\n            {\n              tool_references: [],\n              metadata: {\n                total_searched: deferredTools.length,\n                pattern: sanitizedPattern,\n              },\n            },\n          ];\n        }\n\n        const searchResponse = parseSearchResults(result.stdout);\n        const formattedOutput = `${warningMessage}${formatSearchResults(searchResponse, mcpNameFormat)}`;\n\n        return [\n          formattedOutput,\n          {\n            tool_references: searchResponse.tool_references,\n            metadata: {\n              total_searched: searchResponse.total_tools_searched,\n              pattern: searchResponse.pattern_used,\n            },\n          },\n        ];\n      } catch (error) {\n        // eslint-disable-next-line no-console\n        console.error('[ToolSearch] Error:', error);\n\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return [\n          `Tool search failed: ${errorMessage}\\n\\nSuggestion: Try a simpler search pattern or search for specific tool names.`,\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: sanitizedPattern,\n              error: errorMessage,\n            },\n          },\n        ];\n      }\n    },\n    {\n      name: Constants.TOOL_SEARCH,\n      description,\n      schema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport {\n  createToolSearch,\n  performLocalSearch,\n  extractMcpServerName,\n  isFromMcpServer,\n  isFromAnyMcpServer,\n  normalizeServerFilter,\n  getAvailableMcpServers,\n  getDeferredToolsListing,\n  getBaseToolName,\n  formatServerListing,\n  sanitizeRegex,\n  escapeRegexSpecialChars,\n  isDangerousPattern,\n  countNestedGroups,\n  hasNestedQuantifiers,\n};\n"],"mappings":";;;;;;;;;;AAUA,SAAS,kBAA0B;CACjC,MAAM,MAAM;CAGZ,IAAI,OAAO,QAAQ,YAAY,OAAO;CACtC,IAAI,OAAO,IAAI,YAAY,YAAY,OAAO,IAAI;CAClD,IAAI,IAAI,WAAW,QAAQ,OAAO,IAAI,QAAQ,YAAY,YACxD,OAAO,IAAI,QAAQ;CACrB,MAAM,IAAI,MAAM,uDAAuD;AACzE;AAEA,MAAM,OAAO,gBAAgB;AAS7B,OAAO;;AAGP,MAAM,qBAAqB;AAE3B,MAAa,qBAAA;AAEb,MAAa,4BACX;AAEF,MAAM,0BACJ;AACF,MAAM,0BACJ;AACF,MAAM,qBACJ;AACF,MAAM,0BAA0B;AAChC,MAAM,sBAAsB;AAC5B,MAAM,yBACJ;AAEF,MAAa,uBAAuB;CAClC,MAAM;CACN,YAAY;EACV,QAAQ,EAAE,GAAG,gBAAgB;EAC7B,OAAO;GACL,MAAM;GACN,WAAW;GACX,SAAS;GACT,aAAa;EACf;EACA,QAAQ;GACN,MAAM;GACN,OAAO;IAAE,MAAM;IAAU,MAAM;KAAC;KAAQ;KAAe;IAAY;GAAE;GACrE,SAAS,CAAC,QAAQ,aAAa;GAC/B,aAAa;EACf;EACA,aAAa;GACX,MAAM;GACN,SAAS;GACT,SAAS;GACT,SAAS;GACT,aAAa;EACf;EACA,YAAY;GACV,OAAO,CAAC,EAAE,MAAM,SAAS,GAAG;IAAE,MAAM;IAAS,OAAO,EAAE,MAAM,SAAS;GAAE,CAAC;GACxE,aAAa;EACf;CACF;CACA,UAAU,CAAC;AACb;AAEA,MAAa,2BAA2B;CACtC,MAAM;CACN,aAAa;CACb,QAAQ;AACV;;AAGA,MAAM,uBAAuB;;AAG7B,MAAM,iBAAiB;;;;;;AAsBvB,SAAS,uBAAuB,MAA0C;CACxE,MAAM,mBACJ,SAAS,UAAU,0BAA0B;CAE/C,OAAO;EACL,MAAM;EACN,YAAY;GACV,QAAQ,EAAE,GAAG,gBAAgB;GAC7B,OAAO;IACL,MAAM;IACN,WAAW;IACX,SAAS;IACT,aAAa;GACf;GACA,QAAQ;IACN,MAAM;IACN,OAAO;KAAE,MAAM;KAAU,MAAM;MAAC;MAAQ;MAAe;KAAY;IAAE;IACrE,SAAS,CAAC,QAAQ,aAAa;IAC/B,aAAa;GACf;GACA,aAAa;IACX,MAAM;IACN,SAAS;IACT,SAAS;IACT,SAAS;IACT,aAAa;GACf;GACA,YAAY;IACV,OAAO,CACL,EAAE,MAAM,SAAS,GACjB;KAAE,MAAM;KAAS,OAAO,EAAE,MAAM,SAAS;IAAE,CAC7C;IACA,aAAa;GACf;EACF;EACA,UAAU,CAAC;CACb;AACF;;;;;;;AAQA,SAAS,qBAAqB,UAAsC;CAClE,MAAM,iBAAiB,SAAS,QAAA,OAA+B;CAC/D,IAAI,mBAAmB,IACrB;CAEF,OAAO,SAAS,UAAU,iBAAA,CAA+C;AAC3E;;;;;;;AAQA,SAAS,gBAAgB,UAAkB,YAA6B;CAEtE,OADmB,qBAAqB,QACxB,MAAM;AACxB;;;;;;;AAQA,SAAS,mBAAmB,UAAkB,aAAgC;CAC5E,MAAM,aAAa,qBAAqB,QAAQ;CAChD,IAAI,eAAe,KAAA,GACjB,OAAO;CAET,OAAO,YAAY,SAAS,UAAU;AACxC;;;;;;AAOA,SAAS,sBACP,cACU;CACV,IAAI,iBAAiB,KAAA,GACnB,OAAO,CAAC;CAEV,IAAI,OAAO,iBAAiB,UAC1B,OAAO,iBAAiB,KAAK,CAAC,IAAI,CAAC,YAAY;CAEjD,OAAO,aAAa,QAAQ,MAAM,MAAM,EAAE;AAC5C;;;;;;;AAQA,SAAS,uBACP,cACA,eAAwB,MACd;CACV,IAAI,CAAC,cACH,OAAO,CAAC;CAGV,MAAM,0BAAU,IAAI,IAAY;CAChC,KAAK,MAAM,GAAG,YAAY,cAAc;EACtC,IAAI,gBAAgB,QAAQ,kBAAkB,MAC5C;EAEF,MAAM,SAAS,qBAAqB,QAAQ,IAAI;EAChD,IAAI,WAAW,KAAA,KAAa,WAAW,IACrC,QAAQ,IAAI,MAAM;CAEtB;CAEA,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,KAAK;AAClC;;;;;;AAOA,SAAS,wBAAwB,SAAyB;CACxD,OAAO,QAAQ,QAAQ,uBAAuB,MAAM;AACtD;;;;;;AAOA,SAAS,kBAAkB,SAAyB;CAClD,IAAI,WAAW;CACf,IAAI,eAAe;CAEnB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAClC,IAAI,QAAQ,OAAO,QAAQ,MAAM,KAAK,QAAQ,IAAI,OAAO,OAAO;EAC9D;EACA,WAAW,KAAK,IAAI,UAAU,YAAY;CAC5C,OAAO,IAAI,QAAQ,OAAO,QAAQ,MAAM,KAAK,QAAQ,IAAI,OAAO,OAC9D,eAAe,KAAK,IAAI,GAAG,eAAe,CAAC;CAI/C,OAAO;AACT;;;;;;;AAQA,SAAS,qBAAqB,SAA0B;CAEtD,OAAO,0BAAwB,KAAK,OAAO;AAC7C;;;;;;AAOA,SAAS,mBAAmB,SAA0B;CACpD,IAAI,qBAAqB,OAAO,GAC9B,OAAO;CAGT,IAAI,kBAAkB,OAAO,IAAI,sBAC/B,OAAO;CAaT,KAAK,MAAM,aAAa;EATtB;EACA;EACA;EACA;EACA;EACA;EACA;CAGsC,GACtC,IAAI,UAAU,KAAK,OAAO,GACxB,OAAO;CAIX,OAAO;AACT;;;;;;;AAQA,SAAS,cAAc,SAAwD;CAC7E,IAAI,mBAAmB,OAAO,GAC5B,OAAO;EACL,MAAM,wBAAwB,OAAO;EACrC,YAAY;CACd;CAGF,IAAI;EACF,IAAI,OAAO,OAAO;EAClB,OAAO;GAAE,MAAM;GAAS,YAAY;EAAM;CAC5C,QAAQ;EACN,OAAO;GACL,MAAM,wBAAwB,OAAO;GACrC,YAAY;EACd;CACF;AACF;;;;;;;AAQA,SAAS,4BACP,YAC8B;CAC9B,IAAI,CAAC,YACH;CAGF,IAAI,WAAW,YACb,OAAO;EACL,MAAM,WAAW;EACjB,YAAY,OAAO,YACjB,OAAO,QAAQ,WAAW,UAAU,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CAC1D,KACA,EAAE,MAAO,MAA2B,KAAK,CAC3C,CAAC,CACH;CACF;CAGF,OAAO,EAAE,MAAM,WAAW,KAAK;AACjC;;;;;AAMA,SAAS,iBAAiB,SAA2B;CACnD,MAAM,cAAc,QACjB,QAAQ,sBAAsB,OAAO,CAAC,CACtC,QAAQ,yBAAyB,OAAO,CAAC,CACzC,YAAY,CAAC,CACb,MAAM,KAAK,CAAC,CACZ,OAAO,OAAO;CAEjB,IAAI,YAAY,SAAS,GAAG,OAAO;CAEnC,MAAM,eAAyB,CAAC;CAChC,IAAI,SAAS;CACb,KAAK,MAAM,SAAS,aAAa;EAC/B,IAAI,MAAM,WAAW,GAAG;GACtB,UAAU;GACV;EACF;EACA,aAAa,KAAK,GAAG,SAAS,OAAO;EACrC,SAAS;CACX;CAEA,IAAI,UAAU,aAAa,SAAS,GAClC,aAAa,aAAa,SAAS,MAAM;CAE3C,OAAO,aAAa,SAAS,IAAI,eAAe,CAAC,MAAM;AACzD;;;;;;;AAQA,SAAS,SAAS,MAAwB;CACxC,OAAO,KACJ,MAAM,eAAe,CAAC,CACtB,OAAO,OAAO,CAAC,CACf,QAAQ,gBAAgB;AAC7B;;;;;;;AAQA,SAAS,mBAAmB,MAAsB,QAA0B;CAC1E,MAAM,QAAkB,CAAC;CAEzB,IAAI,OAAO,SAAS,MAAM,GAAG;EAC3B,MAAM,WAAW,KAAK,KAAK,QAAQ,MAAM,GAAG;EAC5C,MAAM,KAAK,UAAU,QAAQ;CAC/B;CAEA,IAAI,OAAO,SAAS,aAAa,KAAK,KAAK,aACzC,MAAM,KAAK,KAAK,WAAW;CAG7B,IAAI,OAAO,SAAS,YAAY,KAAK,KAAK,YAAY,YAAY;EAChE,MAAM,aAAa,OAAO,KAAK,KAAK,WAAW,UAAU,CAAC,CAAC,KAAK,GAAG;EACnE,MAAM,KAAK,UAAU;CACvB;CAEA,OAAO,SAAS,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG;AAC3C;;;;;;;;AASA,SAAS,iBACP,MACA,aACA,QACoC;CACpC,IAAI,OAAO,SAAS,MAAM,GAAG;EAC3B,MAAM,YAAY,KAAK,KAAK,YAAY;EACxC,KAAK,MAAM,SAAS,aAClB,IAAI,UAAU,SAAS,KAAK,GAC1B,OAAO;GAAE,OAAO;GAAQ,SAAS,KAAK;EAAK;CAGjD;CAEA,IAAI,OAAO,SAAS,aAAa,KAAK,KAAK,aAAa;EACtD,MAAM,YAAY,KAAK,YAAY,YAAY;EAC/C,KAAK,MAAM,SAAS,aAClB,IAAI,UAAU,SAAS,KAAK,GAC1B,OAAO;GACL,OAAO;GACP,SAAS,KAAK,YAAY,UAAU,GAAG,GAAG;EAC5C;CAGN;CAEA,IAAI,OAAO,SAAS,YAAY,KAAK,KAAK,YAAY,YAAY;EAChE,MAAM,aAAa,OAAO,KAAK,KAAK,WAAW,UAAU;EACzD,MAAM,aAAa,WAAW,KAAK,GAAG,CAAC,CAAC,YAAY;EACpD,KAAK,MAAM,SAAS,aAClB,IAAI,WAAW,SAAS,KAAK,GAC3B,OAAO;GAAE,OAAO;GAAc,SAAS,WAAW,KAAK,IAAI;EAAE;CAGnE;CAKA,OAAO;EAAE,OAAO;EAAW,SAHH,KAAK,cACzB,KAAK,YAAY,UAAU,GAAG,GAAG,IACjC,KAAK;CAC2C;AACtD;;;;;;;;;;;AAYA,SAAS,mBACP,OACA,OACA,QACA,YACsB;CACtB,IAAI,MAAM,WAAW,GACnB,OAAO;EACL,iBAAiB,CAAC;EAClB,sBAAsB;EACtB,cAAc;CAChB;CAGF,MAAM,cAAc,SAAS,KAAK;CAElC,IAAI,YAAY,WAAW,GAYzB,OAAO;EACL,iBAZe,MACd,MAAM,CAAC,CACP,MAAM,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC,CAAC,CAC5C,MAAM,GAAG,UAAU,CAAC,CACpB,KAAK,UAAU;GACd,WAAW,KAAK;GAChB,aAAa;GACb,eAAe;GACf,SAAS,KAAK,YAAY,UAAU,GAAG,GAAG,KAAK,KAAK;EACtD,EAGwB;EACxB,sBAAsB,MAAM;EAC5B,cAAc;CAChB;CAIF,MAAM,SAAS,KADG,MAAM,KAAK,SAAS,mBAAmB,MAAM,MAAM,CACzC,GAAG,aAAa;EAAE,IAAI;EAAK,GAAG;CAAK,CAAC;CAEhE,MAAM,WAAW,KAAK,IAAI,GAAG,OAAO,QAAQ,MAAM,IAAI,CAAC,GAAG,CAAC;CAC3D,MAAM,aAAa,MAAM,YAAY,CAAC,CAAC,KAAK;CAC5C,MAAM,kBAAkB,YAAY,KAAK,EAAE;CAC3C,MAAM,qBAAqB,OAAO,SAAS,MAAM;CAEjD,MAAM,UAGD,CAAC;CACN,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,QAAQ,OAAO;EACrB,MAAM,iBAAiB,OAAO,SAAS,KAAK,KAAK,QAAQ;EACzD,IAAI,qBAAqB;EACzB,IAAI,kBAAkB,iBAAiB,KAAK,IAAI,QAAQ,UAAU,CAAG,IAAI;EAEzE,IAAI,oBAAoB;GACtB,MAAM,cAAc,gBAAgB,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,YAAY;GAC/D,MAAM,cAAc,MAAM,EAAE,CAAC,KAAK,YAAY;GAC9C,MAAM,iBAAiB,SAAS,WAAW,CAAC,CAAC,KAAK,EAAE;GACpD,MAAM,iBAAiB,SAAS,WAAW,CAAC,CAAC,KAAK,EAAE;GAEpD,IAAI,gBAAgB,YAAY;IAC9B,qBAAqB;IACrB,kBAAkB;GACpB,OAAO,IAAI,gBAAgB,YAAY;IACrC,qBAAqB;IACrB,kBAAkB;GACpB,OAAO,IACL,mBAAmB,mBACnB,mBAAmB,iBACnB;IACA,qBAAqB;IACrB,kBAAkB;GACpB,OAAO,IAAI,eAAe,WAAW,eAAe,GAAG;IACrD,qBAAqB;IACrB,kBAAkB,KAAK,IAAI,iBAAiB,GAAI;GAClD;EACF;EAEA,IAAI,CAAC,kBAAkB,uBAAuB,GAAG;EAEjD,MAAM,EAAE,OAAO,YAAY,iBAAiB,MAAM,IAAI,aAAa,MAAM;EACzE,QAAQ,KAAK;GACX,QAAQ;IACN,WAAW,MAAM,EAAE,CAAC;IACpB,aAAa;IACb,eAAe;IACf;GACF;GACA;EACF,CAAC;CACH;CAEA,QAAQ,MACL,GAAG,MACF,EAAE,qBAAqB,EAAE,sBACzB,EAAE,OAAO,cAAc,EAAE,OAAO,WACpC;CAGA,OAAO;EACL,iBAHiB,QAAQ,MAAM,GAAG,UAAU,CAAC,CAAC,KAAK,EAAE,aAAa,MAGxC;EAC1B,sBAAsB,MAAM;EAC5B,cAAc;CAChB;AACF;;;;;;;;;;AAWA,SAAS,qBACP,eACA,QACA,YACA,kBACQ;CAiFR,OAAO;EA/EL;EACA,iBAAiB,KAAK,UAAU,aAAa,IAAI;EACjD,wBAAwB,KAAK,UAAU,MAAM,IAAI;EACjD,sBAAsB,aAAa;EACnC,mBAAmB,KAAK,UAAU,gBAAgB,IAAI;EACtD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CAES,CAAC,CAAC,KAAK,IAAI;AACxB;;;;;;AAOA,SAAS,mBAAmB,QAAsC;CAChE,MAAM,YAAY,OAAO,KAAK;CAE9B,OADe,KAAK,MAAM,SACd;AACd;;;;;;;AAQA,SAAS,oBACP,gBACA,aAA8B,QACtB;CACR,MAAM,EAAE,iBAAiB,sBAAsB,iBAC7C;CACF,MAAM,cAAc,eAAe;CAEnC,MAAM,SAAS;EACb,OAAO,gBAAgB;EACvB,OAAO,gBAAgB,KAAK,SAAS;GACnC,MAAM,cAAc,IAAI,YAAY,gBAAgB,IAAI,SAAS;GACjE,OAAO,OAAO,IAAI,YAAY,QAAQ,CAAC,CAAC;GACxC,YAAY,IAAI;GAChB,SAAS,IAAI;EACf,EAAE;EACF,gBAAgB;EAChB,OAAO;CACT;CAEA,OAAO,KAAK,UAAU,QAAQ,MAAM,CAAC;AACvC;;;;;;AAOA,SAAS,gBAAgB,UAA0B;CACjD,MAAM,iBAAiB,SAAS,QAAA,OAA+B;CAC/D,IAAI,mBAAmB,IACrB,OAAO;CAET,OAAO,SAAS,UAAU,GAAG,cAAc;AAC7C;;;;;;AAOA,SAAS,UAAU,YAAwC;CACzD,OACE,YAAY,cAAc,QAC1B,OAAO,KAAK,WAAW,UAAU,CAAC,CAAC,SAAS;AAEhD;;;;;;;;;;;AAYA,SAAS,wBACP,cACA,cACQ;CACR,IAAI,CAAC,cACH,OAAO;CAGT,MAAM,gBAA0C,CAAC;CAEjD,KAAK,MAAM,UAAU,aAAa,OAAO,GAAG;EAC1C,IAAI,gBAAgB,OAAO,kBAAkB,MAC3C;EAGF,MAAM,WAAW,OAAO;EACxB,MAAM,aAAa,qBAAqB,QAAQ,KAAK;EACrD,MAAM,WAAW,gBAAgB,QAAQ;EACzC,MAAM,cAAc,UAAU,OAAO,UAAU,IAC3C,GAAG,SAAS,YACZ;EAEJ,IAAI,EAAE,cAAc,gBAClB,cAAc,cAAc,CAAC;EAE/B,cAAc,WAAW,CAAC,KAAK,WAAW;CAC5C;CAEA,MAAM,cAAc,OAAO,KAAK,aAAa,CAAC,CAAC,MAAM,GAAG,MAAM;EAC5D,IAAI,MAAM,SAAS,OAAO;EAC1B,IAAI,MAAM,SAAS,OAAO;EAC1B,OAAO,EAAE,cAAc,CAAC;CAC1B,CAAC;CAED,IAAI,YAAY,WAAW,GACzB,OAAO;CAOT,OAJc,YAAY,KACvB,WAAW,GAAG,OAAO,IAAI,cAAc,OAAO,CAAC,KAAK,IAAI,GAGhD,CAAC,CAAC,KAAK,IAAI;AACxB;;;;;;;;;AAUA,SAAS,oBACP,OACA,aACA,aAA8B,QACtB;CACR,MAAM,UAAU,MAAM,QAAQ,WAAW,IAAI,cAAc,CAAC,WAAW;CACvE,MAAM,cAAc,eAAe;CAEnC,IAAI,MAAM,WAAW,GACnB,OAAO,KAAK,UACV;EACE,cAAc;EACd;EACA,aAAa;EACb,iBAAiB,CAAC;EAClB,MAAM;CACR,GACA,MACA,CACF;CAGF,MAAM,gBAGF,CAAC;CACL,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,SAAS,qBAAqB,KAAK,IAAI,KAAK;EAClD,IAAI,EAAE,UAAU,gBACd,cAAc,UAAU,CAAC;EAE3B,cAAc,OAAO,CAAC,KAAK;GACzB,MAAM,cAAc,KAAK,OAAO,gBAAgB,KAAK,IAAI;GACzD,aACE,KAAK,YAAY,SAAS,MACtB,KAAK,YAAY,UAAU,GAAG,EAAE,IAAI,QACpC,KAAK;EACb,CAAC;CACH;CAEA,MAAM,kBAAkB,cACnB,MAAM,EAAE,EAAE,QAAQ,cACnB,gBAAgB,MAAM,EAAE,EAAE,QAAQ,WAAW;CAEjD,MAAM,SAAS;EACb,cAAc;EACd;EACA,aAAa,MAAM;EACnB,iBAAiB;EACjB,MAAM,uDAAuD,gBAAgB;CAC/E;CAEA,OAAO,KAAK,UAAU,QAAQ,MAAM,CAAC;AACvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAS,iBACP,aAAiC,CAAC,GACX;CACvB,MAAM,OAAyB,WAAW,QAAQ;CAClD,MAAM,sBAAsB,WAAW,gBAAgB;CACvD,MAAM,gBAAiC,WAAW,iBAAiB;CACnE,MAAM,SAAS,uBAAuB,IAAI;CAG1C,MAAM,gBAAgB,GADD,WAAW,WAAW,eAAe,EACpB;CAEtC,MAAM,uBAAuB,wBAC3B,WAAW,cACX,mBACF;CAEA,MAAM,mBACJ,qBAAqB,SAAS,IAC1B;;;EAGN,yBACM;CAEN,MAAM,UACJ,qBAAqB,SAAA,OAAgC,KACrD,qBAAqB,MAAM,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC,KAAK,WAAW,QAAQ,CAAC,IACtE;;8CAGA;CAaN,OAAO,KACL,OAAO,WAAW,WAAW;EAE3B,MAAM,EACJ,QAAQ,IACR,SAAS,CAAC,QAAQ,aAAa,GAC/B,cAAc,qBACd,eACEA;EAEJ,MAAM,EACJ,cAAc,mBACd,cAAc,mBACd,WAAW,mBACT,OAAO,YAAY,CAAC;EAExB,MAAM,eAAe,qBAAqB,WAAW;EACrD,MAAM,eACJ,sBAAsB,KAAA,IAClB,oBACA;EAGN,MAAM,gBAAgB,sBADpB,cAAc,kBAAkB,WAAW,SACc;EAC3D,MAAM,kBAAkB,cAAc,SAAS;EAE/C,IAAI,gBAAgB,MAClB,OAAO,CACL,8FACA;GACE,iBAAiB,CAAC;GAClB,UAAU;IACR,gBAAgB;IAChB,SAAS;IACT,OAAO;GACT;EACF,CACF;EAIF,MAAM,gBADyB,MAAM,KAAK,aAAa,OAAO,CACb,CAAC,CAC/C,QAAQ,WAAW;GAClB,IAAI,iBAAiB,QAAQ,OAAO,kBAAkB,MACpD,OAAO;GAET,IACE,mBACA,CAAC,mBAAmB,OAAO,MAAM,aAAa,GAE9C,OAAO;GAET,OAAO;EACT,CAAC,CAAC,CACD,KAAK,YAAY;GAChB,MAAM,OAAO;GACb,aAAa,OAAO,eAAe;GACnC,YAAY,4BAA4B,OAAO,UAAU;EAC3D,EAAE;EAEJ,IAAI,cAAc,WAAW,GAI3B,OAAO,CACL,+BAJgB,kBACd,wBAAwB,cAAc,KAAK,IAAI,MAC/C,GAEuC,6EACzC;GACE,iBAAiB,CAAC;GAClB,UAAU;IACR,gBAAgB;IAChB,SAAS;IACT,YAAY;GACd;EACF,CACF;EAKF,IAFwB,mBAAmB,UAAU,IASnD,OAAO,CANiB,oBACtB,eACA,eACA,aAIc,GACd;GACE,iBAAiB,CAAC;GAClB,UAAU;IACR,iBAAiB,cAAc;IAC/B,YAAY;IACZ,cAAc;GAChB;EACF,CACF;EAGF,IAAI,SAAS,SAAS;GACpB,MAAM,iBAAiB,mBACrB,eACA,OACA,QACA,WACF;GAMA,OAAO,CALiB,oBACtB,gBACA,aAIc,GACd;IACE,iBAAiB,eAAe;IAChC,UAAU;KACR,gBAAgB,eAAe;KAC/B,SAAS,eAAe;KACxB,YAAY,cAAc,SAAS,IAAI,gBAAgB,KAAA;IACzD;GACF,CACF;EACF;EAEA,MAAM,EAAE,MAAM,kBAAkB,eAAe,cAAc,KAAK;EAClE,IAAI,iBAAiB;EACrB,IAAI,YACF,iBACE;EAUJ,MAAM,WAAW;GACf,MAAM;GACN,MATmB,qBACnB,eACA,QACA,aACA,gBAKiB;GACjB,SAAS;EACX;EAEA,IAAI;GACF,MAAM,eAA4B;IAChC,QAAQ;IACR,SAAS;KACP,gBAAgB;KAChB,cAAc;IAChB;IACA,MAAM,KAAK,UAAU,QAAQ;GAC/B;GAEA,IAAI,QAAQ,IAAI,SAAS,QAAQ,QAAQ,IAAI,UAAU,IACrD,aAAa,QAAQ,IAAI,gBAAgB,QAAQ,IAAI,KAAK;GAG5D,MAAM,WAAW,MAAM,MAAM,eAAe,YAAY;GACxD,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,MAAM,uBAAuB,SAAS,QAAQ;GAG1D,MAAM,SAA0B,MAAM,SAAS,KAAK;GAEpD,IAAI,OAAO,UAAU,OAAO,OAAO,KAAK,GAEtC,QAAQ,KAAK,wBAAwB,OAAO,MAAM;GAGpD,IAAI,CAAC,OAAO,UAAU,CAAC,OAAO,OAAO,KAAK,GACxC,OAAO,CACL,GAAG,eAAe,gCAAgC,iBAAiB,4BAA4B,cAAc,UAC7G;IACE,iBAAiB,CAAC;IAClB,UAAU;KACR,gBAAgB,cAAc;KAC9B,SAAS;IACX;GACF,CACF;GAGF,MAAM,iBAAiB,mBAAmB,OAAO,MAAM;GAGvD,OAAO,CACL,GAHyB,iBAAiB,oBAAoB,gBAAgB,aAAa,KAI3F;IACE,iBAAiB,eAAe;IAChC,UAAU;KACR,gBAAgB,eAAe;KAC/B,SAAS,eAAe;IAC1B;GACF,CACF;EACF,SAAS,OAAO;GAEd,QAAQ,MAAM,uBAAuB,KAAK;GAE1C,MAAM,eACJ,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GACvD,OAAO,CACL,uBAAuB,aAAa,kFACpC;IACE,iBAAiB,CAAC;IAClB,UAAU;KACR,gBAAgB;KAChB,SAAS;KACT,OAAO;IACT;GACF,CACF;EACF;CACF,GACA;EACE,MAAA;EACA,aAnOF,SAAS,UACL;;EAEN,UAAU,iBAAiB;EAC3B,KAAK,IACC;;EAEN,UAAU,iBAAiB;EAC3B,KAAK;EA4ND;EACA,gBAAA;CACF,CACF;AACF"}

package/dist/esm/tools/intentArg.mjs

@@ -0,0 +1,220 @@
+//#region src/tools/intentArg.ts
+/** Argument carrying the model-authored label for a tool call. */
+const INTENT_ARG = "intent";
+/** Model-facing instruction for the injected `intent` property. */
+const INTENT_DESCRIPTION = "ALWAYS write this field FIRST, before any other argument. One short sentence, present progressive, stating what this specific call is about to do: \"Searching for OAuth handling in the callback router\". It is shown to the user as the live status label for this call while it runs, so write it for a human reading a progress line. Do not restate the tool name. Do not exceed one sentence. When you make several calls to the same tool in one turn, each intent must distinguish that call from its siblings.";
+/**
+* Canonical (frozen) shape of the injected property. Always embed a COPY
+* (`{ ...INTENT_PROPERTY }`): LangChain's JSON-schema validator stamps a
+* `__absolute_uri__` marker onto every subschema it dereferences, which
+* throws on a frozen object — and a single shared instance would be stamped
+* with one schema's URI while embedded in many.
+*/
+const INTENT_PROPERTY = Object.freeze({
+	type: "string",
+	description: INTENT_DESCRIPTION
+});
+/**
+* Discriminates the intent LABEL property from a tool's own business
+* parameter that merely shares the name: the label contract always opens
+* with the same instruction. Removal/sanitize passes must never strip a
+* parameter the tool actually needs.
+*/
+function isIntentLabelProperty(property) {
+	if (property == null || typeof property !== "object") return false;
+	const record = property;
+	return record.type === "string" && typeof record.description === "string" && record.description.startsWith("ALWAYS write this field FIRST");
+}
+/**
+* Returns a copy of the parameters schema with `intent` prepended as the
+* FIRST property (object key order is insertion order and every provider
+* serializer preserves it — first key in the schema means first key in the
+* streamed input). Never mutates the input; no-op when the schema already
+* declares `intent`. The property is not added to `required`.
+*/
+function withIntent(parameters) {
+	const existingProps = parameters?.properties ?? {};
+	if ("intent" in existingProps) return parameters;
+	return {
+		...parameters,
+		type: "object",
+		properties: {
+			[INTENT_ARG]: { ...INTENT_PROPERTY },
+			...existingProps
+		}
+	};
+}
+/**
+* Coerces tool-call args to an object, parsing a stringified JSON object
+* (some providers deliver args as a string). Returns undefined otherwise.
+*/
+function coerceArgsObject(args) {
+	if (typeof args === "object" && args !== null && !Array.isArray(args)) return args;
+	if (typeof args === "string" && args.trim().startsWith("{")) try {
+		const parsed = JSON.parse(args);
+		if (parsed != null && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+	} catch {
+		return;
+	}
+}
+/**
+* Reads the model-authored intent from tool-call args (handles stringified
+* args). Returns undefined when absent, empty, or not a string.
+*/
+function readIntent(args) {
+	const value = coerceArgsObject(args)?.[INTENT_ARG];
+	if (typeof value !== "string") return;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+/**
+* Returns the args without the `intent` key so downstream consumers that did
+* not declare it never receive it. Parses stringified JSON object args;
+* returns the value unchanged when the key is absent.
+*/
+function stripIntent(args) {
+	const obj = coerceArgsObject(args);
+	if (!obj || !("intent" in obj)) return args;
+	const { [INTENT_ARG]: _omit, ...rest } = obj;
+	return rest;
+}
+/**
+* Leading-verb map for the mechanical outcome transform, keyed by the
+* lowercased first word of the intent. Deliberately small: an unknown leading
+* word leaves the intent unchanged rather than mangling it.
+*/
+const OUTCOME_VERB_MAP = new Map([
+	["searching", "Searched"],
+	["reading", "Read"],
+	["writing", "Wrote"],
+	["editing", "Edited"],
+	["running", "Ran"],
+	["creating", "Created"],
+	["checking", "Checked"],
+	["fetching", "Fetched"],
+	["listing", "Listed"],
+	["looking", "Looked"],
+	["building", "Built"],
+	["deleting", "Deleted"],
+	["updating", "Updated"],
+	["adding", "Added"],
+	["removing", "Removed"],
+	["verifying", "Verified"],
+	["analyzing", "Analyzed"],
+	["generating", "Generated"],
+	["delegating", "Delegated"],
+	["spawning", "Spawned"],
+	["compiling", "Compiled"],
+	["grepping", "Grepped"]
+]);
+function matchLeadingCase(replacement, original) {
+	if (original.charAt(0) === original.charAt(0).toLowerCase()) return replacement.charAt(0).toLowerCase() + replacement.slice(1);
+	return replacement;
+}
+function transformLeadingVerb(intent) {
+	const spaceIdx = intent.search(/\s/);
+	const leading = spaceIdx === -1 ? intent : intent.slice(0, spaceIdx);
+	const mapped = OUTCOME_VERB_MAP.get(leading.toLowerCase());
+	if (mapped == null) return intent;
+	return matchLeadingCase(mapped, leading) + intent.slice(leading.length);
+}
+/**
+* Resolves the settled label for a call from its model-authored `intent` and
+* the tool's result fields, in precedence order:
+*
+*  1. `outcome` — full replacement authored by the tool.
+*  2. `outcome_patch` — first occurrence of `from` in the intent replaced
+*     with `to` (case-sensitive); no-op when `from` is absent or empty.
+*  3. Mechanical transform — the leading word mapped present-progressive →
+*     past tense; an unknown leading word leaves the intent unchanged.
+*
+* Returns undefined when there is neither an intent nor an outcome, so
+* callers fall back to their default label. Pure and dependency-free — host
+* UIs needing identical logic can import or mirror it.
+*/
+function applyOutcome(intent, result) {
+	const outcome = result?.outcome;
+	if (typeof outcome === "string" && outcome.trim() !== "") return outcome;
+	if (intent == null || intent === "") return;
+	const patch = result?.outcome_patch;
+	if (patch != null && patch.from !== "" && intent.includes(patch.from))
+ /** Replacement callback keeps `to` verbatim — a direct string second
+	*  argument would interpret `$&`/`$'`-style tokens in tool-authored
+	*  text (e.g. labels derived from shell syntax). */
+	return intent.replace(patch.from, () => patch.to);
+	return transformLeadingVerb(intent);
+}
+/**
+* Hard cap on an emitted outcome label. The label is a single progress line
+* in UI chrome; a tool that derives it from data (or a malformed patch)
+* must not be able to inflate completion events or persisted parts.
+*/
+const MAX_OUTCOME_CHARS = 256;
+function boundOutcomeLabel(label) {
+	if (label == null) return;
+	const singleLine = label.replace(/\s+/g, " ").trim();
+	if (singleLine === "") return;
+	if (singleLine.length <= MAX_OUTCOME_CHARS) return singleLine;
+	return `${singleLine.slice(0, MAX_OUTCOME_CHARS - 1)}…`;
+}
+/**
+* Resolves the settled label to emit on a completion event: only when the
+* tool actually authored `outcome`/`outcome_patch` fields. Returns undefined
+* otherwise — the mechanical transform of a bare intent is left to the host
+* so the wire never carries a label the host can derive itself. The result
+* is collapsed to a bounded single line before emission.
+*
+* For failed calls (`isError`), only tool-AUTHORED text may label the call:
+* an explicit `outcome`, or a patch whose `from` actually matches the
+* intent. An unmatched patch must not fall through to the mechanical
+* past-tense transform — wording drift in a failure patch would otherwise
+* render a success-looking label for an error.
+*/
+function resolveToolOutcome(args, fields, options) {
+	if (fields == null || fields.outcome == null && fields.outcome_patch == null) return;
+	if (options?.isError !== true) return boundOutcomeLabel(applyOutcome(readIntent(args), fields));
+	const outcome = fields.outcome;
+	if (typeof outcome === "string" && outcome.trim() !== "") return boundOutcomeLabel(outcome);
+	const intent = readIntent(args);
+	const patch = fields.outcome_patch;
+	if (intent != null && patch != null && patch.from !== "" && intent.includes(patch.from)) return boundOutcomeLabel(intent.replace(patch.from, () => patch.to));
+}
+/**
+* Reads the outcome fields off a tool-execution result: the typed
+* `outcome`/`outcome_patch` fields when present, else the artifact channel
+* (see {@link readOutcomeFields}) — so a `content_and_artifact` tool authors
+* its label the same way on the direct and event-driven paths.
+*/
+function outcomeFieldsFromResult(result) {
+	if (result.outcome != null || result.outcome_patch != null) return result;
+	return readOutcomeFields(result.artifact);
+}
+/**
+* Extracts validated `outcome`/`outcome_patch` fields from an arbitrary
+* value — the artifact channel through which an in-process
+* `content_and_artifact` tool authors its settled label. Returns undefined
+* when neither field is usable.
+*/
+function readOutcomeFields(source) {
+	if (source == null || typeof source !== "object" || Array.isArray(source)) return;
+	const record = source;
+	const outcome = typeof record.outcome === "string" && record.outcome.trim() !== "" ? record.outcome : void 0;
+	let outcome_patch;
+	const rawPatch = record.outcome_patch;
+	if (rawPatch != null && typeof rawPatch === "object" && !Array.isArray(rawPatch)) {
+		const patch = rawPatch;
+		if (typeof patch.from === "string" && typeof patch.to === "string") outcome_patch = {
+			from: patch.from,
+			to: patch.to
+		};
+	}
+	if (outcome == null && outcome_patch == null) return;
+	return {
+		outcome,
+		outcome_patch
+	};
+}
+//#endregion
+export { INTENT_ARG, INTENT_DESCRIPTION, INTENT_PROPERTY, applyOutcome, isIntentLabelProperty, outcomeFieldsFromResult, readIntent, readOutcomeFields, resolveToolOutcome, stripIntent, withIntent };
+
+//# sourceMappingURL=intentArg.mjs.map

package/dist/esm/tools/intentArg.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"intentArg.mjs","names":[],"sources":["../../../src/tools/intentArg.ts"],"sourcesContent":["/**\n * @fileoverview Tool intent labels.\n *\n * Lets a tool declare, as the FIRST property of its input schema, an `intent`\n * string: one model-authored sentence stating what that specific call is about\n * to do (\"Searching for OAuth handling in the callback router\"). Because the\n * property is first, it is the first key providers stream in the tool-call\n * args, so a host UI can render it as the call's live status label before the\n * rest of the args exist. When the call settles, {@link applyOutcome} edits\n * the sentence in place into its outcome form — a tool-supplied replacement\n * (`outcome`), a tool-supplied span edit (`outcome_patch`), or a mechanical\n * present-progressive→past-tense transform of the leading verb.\n *\n * The arg is always optional (never listed in `required`): the same schemas\n * are callable from programmatic tool calling, where no UI renders a label\n * and forcing generated code to fabricate one would be pure cost. Tool bodies\n * must call {@link stripIntent} before using their args so no tool receives a\n * parameter it did not declare.\n */\n\nimport type { JsonSchemaType, OutcomePatch } from '@/types';\n\n/** Argument carrying the model-authored label for a tool call. */\nexport const INTENT_ARG = 'intent';\n\n/** Model-facing instruction for the injected `intent` property. */\nexport const INTENT_DESCRIPTION =\n  'ALWAYS write this field FIRST, before any other argument. One short sentence, ' +\n  'present progressive, stating what this specific call is about to do: ' +\n  '\"Searching for OAuth handling in the callback router\". It is shown to the user ' +\n  'as the live status label for this call while it runs, so write it for a human ' +\n  'reading a progress line. Do not restate the tool name. Do not exceed one sentence. ' +\n  'When you make several calls to the same tool in one turn, each intent must ' +\n  'distinguish that call from its siblings.';\n\n/**\n * Canonical (frozen) shape of the injected property. Always embed a COPY\n * (`{ ...INTENT_PROPERTY }`): LangChain's JSON-schema validator stamps a\n * `__absolute_uri__` marker onto every subschema it dereferences, which\n * throws on a frozen object — and a single shared instance would be stamped\n * with one schema's URI while embedded in many.\n */\nexport const INTENT_PROPERTY: JsonSchemaType = Object.freeze<JsonSchemaType>({\n  type: 'string',\n  description: INTENT_DESCRIPTION,\n});\n\n/**\n * Discriminates the intent LABEL property from a tool's own business\n * parameter that merely shares the name: the label contract always opens\n * with the same instruction. Removal/sanitize passes must never strip a\n * parameter the tool actually needs.\n */\nexport function isIntentLabelProperty(property: unknown): boolean {\n  if (property == null || typeof property !== 'object') {\n    return false;\n  }\n  const record = property as { type?: unknown; description?: unknown };\n  return (\n    record.type === 'string' &&\n    typeof record.description === 'string' &&\n    record.description.startsWith('ALWAYS write this field FIRST')\n  );\n}\n\n/**\n * Returns a copy of the parameters schema with `intent` prepended as the\n * FIRST property (object key order is insertion order and every provider\n * serializer preserves it — first key in the schema means first key in the\n * streamed input). Never mutates the input; no-op when the schema already\n * declares `intent`. The property is not added to `required`.\n */\nexport function withIntent(parameters?: JsonSchemaType): JsonSchemaType {\n  const existingProps = parameters?.properties ?? {};\n  if (INTENT_ARG in existingProps) {\n    return parameters as JsonSchemaType;\n  }\n  return {\n    ...parameters,\n    type: 'object',\n    properties: { [INTENT_ARG]: { ...INTENT_PROPERTY }, ...existingProps },\n  };\n}\n\n/**\n * Coerces tool-call args to an object, parsing a stringified JSON object\n * (some providers deliver args as a string). Returns undefined otherwise.\n */\nfunction coerceArgsObject(args: unknown): Record<string, unknown> | undefined {\n  if (typeof args === 'object' && args !== null && !Array.isArray(args)) {\n    return args as Record<string, unknown>;\n  }\n  if (typeof args === 'string' && args.trim().startsWith('{')) {\n    try {\n      const parsed = JSON.parse(args) as unknown;\n      if (parsed != null && typeof parsed === 'object' && !Array.isArray(parsed)) {\n        return parsed as Record<string, unknown>;\n      }\n    } catch {\n      return undefined;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Reads the model-authored intent from tool-call args (handles stringified\n * args). Returns undefined when absent, empty, or not a string.\n */\nexport function readIntent(args: unknown): string | undefined {\n  const value = coerceArgsObject(args)?.[INTENT_ARG];\n  if (typeof value !== 'string') {\n    return undefined;\n  }\n  const trimmed = value.trim();\n  return trimmed === '' ? undefined : trimmed;\n}\n\n/**\n * Returns the args without the `intent` key so downstream consumers that did\n * not declare it never receive it. Parses stringified JSON object args;\n * returns the value unchanged when the key is absent.\n */\nexport function stripIntent(args: unknown): unknown {\n  const obj = coerceArgsObject(args);\n  if (!obj || !(INTENT_ARG in obj)) {\n    return args;\n  }\n  const { [INTENT_ARG]: _omit, ...rest } = obj;\n  return rest;\n}\n\n/**\n * Leading-verb map for the mechanical outcome transform, keyed by the\n * lowercased first word of the intent. Deliberately small: an unknown leading\n * word leaves the intent unchanged rather than mangling it.\n */\nconst OUTCOME_VERB_MAP: ReadonlyMap<string, string> = new Map([\n  ['searching', 'Searched'],\n  ['reading', 'Read'],\n  ['writing', 'Wrote'],\n  ['editing', 'Edited'],\n  ['running', 'Ran'],\n  ['creating', 'Created'],\n  ['checking', 'Checked'],\n  ['fetching', 'Fetched'],\n  ['listing', 'Listed'],\n  ['looking', 'Looked'],\n  ['building', 'Built'],\n  ['deleting', 'Deleted'],\n  ['updating', 'Updated'],\n  ['adding', 'Added'],\n  ['removing', 'Removed'],\n  ['verifying', 'Verified'],\n  ['analyzing', 'Analyzed'],\n  ['generating', 'Generated'],\n  ['delegating', 'Delegated'],\n  ['spawning', 'Spawned'],\n  ['compiling', 'Compiled'],\n  ['grepping', 'Grepped'],\n]);\n\nfunction matchLeadingCase(replacement: string, original: string): string {\n  if (original.charAt(0) === original.charAt(0).toLowerCase()) {\n    return replacement.charAt(0).toLowerCase() + replacement.slice(1);\n  }\n  return replacement;\n}\n\nfunction transformLeadingVerb(intent: string): string {\n  const spaceIdx = intent.search(/\\s/);\n  const leading = spaceIdx === -1 ? intent : intent.slice(0, spaceIdx);\n  const mapped = OUTCOME_VERB_MAP.get(leading.toLowerCase());\n  if (mapped == null) {\n    return intent;\n  }\n  return matchLeadingCase(mapped, leading) + intent.slice(leading.length);\n}\n\n/**\n * Resolves the settled label for a call from its model-authored `intent` and\n * the tool's result fields, in precedence order:\n *\n *  1. `outcome` — full replacement authored by the tool.\n *  2. `outcome_patch` — first occurrence of `from` in the intent replaced\n *     with `to` (case-sensitive); no-op when `from` is absent or empty.\n *  3. Mechanical transform — the leading word mapped present-progressive →\n *     past tense; an unknown leading word leaves the intent unchanged.\n *\n * Returns undefined when there is neither an intent nor an outcome, so\n * callers fall back to their default label. Pure and dependency-free — host\n * UIs needing identical logic can import or mirror it.\n */\nexport function applyOutcome(\n  intent: string | undefined,\n  result?: { outcome?: string; outcome_patch?: OutcomePatch },\n): string | undefined {\n  const outcome = result?.outcome;\n  if (typeof outcome === 'string' && outcome.trim() !== '') {\n    return outcome;\n  }\n  if (intent == null || intent === '') {\n    return undefined;\n  }\n  const patch = result?.outcome_patch;\n  if (patch != null && patch.from !== '' && intent.includes(patch.from)) {\n    /** Replacement callback keeps `to` verbatim — a direct string second\n     *  argument would interpret `$&`/`$'`-style tokens in tool-authored\n     *  text (e.g. labels derived from shell syntax). */\n    return intent.replace(patch.from, () => patch.to);\n  }\n  return transformLeadingVerb(intent);\n}\n\n/**\n * Hard cap on an emitted outcome label. The label is a single progress line\n * in UI chrome; a tool that derives it from data (or a malformed patch)\n * must not be able to inflate completion events or persisted parts.\n */\nconst MAX_OUTCOME_CHARS = 256;\n\nfunction boundOutcomeLabel(label: string | undefined): string | undefined {\n  if (label == null) {\n    return undefined;\n  }\n  const singleLine = label.replace(/\\s+/g, ' ').trim();\n  if (singleLine === '') {\n    return undefined;\n  }\n  if (singleLine.length <= MAX_OUTCOME_CHARS) {\n    return singleLine;\n  }\n  return `${singleLine.slice(0, MAX_OUTCOME_CHARS - 1)}…`;\n}\n\n/**\n * Resolves the settled label to emit on a completion event: only when the\n * tool actually authored `outcome`/`outcome_patch` fields. Returns undefined\n * otherwise — the mechanical transform of a bare intent is left to the host\n * so the wire never carries a label the host can derive itself. The result\n * is collapsed to a bounded single line before emission.\n *\n * For failed calls (`isError`), only tool-AUTHORED text may label the call:\n * an explicit `outcome`, or a patch whose `from` actually matches the\n * intent. An unmatched patch must not fall through to the mechanical\n * past-tense transform — wording drift in a failure patch would otherwise\n * render a success-looking label for an error.\n */\nexport function resolveToolOutcome(\n  args: unknown,\n  fields?: { outcome?: string; outcome_patch?: OutcomePatch } | null,\n  options?: { isError?: boolean },\n): string | undefined {\n  if (fields == null || (fields.outcome == null && fields.outcome_patch == null)) {\n    return undefined;\n  }\n  if (options?.isError !== true) {\n    return boundOutcomeLabel(applyOutcome(readIntent(args), fields));\n  }\n  const outcome = fields.outcome;\n  if (typeof outcome === 'string' && outcome.trim() !== '') {\n    return boundOutcomeLabel(outcome);\n  }\n  const intent = readIntent(args);\n  const patch = fields.outcome_patch;\n  if (\n    intent != null &&\n    patch != null &&\n    patch.from !== '' &&\n    intent.includes(patch.from)\n  ) {\n    return boundOutcomeLabel(intent.replace(patch.from, () => patch.to));\n  }\n  return undefined;\n}\n\n/**\n * Reads the outcome fields off a tool-execution result: the typed\n * `outcome`/`outcome_patch` fields when present, else the artifact channel\n * (see {@link readOutcomeFields}) — so a `content_and_artifact` tool authors\n * its label the same way on the direct and event-driven paths.\n */\nexport function outcomeFieldsFromResult(result: {\n  outcome?: string;\n  outcome_patch?: OutcomePatch;\n  artifact?: unknown;\n}): { outcome?: string; outcome_patch?: OutcomePatch } | undefined {\n  if (result.outcome != null || result.outcome_patch != null) {\n    return result;\n  }\n  return readOutcomeFields(result.artifact);\n}\n\n/**\n * Extracts validated `outcome`/`outcome_patch` fields from an arbitrary\n * value — the artifact channel through which an in-process\n * `content_and_artifact` tool authors its settled label. Returns undefined\n * when neither field is usable.\n */\nexport function readOutcomeFields(\n  source: unknown,\n): { outcome?: string; outcome_patch?: OutcomePatch } | undefined {\n  if (source == null || typeof source !== 'object' || Array.isArray(source)) {\n    return undefined;\n  }\n  const record = source as Record<string, unknown>;\n  const outcome =\n    typeof record.outcome === 'string' && record.outcome.trim() !== ''\n      ? record.outcome\n      : undefined;\n  let outcome_patch: OutcomePatch | undefined;\n  const rawPatch = record.outcome_patch;\n  if (rawPatch != null && typeof rawPatch === 'object' && !Array.isArray(rawPatch)) {\n    const patch = rawPatch as Record<string, unknown>;\n    if (typeof patch.from === 'string' && typeof patch.to === 'string') {\n      outcome_patch = { from: patch.from, to: patch.to };\n    }\n  }\n  if (outcome == null && outcome_patch == null) {\n    return undefined;\n  }\n  return { outcome, outcome_patch };\n}\n"],"mappings":"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"}

package/dist/esm/tools/local/CompileCheckTool.mjs

@@ -1,5 +1,6 @@
 import "../../common/enum.mjs";
 import "../../common/index.mjs";
+import { withIntent } from "../intentArg.mjs";
 import { isWorkspaceClientTimeoutError } from "./workspaceFS.mjs";
 import { getLocalCwd, getWorkspaceFS, spawnLocalProcess, truncateLocalOutput, validateBashCommand } from "./LocalExecutionEngine.mjs";
 import { tool } from "@langchain/core/tools";
@@ -31,7 +32,7 @@ import { resolve } from "path";
 */
 /** Back-compat alias; canonical name lives on `Constants.COMPILE_CHECK`. */
 const CompileCheckToolName = "compile_check";
-const CompileCheckSchema = {
+const CompileCheckSchema = withIntent({
 	type: "object",
 	properties: {
 		command: {
@@ -43,7 +44,7 @@ const CompileCheckSchema = {
 			description: "Optional timeout in milliseconds. Defaults to 120000 (2 min)."
 		}
 	}
-};
+});
 async function pathExists(fs, p) {
 	try {
 		await fs.stat(p);