@librechat/agents 3.6.8 → 3.6.10

package/src/agents/AgentContext.ts

@@ -32,6 +32,16 @@ import {
   Constants,
   Providers,
 } from '@/common';
+import {
+  isProgrammaticRunnerAutoBound,
+  resolveLocalToolRegistry,
+} from '@/tools/local/resolveLocalExecutionTools';
+import {
+  allowsToolCaller,
+  isToolDefinitionActive,
+  isProgrammaticControlTool,
+  resolveCallerCapabilityProjection,
+} from '@/tools/CallerCapabilities';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { apportionTokenCounts } from '@/utils/tokens';
 import { isThinkingEnabled } from '@/llm/request';
@@ -59,7 +69,8 @@ export class AgentContext {
   static fromConfig(
     agentConfig: t.AgentInputs,
     tokenCounter?: t.TokenCounter,
-    indexTokenCountMap?: Record<string, number>
+    indexTokenCountMap?: Record<string, number>,
+    toolExecution?: t.ToolExecutionConfig
   ): AgentContext {
     const {
       agentId,
@@ -103,6 +114,7 @@ export class AgentContext {
       tools,
       toolMap,
       toolRegistry,
+      toolExecution,
       toolDefinitions,
       instructions,
       additionalInstructions: additional_instructions,
@@ -269,6 +281,8 @@ export class AgentContext {
    * Used for tool search and programmatic tool calling.
    */
   toolRegistry?: t.LCToolRegistry;
+  /** Run-scoped backend used to identify auto-bound programmatic runners. */
+  private toolExecution?: t.ToolExecutionConfig;
   /**
    * Serializable tool definitions for event-driven execution.
    * When provided, ToolNode operates in event-driven mode.
@@ -385,6 +399,7 @@ export class AgentContext {
     tools,
     toolMap,
     toolRegistry,
+    toolExecution,
     toolDefinitions,
     instructions,
     additionalInstructions,
@@ -410,6 +425,7 @@ export class AgentContext {
     tools?: t.GraphTools;
     toolMap?: t.ToolMap;
     toolRegistry?: t.LCToolRegistry;
+    toolExecution?: t.ToolExecutionConfig;
     toolDefinitions?: t.LCTool[];
     instructions?: string;
     additionalInstructions?: string;
@@ -434,7 +450,11 @@ export class AgentContext {
     this.tokenCounter = tokenCounter;
     this.tools = tools;
     this.toolMap = toolMap;
-    this.toolRegistry = toolRegistry;
+    this.toolRegistry = resolveLocalToolRegistry({
+      toolRegistry,
+      toolExecution,
+    });
+    this.toolExecution = toolExecution;
     this.toolDefinitions = toolDefinitions;
     this.instructions = instructions;
     this.additionalInstructions = additionalInstructions;
@@ -461,37 +481,46 @@ export class AgentContext {
     }
   }
 
-  /**
-   * 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
-   * configured programmatic tool.
-   *
-   * Includes:
-   * - Code_execution-only tools that are NOT deferred
-   * - Code_execution-only tools that ARE deferred but have been discovered via tool search
-   */
+  /** Builds the caller boundary and schemas for programmatic-only tools. */
   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');
-
-      if (!isCodeExecutionOnly) continue;
-
-      const isDeferred = toolDef.defer_loading === true;
-      const isDiscovered = this.discoveredToolNames.has(name);
-      if (!isDeferred || isDiscovered) {
-        programmaticOnlyTools.push(toolDef);
-      }
+    const capabilities = resolveCallerCapabilityProjection(
+      this.toolRegistry.values(),
+      (toolDef) => isToolDefinitionActive(toolDef, this.discoveredToolNames)
+    );
+    const programmaticOnlyTools = capabilities.codeExecutionOnlyTools;
+    const programmaticToolNames = capabilities.codeExecutionTools.map(
+      (toolDef) => toolDef.name
+    );
+    const directOnlyToolNames = capabilities.directOnlyTools
+      .map((toolDef) => toolDef.name)
+      .filter((name) => !isProgrammaticControlTool(name));
+
+    const programmaticTools = this.getProgrammaticToolInstructionTargets();
+    if (programmaticTools.length === 0) return '';
+    const programmaticRunnerNames = programmaticTools
+      .map((tool) => `\`${tool.name}\``)
+      .join(' or ');
+    const quotedProgrammaticNames =
+      programmaticToolNames.length > 0
+        ? programmaticToolNames.map((name) => `\`${name}\``).join(', ')
+        : 'none';
+    const directOnlyBoundary =
+      directOnlyToolNames.length > 0
+        ? `\nCall these tools directly; never list them in the \`tool_manifest\` or reference them inside ${programmaticRunnerNames}: ${directOnlyToolNames
+          .map((name) => `\`${name}\``)
+          .join(', ')}. Every ${programmaticRunnerNames} call must include a \`tool_manifest\` containing the exact registered names used by its code; the manifest is validated before execution starts.`
+        : '';
+    const boundary =
+      '\n\n## Programmatic Tool Calling\n\n' +
+      `Only these tools may be invoked inside ${programmaticRunnerNames}: ${quotedProgrammaticNames}.` +
+      directOnlyBoundary;
+
+    if (programmaticOnlyTools.length === 0) {
+      return boundary;
     }
 
-    if (programmaticOnlyTools.length === 0) return '';
-
-    const programmaticTool = this.getProgrammaticToolInstructionTarget();
     const toolDescriptions = programmaticOnlyTools
       .map((tool) => {
         let desc = `- **${tool.name}**`;
@@ -506,41 +535,64 @@ export class AgentContext {
       .join('\n\n');
 
     return (
-      '\n\n## Programmatic-Only Tools\n\n' +
-      `The following tools are available exclusively through the \`${programmaticTool.name}\` tool. ` +
-      `You cannot call these tools directly; instead, use \`${programmaticTool.name}\` with ${programmaticTool.language} code that invokes them.\n\n` +
+      boundary +
+      '\n\n### Programmatic-Only Tools\n\n' +
+      `The following tools are available exclusively through ${programmaticRunnerNames}. ` +
+      `You cannot call these tools directly; instead, ${programmaticTools
+        .map(
+          (tool) =>
+            `use \`${tool.name}\` with ${tool.codeGuidance} that invokes them`
+        )
+        .join(', or ')}.\n\n` +
       toolDescriptions
     );
   }
 
-  private getProgrammaticToolInstructionTarget(): {
+  private getProgrammaticToolInstructionTargets(): Array<{
     name: string;
-    language: 'bash' | 'Python';
-    } {
-    if (this.hasAvailableTool(Constants.BASH_PROGRAMMATIC_TOOL_CALLING)) {
-      return {
+    codeGuidance: string;
+  }> {
+    const targets: Array<{ name: string; codeGuidance: string }> = [];
+    if (
+      this.hasBoundTool(Constants.BASH_PROGRAMMATIC_TOOL_CALLING) ||
+      isProgrammaticRunnerAutoBound(
+        Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+        this.toolExecution
+      )
+    ) {
+      targets.push({
         name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
-        language: 'bash',
-      };
+        codeGuidance: 'Bash code',
+      });
     }
 
-    if (this.hasAvailableTool(Constants.PROGRAMMATIC_TOOL_CALLING)) {
-      return { name: Constants.PROGRAMMATIC_TOOL_CALLING, language: 'Python' };
+    if (
+      this.hasBoundTool(Constants.PROGRAMMATIC_TOOL_CALLING) ||
+      isProgrammaticRunnerAutoBound(
+        Constants.PROGRAMMATIC_TOOL_CALLING,
+        this.toolExecution
+      )
+    ) {
+      const localDefault =
+        this.toolExecution?.engine === 'local' ||
+        this.toolExecution?.engine === 'cloudflare-sandbox';
+      targets.push({
+        name: Constants.PROGRAMMATIC_TOOL_CALLING,
+        codeGuidance: localDefault
+          ? 'Bash code by default, or set `lang: "py"` to use Python code'
+          : 'Python code',
+      });
     }
 
-    return { name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING, language: 'bash' };
+    return targets;
   }
 
-  private hasAvailableTool(name: string): boolean {
-    if (this.toolDefinitions?.some((tool) => tool.name === name) === true)
-      return true;
-    if (
-      this.tools?.some((tool) => 'name' in tool && tool.name === name) === true
-    ) {
-      return true;
-    }
-    if (this.toolMap?.has(name) === true) return true;
-    return this.toolRegistry?.has(name) === true;
+  private hasBoundTool(name: string): boolean {
+    return (
+      this.getToolsForBinding()?.some(
+        (tool) => 'name' in tool && tool.name === name
+      ) === true
+    );
   }
 
   /**
@@ -1083,15 +1135,10 @@ export class AgentContext {
      * alone left programmatic-only definitions counted in
      * `toolSchemaTokens` even though they were never bound.
      */
-    return this.toolDefinitions.filter((def) => {
-      const allowedCallers = def.allowed_callers ?? ['direct'];
-      if (!allowedCallers.includes('direct')) {
-        return false;
-      }
-      return (
-        def.defer_loading !== true || this.discoveredToolNames.has(def.name)
-      );
-    });
+    return resolveCallerCapabilityProjection(
+      this.toolDefinitions,
+      (toolDef) => isToolDefinitionActive(toolDef, this.discoveredToolNames)
+    ).directTools;
   }
 
   /**
@@ -1807,14 +1854,9 @@ export class AgentContext {
         return true;
       }
 
-      if (this.discoveredToolNames.has(tool.name)) {
-        const allowedCallers = toolDef.allowed_callers ?? ['direct'];
-        return allowedCallers.includes('direct');
-      }
-
-      const allowedCallers = toolDef.allowed_callers ?? ['direct'];
       return (
-        allowedCallers.includes('direct') && toolDef.defer_loading !== true
+        allowsToolCaller(toolDef, 'direct') &&
+        isToolDefinitionActive(toolDef, this.discoveredToolNames)
       );
     });
   }

package/src/agents/projection.ts

@@ -13,6 +13,8 @@ export interface ProjectAgentContextUsageParams {
   indexTokenCountMap?: Record<string, number>;
   /** Provider-calibrated ratio from a prior snapshot, applied as a static seed. */
   calibrationRatio?: number;
+  /** Execution backend used to synthesize the live effective tool registry. */
+  toolExecution?: t.ToolExecutionConfig;
   runId?: string;
   agentId?: string;
 }
@@ -32,10 +34,16 @@ export async function projectAgentContextUsage({
   tokenCounter,
   indexTokenCountMap,
   calibrationRatio,
+  toolExecution,
   runId,
   agentId,
 }: ProjectAgentContextUsageParams): Promise<t.ContextUsageEvent | null> {
-  const context = AgentContext.fromConfig(agent, tokenCounter, indexTokenCountMap);
+  const context = AgentContext.fromConfig(
+    agent,
+    tokenCounter,
+    indexTokenCountMap,
+    toolExecution
+  );
   await context.tokenCalculationPromise;
   return context.projectContextUsage(messages, {
     runId,

package/src/graphs/Graph.ts

@@ -34,6 +34,7 @@ import type {
 import type {
   GraphFactory,
   GraphFactoryDependencies,
+  GraphFactoryRequest,
 } from '@/graphs/graphFactory';
 import type { OverflowRecoveryPlan } from '@/llm/contextOverflowRecovery';
 import type { FallbackErrorContext } from '@/llm/invoke';
@@ -61,6 +62,7 @@ import {
   resolveBedrockPromptCacheTtl,
   supportsBedrockToolCache,
   isSyntheticProviderContextMessage,
+  compactSyntheticProviderContextMessage,
   getMessageId,
   getMessageCreationContentMetadata,
   splitAssistantTextContentByPhase,
@@ -73,6 +75,7 @@ import {
   strictAlternationProviders,
   appendPredecessorHandoffCue,
   removePredecessorHandoffCue,
+  stampSyntheticProviderMessage,
 } from '@/messages';
 import {
   Constants,
@@ -133,11 +136,6 @@ import {
   resolveLangfuseConfig,
   resolveToolOutputTracingConfig,
 } from '@/langfuseConfig';
-import {
-  compactToolContent,
-  getToolContentCharLength,
-  serializeToolContentBounded,
-} from '@/utils/toolContent';
 import {
   annotateMessagesForLLM,
   ToolOutputReferenceRegistry,
@@ -146,6 +144,10 @@ import {
   resolveLangfuseRuntimeScope,
   withLangfuseRuntimeScope,
 } from '@/langfuseRuntimeScope';
+import {
+  getToolContentCharLength,
+  serializeToolContentBounded,
+} from '@/utils/toolContent';
 import {
   appendCallbacks,
   findCallback,
@@ -412,7 +414,9 @@ function getCurrentStepIds({
     if (stepKey !== baseStepKey && !stepKey.startsWith(`${baseStepKey}_`)) {
       continue;
     }
-    currentStepIds.push(...stepIds);
+    for (const stepId of stepIds) {
+      currentStepIds.push(stepId);
+    }
   }
   return currentStepIds;
 }
@@ -1457,6 +1461,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       subagentExecutionContext,
       preemption,
       streamLimits,
+      toolExecution,
     }: t.StandardGraphInput,
     dependencies?: GraphFactoryDependencies
   ) {
@@ -1482,6 +1487,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.subagentExecutionContext = subagentExecutionContext;
     this.preemption = preemption;
     this.streamLimits = resolveStreamLimits(streamLimits);
+    this.toolExecution = toolExecution;
 
     if (agents.length === 0) {
       throw new Error('At least one agent configuration is required');
@@ -1491,7 +1497,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       const agentContext = AgentContext.fromConfig(
         agentConfig,
         tokenCounter,
-        indexTokenCountMap
+        indexTokenCountMap,
+        toolExecution
       );
       if (calibrationRatio != null && calibrationRatio > 0) {
         agentContext.calibrationRatio = calibrationRatio;
@@ -2557,6 +2564,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         executingAgentId: agentContext?.agentId,
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
+        getDiscoveredToolNames: (): readonly string[] =>
+          agentContext?.getDiscoveredTools() ?? [],
         hookRegistry: this.hookRegistry,
         humanInTheLoop: this.humanInTheLoop,
         eagerEventToolExecution: this.eagerEventToolExecution,
@@ -2634,6 +2643,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       errorHandler: (data, metadata): Promise<boolean> =>
         StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       toolRegistry: agentContext?.toolRegistry,
+      getDiscoveredToolNames: (): readonly string[] =>
+        agentContext?.getDiscoveredTools() ?? [],
       sessions: this.sessions,
       codeSessionKey: agentContext?.codeSessionKey,
       toolExecution: this.toolExecution,
@@ -2839,6 +2850,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       const rawToolsForBinding = resolveLocalToolsForBinding({
         tools: agentContext.getToolsForBinding(),
         toolExecution: this.toolExecution,
+        toolRegistry: agentContext.toolRegistry,
+        discoveredToolNames: new Set(agentContext.getDiscoveredTools()),
       });
 
       /**
@@ -3553,17 +3566,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         const buildCandidate = (scale: number): BaseMessage[] => {
           const compacted = [...candidate];
           for (const { index, message, chars } of synthetic) {
-            const content = compactToolContent(
-              message.content,
+            compacted[index] = compactSyntheticProviderContextMessage(
+              message,
               Math.floor(chars * scale)
-            ).content;
-            compacted[index] = new HumanMessage({
-              content,
-              id: message.id,
-              name: message.name,
-              additional_kwargs: message.additional_kwargs,
-              response_metadata: message.response_metadata,
-            });
+            );
           }
           return compacted;
         };
@@ -4725,15 +4731,26 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     );
     if (contexts.length > 0) {
       injected.push(
-        new HumanMessage({
-          content: contexts.join('\n\n'),
-          additional_kwargs: { role: 'system', isMeta: true, source: 'hook' },
-        })
+        stampSyntheticProviderMessage(
+          new HumanMessage({
+            content: contexts.join('\n\n'),
+            additional_kwargs: {
+              role: 'system',
+              isMeta: true,
+              source: 'hook',
+            },
+          })
+        )
       );
     }
     if (result.injectedMessages.length > 0) {
       try {
-        injected.push(...convertInjectedMessages(result.injectedMessages));
+        const convertedMessages = convertInjectedMessages(
+          result.injectedMessages
+        );
+        for (const convertedMessage of convertedMessages) {
+          injected.push(convertedMessage);
+        }
       } catch (e) {
         console.warn(
           '[StandardGraph] Failed to convert PreemptBoundary injectedMessages:',
@@ -4805,7 +4822,23 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           };
           const checkpointer = this.compileOptions?.checkpointer;
           return (request): StandardGraph => {
-            const childGraph = graphFactory(request);
+            const configuredRequest: GraphFactoryRequest =
+              request.kind === 'multi-agent'
+                ? {
+                  kind: 'multi-agent',
+                  input: {
+                    ...request.input,
+                    toolExecution: runtimeConfig.toolExecution,
+                  },
+                }
+                : {
+                  kind: 'standard',
+                  input: {
+                    ...request.input,
+                    toolExecution: runtimeConfig.toolExecution,
+                  },
+                };
+            const childGraph = graphFactory(configuredRequest);
             if (subagentModelOverride != null) {
               childGraph.overrideModel = subagentModelOverride;
               childGraph.setSubagentModelOverride(subagentModelOverride);