@librechat/agents 3.2.66 → 3.2.67

package/src/hooks/__tests__/createToolPolicyHook.test.ts

@@ -98,12 +98,12 @@ describe('createToolPolicyHook — bypass mode', () => {
     expect((await callHook(hook, 'read_file')).decision).toBe('allow');
   });
 
-  it('overrides explicit ask patterns (bypass means stop asking)', async () => {
+  it('still asks tools that match an explicit ask pattern', async () => {
     const hook = createToolPolicyHook({
       mode: 'bypass',
       ask: ['execute_*'],
     });
-    expect((await callHook(hook, 'execute_code')).decision).toBe('allow');
+    expect((await callHook(hook, 'execute_code')).decision).toBe('ask');
   });
 });
 
@@ -154,6 +154,15 @@ describe('createToolPolicyHook — pattern matching', () => {
 });
 
 describe('createToolPolicyHook — precedence', () => {
+  it('deny wins over ask', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      deny: ['execute_delete'],
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_delete')).decision).toBe('deny');
+  });
+
   it('deny wins over allow', async () => {
     const hook = createToolPolicyHook({
       mode: 'default',
@@ -173,13 +182,13 @@ describe('createToolPolicyHook — precedence', () => {
     expect((await callHook(hook, 'anything_else')).decision).toBe('allow');
   });
 
-  it('allow wins over ask in default mode', async () => {
+  it('ask wins over allow in default mode', async () => {
     const hook = createToolPolicyHook({
       mode: 'default',
       allow: ['execute_safe'],
       ask: ['execute_*'],
     });
-    expect((await callHook(hook, 'execute_safe')).decision).toBe('allow');
+    expect((await callHook(hook, 'execute_safe')).decision).toBe('ask');
     expect((await callHook(hook, 'execute_dangerous')).decision).toBe('ask');
   });
 });

package/src/hooks/createToolPolicyHook.ts

@@ -3,11 +3,11 @@
  * permission policies (allow / deny / ask lists + a global mode) without
  * hand-rolling matching, precedence, and decision logic per-host.
  *
- * Maps directly to the Claude Code Agent SDK permission vocabulary
- * (`allowed_tools` / `disallowed_tools` / `permissionMode`) so users of
- * either SDK can think in the same terms. See the README's HITL section
- * for the cross-walk and `docs/hooks-design-report.md` for the broader
- * hook system context.
+ * Uses the Claude Code Agent SDK permission vocabulary (`allowed_tools` /
+ * `disallowed_tools` / `permissionMode`) while treating modes as fallbacks
+ * for calls that match no explicit rule. See the README's HITL section for
+ * the cross-walk and `docs/hooks-design-report.md` for the broader hook
+ * system context.
  */
 
 import type { HookCallback, PreToolUseHookOutput, ToolDecision } from './types';
@@ -20,10 +20,8 @@ import type { HookCallback, PreToolUseHookOutput, ToolDecision } from './types';
  *   - `dontAsk`  — unmatched tools are denied; the human is never
  *                  prompted. Useful for headless / API agents where a
  *                  silent denial is preferable to a hung interrupt.
- *   - `bypass`   — every tool is approved, except those matching `deny`
- *                  patterns. The kill switch you flip when you trust
- *                  the agent and want to stop being asked. Equivalent to
- *                  Claude Code's `bypassPermissions`.
+ *   - `bypass`   — unmatched tools are approved. Explicit `deny` and `ask`
+ *                  rules still apply.
  */
 export type ToolPolicyMode = 'default' | 'dontAsk' | 'bypass';
 
@@ -46,9 +44,8 @@ export interface ToolPolicyConfig {
    */
   deny?: readonly string[];
   /**
-   * Tool name patterns that always trigger human approval, regardless
-   * of `mode: 'default'` vs `'dontAsk'`. In `mode: 'bypass'` these are
-   * still bypassed (because that's what bypass means).
+   * Tool name patterns that always trigger human approval. Wins over
+   * `allow` and every mode, but not `deny`.
    */
   ask?: readonly string[];
   /**
@@ -115,12 +112,12 @@ function formatReason(
  * registry.register('PreToolUse', { hooks: [policyHook] });
  * ```
  *
- * Evaluation order matches Claude Code's permission flow:
+ * Explicit rules take precedence over fallback modes:
  *
  *   1. `deny` rule match → `'deny'` (always wins, even in `bypass`).
- *   2. `mode === 'bypass'` → `'allow'`.
+ *   2. `ask` rule match → `'ask'`.
  *   3. `allow` rule match → `'allow'`.
- *   4. `ask` rule match → `'ask'`.
+ *   4. `mode === 'bypass'` → `'allow'`.
  *   5. `mode === 'dontAsk'` → `'deny'`.
  *   6. fallthrough → `'ask'`.
  *
@@ -168,14 +165,14 @@ function decide(
   if (denyMatch(toolName)) {
     return 'deny';
   }
-  if (mode === 'bypass') {
-    return 'allow';
+  if (askMatch(toolName)) {
+    return 'ask';
   }
   if (allowMatch(toolName)) {
     return 'allow';
   }
-  if (askMatch(toolName)) {
-    return 'ask';
+  if (mode === 'bypass') {
+    return 'allow';
   }
   if (mode === 'dontAsk') {
     return 'deny';

package/src/tools/ToolSearch.ts

@@ -359,18 +359,48 @@ function simplifyParametersForSearch(
   return { type: parameters.type };
 }
 
+/**
+ * Splits one alphanumeric identifier segment on case boundaries without
+ * emitting artificial one-character acronym fragments.
+ */
+function splitCaseSegment(segment: string): string[] {
+  const splitTokens = segment
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+
+  if (splitTokens.length < 2) return splitTokens;
+
+  const mergedTokens: string[] = [];
+  let prefix = '';
+  for (const token of splitTokens) {
+    if (token.length === 1) {
+      prefix += token;
+      continue;
+    }
+    mergedTokens.push(`${prefix}${token}`);
+    prefix = '';
+  }
+
+  if (prefix && mergedTokens.length > 0) {
+    mergedTokens[mergedTokens.length - 1] += prefix;
+  }
+  return mergedTokens.length > 0 ? mergedTokens : [prefix];
+}
+
 /**
  * Tokenizes a string into lowercase words for BM25.
- * Splits on underscores and non-alphanumeric characters for consistent matching.
+ * Splits camelCase, underscores, and non-alphanumeric characters for consistent matching.
  * @param text - The text to tokenize
  * @returns Array of lowercase tokens
  */
 function tokenize(text: string): string[] {
   return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]/g, ' ')
-    .split(/\s+/)
-    .filter((token) => token.length > 0);
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .flatMap(splitCaseSegment);
 }
 
 /**
@@ -396,7 +426,7 @@ function createToolDocument(tool: t.ToolMetadata, fields: string[]): string {
     parts.push(paramNames);
   }
 
-  return parts.join(' ');
+  return tokenize(parts.join(' ')).join(' ');
 }
 
 /**
@@ -498,35 +528,63 @@ function performLocalSearch(
 
   const maxScore = Math.max(...scores.filter((s) => s > 0), 1);
   const queryLower = query.toLowerCase().trim();
+  const queryIdentifier = queryTokens.join('');
+  const matchesIdentifiers = fields.includes('name');
 
-  const results: t.ToolSearchResult[] = [];
+  const results: Array<{
+    result: t.ToolSearchResult;
+    identifierPriority: number;
+  }> = [];
   for (let i = 0; i < tools.length; i++) {
-    if (scores[i] > 0) {
-      const { field, snippet } = findMatchedField(
-        tools[i],
-        queryTokens,
-        fields
-      );
-      let normalizedScore = Math.min(scores[i] / maxScore, 1.0);
-
-      const baseName = getBaseToolName(tools[i].name).toLowerCase();
-      if (baseName === queryLower) {
+    const score = scores[i];
+    const hasSearchScore = Number.isFinite(score) && score > 0;
+    let identifierPriority = 0;
+    let normalizedScore = hasSearchScore ? Math.min(score / maxScore, 1.0) : 0;
+
+    if (matchesIdentifiers) {
+      const rawBaseName = getBaseToolName(tools[i].name).toLowerCase();
+      const rawFullName = tools[i].name.toLowerCase();
+      const baseIdentifier = tokenize(rawBaseName).join('');
+      const fullIdentifier = tokenize(rawFullName).join('');
+
+      if (rawFullName === queryLower) {
+        identifierPriority = 4;
+        normalizedScore = 1.0;
+      } else if (rawBaseName === queryLower) {
+        identifierPriority = 3;
+        normalizedScore = 1.0;
+      } else if (
+        baseIdentifier === queryIdentifier ||
+        fullIdentifier === queryIdentifier
+      ) {
+        identifierPriority = 2;
         normalizedScore = 1.0;
-      } else if (baseName.startsWith(queryLower)) {
+      } else if (baseIdentifier.startsWith(queryIdentifier)) {
+        identifierPriority = 1;
         normalizedScore = Math.max(normalizedScore, 0.95);
       }
+    }
+
+    if (!hasSearchScore && identifierPriority === 0) continue;
 
-      results.push({
+    const { field, snippet } = findMatchedField(tools[i], queryTokens, fields);
+    results.push({
+      result: {
         tool_name: tools[i].name,
         match_score: normalizedScore,
         matched_field: field,
         snippet,
-      });
-    }
+      },
+      identifierPriority,
+    });
   }
 
-  results.sort((a, b) => b.match_score - a.match_score);
-  const topResults = results.slice(0, maxResults);
+  results.sort(
+    (a, b) =>
+      b.identifierPriority - a.identifierPriority ||
+      b.result.match_score - a.result.match_score
+  );
+  const topResults = results.slice(0, maxResults).map(({ result }) => result);
 
   return {
     tool_references: topResults,

package/src/tools/__tests__/ToolSearch.test.ts

@@ -360,6 +360,52 @@ describe('ToolSearch', () => {
       expect(result.tool_references[0].match_score).toBeGreaterThan(0);
     });
 
+    it('does not match tool names when searching only parameters', () => {
+      const tools: ToolMetadata[] = [
+        {
+          name: 'query',
+          description: 'A tool whose name matches but parameters do not',
+          parameters: {
+            type: 'object',
+            properties: { value: { type: 'string' } },
+          },
+        },
+        {
+          name: 'run_database_query',
+          description: 'Run a database query',
+          parameters: {
+            type: 'object',
+            properties: { query: { type: 'string' } },
+          },
+        },
+      ];
+
+      const result = performLocalSearch(tools, 'query', ['parameters'], 1);
+
+      expect(result.tool_references).toHaveLength(1);
+      expect(result.tool_references[0].tool_name).toBe('run_database_query');
+      expect(result.tool_references[0].matched_field).toBe('parameters');
+    });
+
+    it('returns no matches when every selected field is empty', () => {
+      const tools: ToolMetadata[] = [
+        {
+          name: 'get_weather',
+          description: 'Get the weather',
+          parameters: undefined,
+        },
+        {
+          name: 'send_email',
+          description: 'Send an email',
+          parameters: undefined,
+        },
+      ];
+
+      const result = performLocalSearch(tools, 'query', ['parameters'], 10);
+
+      expect(result.tool_references).toEqual([]);
+    });
+
     it('prioritizes name matches over description matches', () => {
       const result = performLocalSearch(
         mockTools,
@@ -830,6 +876,111 @@ describe('ToolSearch', () => {
       },
     ];
 
+    it('finds camelCase tools by exact name', () => {
+      const tools: ToolMetadata[] = [
+        {
+          name: 'addActivity',
+          description: 'Create an activity',
+          parameters: undefined,
+        },
+        {
+          name: 'addPerson',
+          description: 'Create a person',
+          parameters: undefined,
+        },
+      ];
+
+      const result = performLocalSearch(tools, 'addPerson', ['name'], 10);
+
+      expect(result.tool_references[0].tool_name).toBe('addPerson');
+      expect(result.tool_references[0].match_score).toBe(1.0);
+    });
+
+    it('finds camelCase tools by a lowercased exact name', () => {
+      const tools: ToolMetadata[] = [
+        {
+          name: 'addActivity',
+          description: 'Create an activity',
+          parameters: undefined,
+        },
+        {
+          name: 'addPerson',
+          description: 'Create a person',
+          parameters: undefined,
+        },
+      ];
+
+      const result = performLocalSearch(tools, 'addperson', ['name'], 10);
+
+      expect(result.tool_references).toHaveLength(1);
+      expect(result.tool_references[0].tool_name).toBe('addPerson');
+      expect(result.tool_references[0].match_score).toBe(1.0);
+    });
+
+    it('prioritizes an exact full camelCase MCP tool ID', () => {
+      const tools: ToolMetadata[] = [
+        {
+          name: 'add_person_mcp_pipedrive',
+          description: 'Create a person with a separator variant',
+          parameters: undefined,
+        },
+        {
+          name: 'addActivity_mcp_pipedrive',
+          description: 'Create an activity',
+          parameters: undefined,
+        },
+        {
+          name: 'addPerson_mcp_pipedrive',
+          description: 'Create a person',
+          parameters: undefined,
+        },
+        {
+          name: 'updatePerson_mcp_pipedrive',
+          description: 'Update a person',
+          parameters: undefined,
+        },
+      ];
+
+      const result = performLocalSearch(
+        tools,
+        'addPerson_mcp_pipedrive',
+        ['name'],
+        1
+      );
+
+      expect(result.tool_references[0].tool_name).toBe(
+        'addPerson_mcp_pipedrive'
+      );
+      expect(result.tool_references[0].match_score).toBe(1.0);
+    });
+
+    it.each([
+      ['OAuthToken', 'close_order'],
+      ['iOSApp', 'inspect_inventory'],
+    ])(
+      'does not return tools matching only an acronym fragment from %s',
+      (matchingTool, unrelatedTool) => {
+        const tools: ToolMetadata[] = [
+          {
+            name: matchingTool,
+            description: 'Expected acronym tool',
+            parameters: undefined,
+          },
+          {
+            name: unrelatedTool,
+            description: 'Unrelated tool',
+            parameters: undefined,
+          },
+        ];
+
+        const result = performLocalSearch(tools, matchingTool, ['name'], 10);
+
+        expect(
+          result.tool_references.map(({ tool_name }) => tool_name)
+        ).toEqual([matchingTool]);
+      }
+    );
+
     it('searches across all tools including MCP tools', () => {
       const result = performLocalSearch(
         mcpTools,

package/src/tools/__tests__/hitl.test.ts

@@ -34,7 +34,7 @@ import type {
 import type * as t from '@/types';
 import { Providers as providers, GraphEvents } from '@/common';
 import * as events from '@/utils/events';
-import { HookRegistry } from '@/hooks';
+import { HookRegistry, createToolPolicyHook } from '@/hooks';
 import { ToolNode } from '../ToolNode';
 
 async function flushAsyncWork(): Promise<void> {
@@ -255,6 +255,119 @@ describe('ToolNode HITL — `ask` decision raises interrupt() when humanInTheLoo
     ]);
   });
 
+  it('waits for approval before executing an explicit ask rule in bypass mode', async () => {
+    let toolExecuted = false;
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data) => {
+        if (event !== 'on_tool_execute') {
+          return;
+        }
+        toolExecuted = true;
+        const request = data as {
+          resolve: (results: t.ToolExecuteResult[]) => void;
+        };
+        request.resolve([
+          { toolCallId: 'call_1', content: 'deleted', status: 'success' },
+        ]);
+      });
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        createToolPolicyHook({
+          mode: 'bypass',
+          ask: ['dangerous_*'],
+        }),
+      ],
+    });
+    const node = new ToolNode({
+      tools: [createSchemaStub('dangerous_tool')],
+      eventDrivenMode: true,
+      agentId: 'agent-x',
+      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
+      hookRegistry: registry,
+      humanInTheLoop: { enabled: true },
+    });
+    const graph = buildHITLGraph(node, [
+      {
+        id: 'call_1',
+        name: 'dangerous_tool',
+        args: { command: 'delete data' },
+      },
+    ]);
+    const config = {
+      configurable: { thread_id: 'thread-bypass-explicit-ask' },
+    };
+
+    const interrupted = await graph.invoke({ messages: [] }, config);
+
+    expect(isInterrupted<t.HumanInterruptPayload>(interrupted)).toBe(true);
+    expect(toolExecuted).toBe(false);
+
+    const resumed = (await resumeGraph(
+      graph,
+      interrupted,
+      [{ type: 'approve' }],
+      config
+    )) as { messages: BaseMessage[] };
+
+    expect(toolExecuted).toBe(true);
+    expect(
+      resumed.messages.some(
+        (message) =>
+          message._getType() === 'tool' &&
+          (message as ToolMessage).tool_call_id === 'call_1' &&
+          message.content === 'deleted'
+      )
+    ).toBe(true);
+  });
+
+  it('executes an unmatched tool without interruption in bypass mode', async () => {
+    let toolExecuted = false;
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data) => {
+        if (event !== 'on_tool_execute') {
+          return;
+        }
+        toolExecuted = true;
+        const request = data as {
+          resolve: (results: t.ToolExecuteResult[]) => void;
+        };
+        request.resolve([
+          { toolCallId: 'call_1', content: 'read result', status: 'success' },
+        ]);
+      });
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        createToolPolicyHook({
+          mode: 'bypass',
+          ask: ['dangerous_*'],
+        }),
+      ],
+    });
+    const node = new ToolNode({
+      tools: [createSchemaStub('read_tool')],
+      eventDrivenMode: true,
+      agentId: 'agent-x',
+      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
+      hookRegistry: registry,
+      humanInTheLoop: { enabled: true },
+    });
+    const graph = buildHITLGraph(node, [
+      { id: 'call_1', name: 'read_tool', args: { command: 'read data' } },
+    ]);
+
+    const result = await graph.invoke(
+      { messages: [] },
+      { configurable: { thread_id: 'thread-bypass-unmatched' } }
+    );
+
+    expect(isInterrupted(result)).toBe(false);
+    expect(toolExecuted).toBe(true);
+  });
+
   it('resume with approve runs the tool through the host event path', async () => {
     mockEventDispatch([
       { toolCallId: 'call_1', content: 'host-result', status: 'success' },

package/src/tools/search/source-processing.test.ts

@@ -141,6 +141,63 @@ describe('expandHighlights content stripping', () => {
     expect(result.organic?.[0].content).toBeUndefined();
     expect(result.organic?.[0].references).toBeUndefined();
   });
+
+  test('honors a custom mainExpandBy when expanding highlights', () => {
+    const highlightText = 'KEYFACT';
+    // Boundary-free filler so expansion is governed purely by mainExpandBy,
+    // not by where natural separators happen to fall.
+    const content = `${'x'.repeat(1000)}${highlightText}${'y'.repeat(1000)}`;
+    const makeData = (): t.SearchResultData => ({
+      organic: [
+        {
+          ...makeOrganic('https://a.com'),
+          content,
+          highlights: [{ text: highlightText, score: 0.9 }],
+        },
+      ],
+    });
+
+    // separatorExpandBy 0 isolates the mainExpandBy effect.
+    const narrow = expandHighlights(makeData(), 50, 0).organic?.[0]
+      .highlights?.[0];
+    const wide = expandHighlights(makeData(), 500, 0).organic?.[0]
+      .highlights?.[0];
+
+    expect(narrow?.text).toContain(highlightText);
+    expect(wide?.text).toContain(highlightText);
+    // 50 chars of context each side vs. 500 → wide must be markedly longer.
+    expect(wide!.text.length).toBeGreaterThan(narrow!.text.length);
+    expect(narrow!.text.length).toBe(highlightText.length + 100);
+    expect(wide!.text.length).toBe(highlightText.length + 1000);
+  });
+
+  test('honors a custom separatorExpandBy when seeking boundaries', () => {
+    const highlightText = 'KEYFACT';
+    // The main window lands inside a boundary-free 'y' run; the only natural
+    // boundary ('. ') sits 250 chars past the main window's end. A small
+    // separator range can't reach it; a large one can.
+    const content = `${'x'.repeat(100)}${highlightText}${'y'.repeat(300)}. ${'z'.repeat(300)}`;
+    const makeData = (): t.SearchResultData => ({
+      organic: [
+        {
+          ...makeOrganic('https://a.com'),
+          content,
+          highlights: [{ text: highlightText, score: 0.9 }],
+        },
+      ],
+    });
+
+    // Same mainExpandBy; only the separator search range differs.
+    const narrow = expandHighlights(makeData(), 50, 100).organic?.[0]
+      .highlights?.[0];
+    const wide = expandHighlights(makeData(), 50, 400).organic?.[0]
+      .highlights?.[0];
+
+    expect(narrow?.text).toContain(highlightText);
+    expect(wide?.text).toContain(highlightText);
+    // Only the wider separator range reaches the trailing sentence boundary.
+    expect(wide!.text.length).toBeGreaterThan(narrow!.text.length);
+  });
 });
 
 describe('createSourceProcessor content capping', () => {

package/src/tools/search/tool.ts

@@ -203,6 +203,8 @@ function createSearchProcessor({
   supportsNews,
   sourceProcessor,
   onGetHighlights,
+  mainExpandBy,
+  separatorExpandBy,
   logger,
 }: {
   safeSearch: t.SearchToolConfig['safeSearch'];
@@ -212,6 +214,8 @@ function createSearchProcessor({
   searchAPI: ReturnType<typeof createSearchAPI>;
   sourceProcessor: ReturnType<typeof createSourceProcessor>;
   onGetHighlights: t.SearchToolConfig['onGetHighlights'];
+  mainExpandBy: t.SearchToolConfig['mainExpandBy'];
+  separatorExpandBy: t.SearchToolConfig['separatorExpandBy'];
   logger: t.Logger;
 }) {
   return async function ({
@@ -260,7 +264,11 @@ function createSearchProcessor({
         numElements: maxSources,
       });
 
-      return expandHighlights(processedSources);
+      return expandHighlights(
+        processedSources,
+        mainExpandBy,
+        separatorExpandBy
+      );
     } catch (error) {
       logger.error('Error in search:', error);
       return {
@@ -376,6 +384,8 @@ export const createSearchTool = (
     maxContentLength,
     chunkSize,
     chunkOverlap,
+    mainExpandBy,
+    separatorExpandBy,
     maxOutputChars,
     strategies = ['no_extraction'],
     filterContent = true,
@@ -525,6 +535,8 @@ export const createSearchTool = (
     supportsNews: searchProvider !== 'keenable',
     sourceProcessor,
     onGetHighlights,
+    mainExpandBy,
+    separatorExpandBy,
     logger,
   });
 

package/src/tools/search/types.ts

@@ -227,6 +227,8 @@ export interface ProcessSourcesConfig {
    * configurable via the `SEARCH_CHUNK_OVERLAP` env var. Clamped below
    * `chunkSize`. */
   chunkOverlap?: number;
+  mainExpandBy?: number;
+  separatorExpandBy?: number;
   strategies?: string[];
   filterContent?: boolean;
   reranker?: BaseReranker;