@librechat/agents 3.0.41 → 3.0.43

package/dist/types/messages/index.d.ts

@@ -4,3 +4,4 @@ export * from './prune';
 export * from './format';
 export * from './cache';
 export * from './content';
+export * from './tools';

package/dist/types/messages/tools.d.ts

@@ -0,0 +1,17 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Extracts discovered tool names from tool search results in the current turn.
+ * Only processes tool search messages after the latest AI message with tool calls.
+ *
+ * Similar pattern to formatArtifactPayload - finds relevant messages efficiently
+ * by identifying the latest AI parent and only processing subsequent tool messages.
+ *
+ * @param messages - All messages in the conversation
+ * @returns Array of discovered tool names (empty if no new discoveries)
+ */
+export declare function extractToolDiscoveries(messages: BaseMessage[]): string[];
+/**
+ * Checks if the current turn has any tool search results.
+ * Quick check to avoid full extraction when not needed.
+ */
+export declare function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean;

package/dist/types/tools/ProgrammaticToolCalling.d.ts

@@ -3,40 +3,32 @@ import { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 declare const ProgrammaticToolCallingSchema: z.ZodObject<{
     code: z.ZodString;
-    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
-        parameters: z.ZodAny;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        description?: string | undefined;
-        parameters?: any;
-    }, {
-        name: string;
-        description?: string | undefined;
-        parameters?: any;
-    }>, "many">>;
     session_id: z.ZodOptional<z.ZodString>;
     timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
     code: string;
     timeout: number;
-    tools?: {
-        name: string;
-        description?: string | undefined;
-        parameters?: any;
-    }[] | undefined;
     session_id?: string | undefined;
 }, {
     code: string;
-    tools?: {
-        name: string;
-        description?: string | undefined;
-        parameters?: any;
-    }[] | undefined;
     timeout?: number | undefined;
     session_id?: string | undefined;
 }>;
+/**
+ * Extracts tool names that are actually called in the Python code.
+ * Matches patterns like `await tool_name(`, `tool_name(`, and asyncio.gather calls.
+ * @param code - The Python code to analyze
+ * @param availableToolNames - Set of available tool names to match against
+ * @returns Set of tool names found in the code
+ */
+export declare function extractUsedToolNames(code: string, availableToolNames: Set<string>): Set<string>;
+/**
+ * Filters tool definitions to only include tools actually used in the code.
+ * @param toolDefs - All available tool definitions
+ * @param code - The Python code to analyze
+ * @returns Filtered array of tool definitions
+ */
+export declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string): t.LCTool[];
 /**
  * Makes an HTTP request to the Code API.
  * @param endpoint - The API endpoint URL

package/dist/types/tools/ToolNode.d.ts

@@ -5,7 +5,6 @@ import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
 export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
-    tools: t.GenericTool[];
     private toolMap;
     private loadRuntimeTools?;
     handleToolErrors: boolean;
@@ -13,13 +12,16 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
     private toolUsageCount;
-    /** Tools available for programmatic code execution */
-    private programmaticToolMap?;
-    /** Tool definitions for programmatic code execution (sent to Code API) */
-    private programmaticToolDefs?;
-    /** Tool registry for tool search (deferred tools) */
+    /** Tool registry for filtering (lazy computation of programmatic maps) */
     private toolRegistry?;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, programmaticToolMap, programmaticToolDefs, toolRegistry, }: t.ToolNodeConstructorParams);
