Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions src/graphs/Graph.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1174,7 +1174,10 @@ export abstract class Graph<
}
const savedStateKeys = new Set<string>();
const toolNodeStatesByKey = new Map<string, SubagentToolNodeResumeState>();
const legacyNodeStatesByKey = new Map<string, SubagentToolNodeResumeState>();
const legacyNodeStatesByKey = new Map<
string,
SubagentToolNodeResumeState
>();
for (const nodeState of state.toolNodes) {
const identity = parseSubagentToolNodeStateKey(nodeState.stateKey);
if (identity == null) {
Expand Down Expand Up @@ -4378,7 +4381,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
);
const traceMetadata = createLangfuseTraceMetadata({
messageId: this.runId,
parentMessageId: config.configurable?.requestBody?.parentMessageId,
parentMessageId:
typeof config.metadata?.parentMessageId === 'string'
? config.metadata.parentMessageId
: config.configurable?.requestBody?.parentMessageId,
agentId,
agentName: agentContext.name,
rootAgentId: this.defaultAgentId,
Expand Down Expand Up @@ -4462,6 +4468,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
traceAnchor: this.langfuseTraceAnchor,
runId: this.langfuseScopeRunId,
agentId,
traceIdSeed:
langfuse?.deterministicTraceId === true ? this.runId : undefined,
}),
() =>
attemptInvoke(
Expand Down Expand Up @@ -4672,6 +4680,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
langfuseOverlay: agentContext.langfuse,
runId: this.langfuseScopeRunId,
agentId,
traceIdSeed:
langfuse?.deterministicTraceId === true
? this.runId
: undefined,
}),
() =>
tryFallbackProviders({
Expand Down
30 changes: 30 additions & 0 deletions src/messages/__tests__/tools.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,36 @@ describe('Tool Discovery Functions', () => {
};

describe('extractToolDiscoveries', () => {
it('extracts tool names from a skill artifact in the current turn', () => {
const messages: BaseMessage[] = [
new HumanMessage('Load the proposal skill'),
createAIMessage('Loading skill...', [
{
id: 'skill_call',
name: Constants.SKILL_TOOL,
args: { skill: 'dolibarr-proposal' },
},
]),
new ToolMessage({
content: 'Loaded skill',
tool_call_id: 'skill_call',
name: Constants.SKILL_TOOL,
artifact: {
tool_references: [
{ tool_name: 'create_proposal_mcp_dolibarr' },
{ tool_name: 'add_proposal_lines_mcp_dolibarr' },
],
},
}),
];

expect(extractToolDiscoveries(messages)).toEqual([
'create_proposal_mcp_dolibarr',
'add_proposal_lines_mcp_dolibarr',
]);
expect(hasToolSearchInCurrentTurn(messages)).toBe(true);
});

it('extracts tool names from a single tool search result', () => {
const messages: BaseMessage[] = [
new HumanMessage('Search for database tools'),
Expand Down
10 changes: 8 additions & 2 deletions src/messages/tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,12 @@ export function extractToolDiscoveries(messages: BaseMessage[]): string[] {
for (let i = latestAIParentIndex + 1; i < messages.length; i++) {
const msg = messages[i];
if (!(msg instanceof ToolMessage)) continue;
if (msg.name !== Constants.TOOL_SEARCH) continue;
if (
msg.name !== Constants.TOOL_SEARCH &&
msg.name !== Constants.SKILL_TOOL
) {
continue;
}
if (!toolCallIds.has(msg.tool_call_id)) continue;

// This is a tool search result from the current turn
Expand Down Expand Up @@ -88,7 +93,8 @@ export function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean {
const msg = messages[i];
if (
msg instanceof ToolMessage &&
msg.name === Constants.TOOL_SEARCH &&
(msg.name === Constants.TOOL_SEARCH ||
msg.name === Constants.SKILL_TOOL) &&
toolCallIds.has(msg.tool_call_id)
) {
return true;
Expand Down
188 changes: 177 additions & 11 deletions src/tools/ToolSearch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,10 @@ const MAX_PATTERN_LENGTH = 200;
export const ToolSearchToolName = Constants.TOOL_SEARCH;

export const ToolSearchToolDescription =
'Searches deferred tools using BM25 ranking. Multi-word queries supported. Use mcp_server param to filter by server.';
'Searches deferred tools using BM25 ranking. Multi-word queries rank better than a single word. If you know the exact tool name, query that full name or base name (or select:full_name) to load it directly. Use mcp_server param to filter by server.';

const QUERY_DESCRIPTION_LOCAL =
'Search term to find in tool names and descriptions. Case-insensitive substring matching. Optional if mcp_server is provided.';
'BM25 ranking over tool names and descriptions. Multi-word queries rank better than one word. If you know the exact tool name, pass the full name or base name (optionally prefixed with select:) to load it directly without ranking. Optional if mcp_server is provided.';
const QUERY_DESCRIPTION_REGEX =
'Regex pattern to search tool names and descriptions. Optional if mcp_server is provided.';
const FIELDS_DESCRIPTION =
Expand Down Expand Up @@ -597,9 +597,84 @@ function findMatchedField(
return { field: 'unknown', snippet: fallbackSnippet };
}

const SELECT_QUERY_PREFIX = /^select:/i;

/**
* Strips an optional `select:` prefix used to load a tool by exact name.
*/
function normalizeToolSearchQuery(query: string): string {
const trimmed = query.trim();
return (
SELECT_QUERY_PREFIX.test(trimmed)
? trimmed.replace(SELECT_QUERY_PREFIX, '')
: trimmed
).trim();
}

/**
* Base-name exact match is gated so a single English word does not skip BM25.
* Full names, underscored base names, and `select:` queries still qualify.
*/
function allowsBaseNameExactMatch(rawQuery: string): boolean {
const trimmed = rawQuery.trim();
if (SELECT_QUERY_PREFIX.test(trimmed)) {
return true;
}
return normalizeToolSearchQuery(rawQuery).includes('_');
}

/**
* Finds tools whose full name or MCP base name equals the query.
* Full-name matches win over base-name matches. All same-base tools are returned.
*/
function findExactToolMatches(
tools: t.ToolMetadata[],
query: string,
allowBaseName = true
): t.ToolMetadata[] {
const queryLower = query.toLowerCase();
if (queryLower === '') {
return [];
}
const full = tools.filter((tool) => tool.name.toLowerCase() === queryLower);
if (full.length > 0) {
return full;
}
if (allowBaseName !== true) {
return [];
}
return tools.filter(
(tool) => getBaseToolName(tool.name).toLowerCase() === queryLower
);
}

function toExactSearchResponse(
matches: t.ToolMetadata[],
query: string,
totalSearched: number
): t.ToolSearchResponse {
return {
tool_references: matches.map((tool) => ({
tool_name: tool.name,
match_score: 1,
matched_field: 'name',
snippet: tool.description
? tool.description.substring(0, 100)
: tool.name,
})),
total_tools_searched: totalSearched,
total_matches: matches.length,
pattern_used: query,
already_available:
matches.length > 0 &&
matches.every((tool) => tool.defer_loading === false),
};
}

/**
* Performs BM25-based search for better relevance ranking.
* Uses Okapi BM25 algorithm for term frequency and document length normalization.
* Exact full-name or base-name queries (optionally `select:`-prefixed) return that tool only.
* If query is empty, returns all tools (up to maxResults) sorted alphabetically.
* @param tools - Array of tool metadata to search
* @param query - The search query (empty returns all tools)
Expand All @@ -617,11 +692,24 @@ function performLocalSearch(
return {
tool_references: [],
total_tools_searched: 0,
total_matches: 0,
pattern_used: query,
};
}

const queryTokens = tokenize(query);
const normalizedQuery = normalizeToolSearchQuery(query);
if (fields.includes('name')) {
const exactMatches = findExactToolMatches(
tools,
normalizedQuery,
allowsBaseNameExactMatch(query)
);
if (exactMatches.length > 0) {
return toExactSearchResponse(exactMatches, normalizedQuery, tools.length);
}
}

const queryTokens = tokenize(normalizedQuery);

if (queryTokens.length === 0) {
const allTools = tools
Expand All @@ -638,15 +726,16 @@ function performLocalSearch(
return {
tool_references: allTools,
total_tools_searched: tools.length,
pattern_used: query,
total_matches: tools.length,
pattern_used: normalizedQuery,
};
}

const documents = tools.map((tool) => createToolDocument(tool, fields));
const scores = BM25(documents, queryTokens, { k1: 1.5, b: 0.75 }) as number[];

const maxScore = Math.max(...scores.filter((s) => s > 0), 1);
const queryLower = query.toLowerCase().trim();
const queryLower = normalizedQuery.toLowerCase().trim();
const queryIdentifier = queryTokens.join('');
const matchesIdentifiers = fields.includes('name');

Expand Down Expand Up @@ -708,7 +797,8 @@ function performLocalSearch(
return {
tool_references: topResults,
total_tools_searched: tools.length,
pattern_used: query,
total_matches: results.length,
pattern_used: normalizedQuery,
};
}

Expand Down Expand Up @@ -834,23 +924,43 @@ function formatSearchResults(
nameFormat: t.McpNameFormat = 'full',
notes: string[] = []
): string {
const { tool_references, total_tools_searched, pattern_used } =
searchResponse;
const {
tool_references,
total_tools_searched,
pattern_used,
total_matches,
already_available,
} = searchResponse;
const useFullName = nameFormat === 'full';

const output = {
const matchCount = total_matches ?? tool_references.length;
const hasQuery =
typeof pattern_used === 'string' && pattern_used.trim() !== '';
const hidden = hasQuery
? Math.max(0, matchCount - tool_references.length)
: 0;

const output: Record<string, unknown> = {
found: tool_references.length,
tools: tool_references.map((ref) => ({
name: useFullName ? ref.tool_name : getBaseToolName(ref.tool_name),
score: Number(ref.match_score.toFixed(2)),
matched_in: ref.matched_field,
snippet: ref.snippet,
})),
total_matches: matchCount,
hidden,
total_searched: total_tools_searched,
query: pattern_used,
...(notes.length > 0 ? { notes } : {}),
};

if (already_available === true) {
output.already_available = true;
output.hint = 'This tool is already bound; call it directly.';
} else if (hidden > 0) {
output.hint = `${hidden} more matches not shown. Use a more specific query (full tool name or base name) to load a known tool.`;
}

return JSON.stringify(output, null, 2);
}

Expand Down Expand Up @@ -1065,7 +1175,8 @@ ${deferredToolsListing}`
const description =
mode === 'local'
? `
Searches deferred tools using BM25 ranking. Multi-word queries supported.
Searches deferred tools using BM25 ranking. Multi-word queries rank better than a single word.
If you know the exact tool name, query that full name or base name (or select:full_name) to load it directly.
${mcpNote}${toolsListSection}
`.trim()
: `
Expand Down Expand Up @@ -1127,6 +1238,7 @@ ${mcpNote}${toolsListSection}
name: lcTool.name,
description: lcTool.description ?? '',
parameters: simplifyParametersForSearch(lcTool.parameters),
defer_loading: lcTool.defer_loading === true,
});

for (const lcTool of toolRegistry.values()) {
Expand Down Expand Up @@ -1209,6 +1321,58 @@ ${mcpNote}${toolsListSection}
}
}

if (mode === 'local') {
let catalogFilter: string[] = [];
if (hasServerFilter) {
catalogFilter =
activeServers.length > 0 ? activeServers : matchedServers;
}
const catalogTools: t.ToolMetadata[] = [];
for (const lcTool of toolRegistry.values()) {
if (
hasServerFilter &&
!isFromAnyMcpServer(lcTool.name, catalogFilter)
) {
continue;
}
catalogTools.push(describeTool(lcTool));
}
const normalizedQuery = normalizeToolSearchQuery(query);
if (normalizedQuery !== '') {
const exactMatches = findExactToolMatches(
catalogTools,
normalizedQuery,
allowsBaseNameExactMatch(query)
);
if (exactMatches.length > 0) {
const searchResponse = toExactSearchResponse(
exactMatches,
normalizedQuery,
catalogTools.length
);
const formattedOutput = formatSearchResults(
searchResponse,
mcpNameFormat,
filterNotes
);
return [
formattedOutput,
{
tool_references: searchResponse.tool_references,
metadata: {
total_searched: searchResponse.total_tools_searched,
pattern: searchResponse.pattern_used,
already_available: searchResponse.already_available,
mcp_server:
serverFilters.length > 0 ? serverFilters : undefined,
...filterMetadata,
},
},
];
}
}
}

if (deferredTools.length === 0) {
/** Say which of the three it is, so an empty result is not read as an
* outage: nothing is registered, the name did not match anything, or
Expand Down Expand Up @@ -1311,6 +1475,7 @@ ${mcpNote}${toolsListSection}
metadata: {
total_searched: searchResponse.total_tools_searched,
pattern: searchResponse.pattern_used,
already_available: searchResponse.already_available,
mcp_server: serverFilters.length > 0 ? serverFilters : undefined,
...filterMetadata,
},
Expand Down Expand Up @@ -1423,6 +1588,7 @@ ${mcpNote}${toolsListSection}

export {
createToolSearch,
formatSearchResults,
performLocalSearch,
extractMcpServerName,
isFromMcpServer,
Expand Down
Loading