+    /** Cached programmatic tools (computed once on first PTC call) */
+    private programmaticCache?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, }: t.ToolNodeConstructorParams);
+    /**
+     * Returns cached programmatic tools, computing once on first access.
+     * Single iteration builds both toolMap and toolDefs simultaneously.
+     */
+    private getProgrammaticTools;
     /**
      * Returns a snapshot of the current tool usage counts.
      * @returns A ReadonlyMap where keys are tool names and values are their usage counts.

package/dist/types/types/tools.d.ts

@@ -25,11 +25,7 @@ export type ToolNodeOptions = {
     loadRuntimeTools?: ToolRefGenerator;
     toolCallStepIds?: Map<string, string>;
     errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<void>;
-    /** Tools available for programmatic code execution (allowed_callers includes 'code_execution') */
-    programmaticToolMap?: ToolMap;
-    /** Tool definitions for programmatic code execution (sent to Code API for stub generation) */
-    programmaticToolDefs?: LCTool[];
-    /** Tool registry for tool search (deferred tool definitions) */
+    /** Tool registry for lazy computation of programmatic tools and tool search */
     toolRegistry?: LCToolRegistry;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
@@ -97,6 +93,10 @@ export type LCTool = {
 };
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;
+export type ProgrammaticCache = {
+    toolMap: ToolMap;
+    toolDefs: LCTool[];
+};
 /** Parameters for creating a Tool Search Regex tool */
 export type ToolSearchRegexParams = {
     apiKey?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.0.41",
+  "version": "3.0.43",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/agents/AgentContext.ts

@@ -13,19 +13,6 @@ import type * as t from '@/types';
 import type { createPruneMessages } from '@/messages';
 import { ContentTypes, Providers } from '@/common';
 
-/**
- * Checks if a tool allows the specified caller type.
- * Default is 'direct' only if allowed_callers is not specified.
- */
-function toolAllowsCaller(
-  toolDef: t.LCTool | undefined,
-  caller: t.AllowedCaller
-): boolean {
-  if (!toolDef) return false;
-  const allowedCallers = toolDef.allowed_callers ?? ['direct'];
-  return allowedCallers.includes(caller);
-}
-
 /**
  * Encapsulates agent-specific state that can vary between agents in a multi-agent system
  */
@@ -73,12 +60,17 @@ export class AgentContext {
     });
 
     if (tokenCounter) {
+      // Initialize system runnable BEFORE async tool token calculation
+      // This ensures system message tokens are in instructionTokens before
+      // updateTokenMapWithInstructions is called
+      agentContext.initializeSystemRunnable();
+
       const tokenMap = indexTokenCountMap || {};
       agentContext.indexTokenCountMap = tokenMap;
       agentContext.tokenCalculationPromise = agentContext
         .calculateInstructionTokens(tokenCounter)
         .then(() => {
-          // Update token map with instruction tokens
+          // Update token map with instruction tokens (includes system + tool tokens)
           agentContext.updateTokenMapWithInstructions(tokenMap);
         })
         .catch((err) => {
@@ -122,6 +114,8 @@ export class AgentContext {
    * Used for tool search and programmatic tool calling.
    */
   toolRegistry?: t.LCToolRegistry;
+  /** Set of tool names discovered via tool search (to be loaded) */
+  discoveredToolNames: Set<string> = new Set();
   /** Instructions for this agent */
   instructions?: string;
   /** Additional instructions for this agent */
@@ -137,12 +131,16 @@ export class AgentContext {
     ContentTypes.TEXT;
   /** Whether tools should end the workflow */
   toolEnd: boolean = false;
-  /** System runnable for this agent */
-  systemRunnable?: Runnable<
+  /** Cached system runnable (created lazily) */
+  private cachedSystemRunnable?: Runnable<
     BaseMessage[],
     (BaseMessage | SystemMessage)[],
     RunnableConfig<Record<string, unknown>>
   >;
+  /** Whether system runnable needs rebuild (set when discovered tools change) */
+  private systemRunnableStale: boolean = true;
+  /** Cached system message token count (separate from tool tokens) */
+  private systemMessageTokens: number = 0;
   /** Promise for token calculation initialization */
   tokenCalculationPromise?: Promise<void>;
   /** Format content blocks as strings (for legacy compatibility) */
@@ -203,39 +201,145 @@ export class AgentContext {
     }
 
     this.useLegacyContent = useLegacyContent ?? false;
+  }
+
+  /**
+   * Builds instructions text for tools that are ONLY callable via programmatic code execution.
+   * These tools cannot be called directly by the LLM but are available through the
+   * run_tools_with_code tool.
+   *
+   * Includes:
+   * - Code_execution-only tools that are NOT deferred
+   * - Code_execution-only tools that ARE deferred but have been discovered via tool search
+   */
+  private buildProgrammaticOnlyToolsInstructions(): string {
+    if (!this.toolRegistry) return '';
+
+    const programmaticOnlyTools: t.LCTool[] = [];
+    for (const [name, toolDef] of this.toolRegistry) {
+      const allowedCallers = toolDef.allowed_callers ?? ['direct'];
+      const isCodeExecutionOnly =
+        allowedCallers.includes('code_execution') &&
+        !allowedCallers.includes('direct');
 
-    this.systemRunnable = this.createSystemRunnable();
+      if (!isCodeExecutionOnly) continue;
+
+      // Include if: not deferred OR deferred but discovered
+      const isDeferred = toolDef.defer_loading === true;
+      const isDiscovered = this.discoveredToolNames.has(name);
+      if (!isDeferred || isDiscovered) {
+        programmaticOnlyTools.push(toolDef);
+      }
+    }
+
+    if (programmaticOnlyTools.length === 0) return '';
+
+    const toolDescriptions = programmaticOnlyTools
+      .map((tool) => {
+        let desc = `- **${tool.name}**`;
+        if (tool.description != null && tool.description !== '') {
+          desc += `: ${tool.description}`;
+        }
+        if (tool.parameters) {
+          desc += `\n  Parameters: ${JSON.stringify(tool.parameters, null, 2).replace(/\n/g, '\n  ')}`;
+        }
+        return desc;
+      })
+      .join('\n\n');
+
+    return (
+      '\n\n## Programmatic-Only Tools\n\n' +
+      'The following tools are available exclusively through the `run_tools_with_code` tool. ' +
+      'You cannot call these tools directly; instead, use `run_tools_with_code` with Python code that invokes them.\n\n' +
+      toolDescriptions
+    );
   }
 
   /**
-   * Create system runnable from instructions and calculate tokens if tokenCounter is available
+   * Gets the system runnable, creating it lazily if needed.
+   * Includes instructions, additional instructions, and programmatic-only tools documentation.
+   * Only rebuilds when marked stale (via markToolsAsDiscovered).
    */
-  private createSystemRunnable():
+  get systemRunnable():
     | Runnable<
         BaseMessage[],
         (BaseMessage | SystemMessage)[],
         RunnableConfig<Record<string, unknown>>
       >
     | undefined {
-    let finalInstructions: string | BaseMessageFields | undefined =
-      this.instructions;
+    // Return cached if not stale
+    if (!this.systemRunnableStale && this.cachedSystemRunnable !== undefined) {
+      return this.cachedSystemRunnable;
+    }
+
+    // Stale or first access - rebuild
+    const instructionsString = this.buildInstructionsString();
+    this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+    this.systemRunnableStale = false;
+    return this.cachedSystemRunnable;
+  }
+
+  /**
+   * Explicitly initializes the system runnable.
+   * Call this before async token calculation to ensure system message tokens are counted first.
+   */
+  initializeSystemRunnable(): void {
+    if (this.systemRunnableStale || this.cachedSystemRunnable === undefined) {
+      const instructionsString = this.buildInstructionsString();
+      this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+      this.systemRunnableStale = false;
+    }
+  }
+
+  /**
+   * Builds the raw instructions string (without creating SystemMessage).
+   */
+  private buildInstructionsString(): string {
+    let result = this.instructions ?? '';
 
     if (
       this.additionalInstructions != null &&
       this.additionalInstructions !== ''
     ) {
-      finalInstructions =
-        finalInstructions != null && finalInstructions
-          ? `${finalInstructions}\n\n${this.additionalInstructions}`
-          : this.additionalInstructions;
+      result = result
+        ? `${result}\n\n${this.additionalInstructions}`
+        : this.additionalInstructions;
+    }
+
+    const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
+    if (programmaticToolsDoc) {
+      result = result
+        ? `${result}${programmaticToolsDoc}`
+        : programmaticToolsDoc;
+    }
+
+    return result;
+  }
+
+  /**
+   * Build system runnable from pre-built instructions string.
+   * Only called when content has actually changed.
+   */
+  private buildSystemRunnable(
+    instructionsString: string
+  ):
+    | Runnable<
+        BaseMessage[],
+        (BaseMessage | SystemMessage)[],
+        RunnableConfig<Record<string, unknown>>
+      >
+    | undefined {
+    if (!instructionsString) {
+      // Remove previous tokens if we had a system message before
+      this.instructionTokens -= this.systemMessageTokens;
+      this.systemMessageTokens = 0;
+      return undefined;
     }
 
+    let finalInstructions: string | BaseMessageFields = instructionsString;
+
     // Handle Anthropic prompt caching
-    if (
-      finalInstructions != null &&
-      finalInstructions !== '' &&
-      this.provider === Providers.ANTHROPIC
-    ) {
+    if (this.provider === Providers.ANTHROPIC) {
       const anthropicOptions = this.clientOptions as
         | t.AnthropicClientOptions
         | undefined;
@@ -251,7 +355,7 @@ export class AgentContext {
           content: [
             {
               type: 'text',
-              text: this.instructions,
+              text: instructionsString,
               cache_control: { type: 'ephemeral' },
             },
           ],
@@ -259,19 +363,18 @@ export class AgentContext {
       }
     }
 
-    if (finalInstructions != null && finalInstructions !== '') {
-      const systemMessage = new SystemMessage(finalInstructions);
+    const systemMessage = new SystemMessage(finalInstructions);
 
-      if (this.tokenCounter) {
-        this.instructionTokens += this.tokenCounter(systemMessage);
-      }
-
-      return RunnableLambda.from((messages: BaseMessage[]) => {
-        return [systemMessage, ...messages];
-      }).withConfig({ runName: 'prompt' });
+    // Update token counts (subtract old, add new)
+    if (this.tokenCounter) {
+      this.instructionTokens -= this.systemMessageTokens;
+      this.systemMessageTokens = this.tokenCounter(systemMessage);
+      this.instructionTokens += this.systemMessageTokens;
     }
 
-    return undefined;
+    return RunnableLambda.from((messages: BaseMessage[]) => {
+      return [systemMessage, ...messages];
+    }).withConfig({ runName: 'prompt' });
   }
 
   /**
@@ -279,6 +382,9 @@ export class AgentContext {
    */
   reset(): void {
     this.instructionTokens = 0;
+    this.systemMessageTokens = 0;
+    this.cachedSystemRunnable = undefined;
+    this.systemRunnableStale = true;
     this.lastToken = undefined;
     this.indexTokenCountMap = {};
     this.currentUsage = undefined;
@@ -286,6 +392,7 @@ export class AgentContext {
     this.lastStreamCall = undefined;
     this.tokenTypeSwitch = undefined;
     this.currentTokenType = ContentTypes.TEXT;
+    this.discoveredToolNames.clear();
   }
 
   /**
@@ -345,65 +452,83 @@ export class AgentContext {
   }
 
   /**
-   * Gets a map of tools that allow programmatic (code_execution) calling.
-   * Filters toolMap based on toolRegistry's allowed_callers settings.
-   * @returns ToolMap containing only tools that allow code_execution
+   * Gets the tool registry for deferred tools (for tool search).
+   * @param onlyDeferred If true, only returns tools with defer_loading=true
+   * @returns LCToolRegistry with tool definitions
    */
-  getProgrammaticToolMap(): t.ToolMap {
-    const programmaticMap: t.ToolMap = new Map();
+  getDeferredToolRegistry(onlyDeferred: boolean = true): t.LCToolRegistry {
+    const registry: t.LCToolRegistry = new Map();
 
-    if (!this.toolMap) {
-      return programmaticMap;
+    if (!this.toolRegistry) {
+      return registry;
     }
 
-    for (const [name, tool] of this.toolMap) {
-      const toolDef = this.toolRegistry?.get(name);
-      if (toolAllowsCaller(toolDef, 'code_execution')) {
-        programmaticMap.set(name, tool);
+    for (const [name, toolDef] of this.toolRegistry) {
+      if (!onlyDeferred || toolDef.defer_loading === true) {
+        registry.set(name, toolDef);
       }
     }
 
-    return programmaticMap;
+    return registry;
   }
 
   /**
-   * Gets tool definitions for tools that allow programmatic calling.
-   * Used to send to the Code API for stub generation.
-   * @returns Array of LCTool definitions for programmatic tools
+   * Marks tools as discovered via tool search.
+   * Discovered tools will be included in the next model binding.
+   * Only marks system runnable stale if NEW tools were actually added.
+   * @param toolNames - Array of discovered tool names
+   * @returns true if any new tools were discovered
    */
-  getProgrammaticToolDefs(): t.LCTool[] {
-    if (!this.toolRegistry) {
-      return [];
-    }
-
-    const defs: t.LCTool[] = [];
-    for (const [_name, toolDef] of this.toolRegistry) {
-      if (toolAllowsCaller(toolDef, 'code_execution')) {
-        defs.push(toolDef);
+  markToolsAsDiscovered(toolNames: string[]): boolean {
+    let hasNewDiscoveries = false;
+    for (const name of toolNames) {
+      if (!this.discoveredToolNames.has(name)) {
+        this.discoveredToolNames.add(name);
+        hasNewDiscoveries = true;
       }
     }
-
-    return defs;
+    if (hasNewDiscoveries) {
+      this.systemRunnableStale = true;
+    }
+    return hasNewDiscoveries;
   }
 
   /**
-   * Gets the tool registry for deferred tools (for tool search).
-   * @param onlyDeferred If true, only returns tools with defer_loading=true
-   * @returns LCToolRegistry with tool definitions
+   * Gets tools that should be bound to the LLM.
+   * Includes:
+   * 1. Non-deferred tools with allowed_callers: ['direct']
+   * 2. Discovered tools (from tool search)
+   * @returns Array of tools to bind to model
    */
-  getDeferredToolRegistry(onlyDeferred: boolean = true): t.LCToolRegistry {
-    const registry: t.LCToolRegistry = new Map();
-
-    if (!this.toolRegistry) {
-      return registry;
+  getToolsForBinding(): t.GraphTools | undefined {
+    if (!this.tools || !this.toolRegistry) {
+      return this.tools;
     }
 
-    for (const [name, toolDef] of this.toolRegistry) {
-      if (!onlyDeferred || toolDef.defer_loading === true) {
-        registry.set(name, toolDef);
+    const toolsToInclude = this.tools.filter((tool) => {
+      if (!('name' in tool)) {
+        return true; // No name, include by default
       }
-    }
 
-    return registry;
+      const toolDef = this.toolRegistry?.get(tool.name);
+      if (!toolDef) {
+        return true; // Not in registry, include by default
+      }
+
+      // Check if discovered (overrides defer_loading)
+      if (this.discoveredToolNames.has(tool.name)) {
+        // Discovered tools must still have allowed_callers: ['direct']
+        const allowedCallers = toolDef.allowed_callers ?? ['direct'];
+        return allowedCallers.includes('direct');
+      }
+
+      // Not discovered: must be direct-callable AND not deferred
+      const allowedCallers = toolDef.allowed_callers ?? ['direct'];
+      return (
+        allowedCallers.includes('direct') && toolDef.defer_loading !== true
+      );
+    });
+
+    return toolsToInclude;
   }
 }