@librechat/agents 3.6.9 → 3.6.11

package/src/tools/ToolNode.ts

@@ -62,7 +62,6 @@ import {
   SUBAGENT_PARENT_BATCH_CONFIG_KEY,
   SUBAGENT_REPLAY_CONTROLLER,
 } from '@/tools/subagent/SubagentReplay';
-import { attachRunStepResumeState } from '@/tools/runStepResume';
 import {
   INTENT_ARG,
   readOutcomeFields,
@@ -95,8 +94,17 @@ import {
   resolveLocalToolRegistry,
   resolveLocalExecutionTools,
 } from '@/tools/local';
+import {
+  type CallerCapabilityProjection,
+  createCallerCapabilityProjectionSnapshot,
+  isToolDefinitionActive,
+  isProgrammaticControlTool,
+  mergeCallerCapabilityDefinitions,
+  resolveCallerCapabilityProjection,
+} from '@/tools/CallerCapabilities';
 import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { Constants, GraphEvents, CODE_EXECUTION_TOOLS } from '@/common';
+import { attachRunStepResumeState } from '@/tools/runStepResume';
 
 /** Host-facing batch requests must not carry the batch's breaker scope —
  * hosts spread `configurable` into their own run configs. */
@@ -110,6 +118,7 @@ function stripRunBreakerScope(
   return rest;
 }
 import { convertInjectedMessages } from '@/messages/injected';
+import { stampSyntheticProviderMessage } from '@/messages/provenance';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { RunnableCallable, composeAbortSignals } from '@/utils';
 import {
@@ -692,8 +701,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   >();
   /** Tool registry for filtering (lazy computation of programmatic maps) */
   private toolRegistry?: t.LCToolRegistry;
-  /** Cached programmatic tools (computed once on first PTC call) */
-  private programmaticCache?: t.ProgrammaticCache;
+  /** Schema-only definitions used when event mode has no runtime registry. */
+  private toolDefinitions?: t.LCToolRegistry;
+  /** Tool-map entries created or replaced by the local execution resolver. */
+  private localImplementationNames = new Set<string>();
+  /** Reads deferred-tool discovery state from the owning agent context. */
+  private getDiscoveredToolNames?: () => readonly string[];
   /** Reference to Graph's sessions map for automatic session injection */
   private sessions?: t.ToolSessionMap;
   /** Partition within `sessions` owned by this agent's execution profile. */
@@ -797,6 +810,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     handleToolErrors,
     loadRuntimeTools,
     toolRegistry,
+    toolDefinitions,
+    getDiscoveredToolNames,
     sessions,
     codeSessionKey,
     eventDrivenMode,
@@ -872,6 +887,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       toolRegistry,
       toolExecution,
     });
+    this.toolDefinitions = toolDefinitions;
+    this.getDiscoveredToolNames = getDiscoveredToolNames;
     this.sessions = sessions;
     this.codeSessionKey = codeSessionKey ?? Constants.EXECUTE_CODE;
     this.eventDrivenMode = eventDrivenMode ?? false;
@@ -986,10 +1003,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     const resolved = resolveLocalExecutionTools({
       toolMap: this.toolMap,
       toolExecution: this.toolExecution,
+      toolRegistry: this.toolRegistry,
       fileCheckpointer: this.fileCheckpointer,
     });
 
     this.toolMap = resolved.toolMap;
+    this.localImplementationNames = resolved.localImplementationNames;
     if (resolved.fileCheckpointer != null) {
       this.fileCheckpointer = resolved.fileCheckpointer;
     }
@@ -1001,7 +1020,6 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       ...(this.directToolNames ?? new Set<string>()),
       ...resolved.directToolNames,
     ]);
-    this.programmaticCache = undefined;
   }
 
   /**
@@ -1097,30 +1115,61 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.settledInterruptingResults.clear();
   }
 
-  /**
-   * Returns cached programmatic tools, computing once on first access.
-   * Single iteration builds both toolMap and toolDefs simultaneously.
-   */
-  private getProgrammaticTools(): { toolMap: t.ToolMap; toolDefs: t.LCTool[] } {
-    if (this.programmaticCache) return this.programmaticCache;
+  /** Returns the live caller projection used by direct and event execution. */
+  private getCallerCapabilityProjection(): CallerCapabilityProjection {
+    const discoveredToolNames = new Set(
+      this.getDiscoveredToolNames?.() ?? []
+    );
+    return resolveCallerCapabilityProjection(
+      mergeCallerCapabilityDefinitions(
+        this.toolDefinitions?.values(),
+        this.toolRegistry?.values()
+      ),
+      (toolDef) => isToolDefinitionActive(toolDef, discoveredToolNames)
+    );
+  }
+
+  /** Serializes the live caller projection for event-driven hosts. */
+  private getCallerCapabilityProjectionSnapshot(): t.CallerCapabilityProjectionSnapshot {
+    return createCallerCapabilityProjectionSnapshot(
+      this.getCallerCapabilityProjection()
+    );
+  }
 
+  /** Returns active tools projected by their effective caller capabilities. */
+  private getProgrammaticTools(): t.ProgrammaticCache {
     const toolMap: t.ToolMap = new Map();
     const toolDefs: t.LCTool[] = [];
-
-    if (this.toolRegistry) {
-      for (const [name, toolDef] of this.toolRegistry) {
-        if (
-          (toolDef.allowed_callers ?? ['direct']).includes('code_execution')
-        ) {
-          toolDefs.push(toolDef);
-          const tool = this.toolMap.get(name);
-          if (tool) toolMap.set(name, tool);
-        }
+    const discoveredToolNames = new Set(
+      this.getDiscoveredToolNames?.() ?? []
+    );
+    const executableCapabilities = resolveCallerCapabilityProjection(
+      this.toolRegistry?.values() ?? [],
+      (toolDef) => isToolDefinitionActive(toolDef, discoveredToolNames)
+    );
+    for (const toolDef of executableCapabilities.codeExecutionTools) {
+      if (
+        this.eventDrivenMode &&
+        this.directToolNames?.has(toolDef.name) !== true &&
+        !this.localImplementationNames.has(toolDef.name)
+      ) {
+        continue;
+      }
+      const tool = this.toolMap.get(toolDef.name);
+      if (tool != null) {
+        toolMap.set(toolDef.name, tool);
+        toolDefs.push(toolDef);
       }
     }
+    const activeCapabilities = this.getCallerCapabilityProjection();
 
-    this.programmaticCache = { toolMap, toolDefs };
-    return this.programmaticCache;
+    return {
+      toolMap,
+      toolDefs,
+      disallowedToolDefs: activeCapabilities.directOnlyTools
+        .filter((toolDef) => !isProgrammaticControlTool(toolDef.name))
+        .map((toolDef) => ({ name: toolDef.name })),
+    };
   }
 
   /**
@@ -1331,11 +1380,14 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         call.name === Constants.PROGRAMMATIC_TOOL_CALLING ||
         call.name === Constants.BASH_PROGRAMMATIC_TOOL_CALLING
       ) {
-        const { toolMap, toolDefs } = this.getProgrammaticTools();
+        const { toolMap, toolDefs, disallowedToolDefs } =
+          this.getProgrammaticTools();
         invokeParams = {
           ...invokeParams,
           toolMap,
           toolDefs,
+          disallowedToolDefs,
+          programmaticToolName: call.name,
           // Plumb the hook context into the programmatic-tool path so
           // inner tool calls made via the in-process bridge can run
           // through `PreToolUse` (deny / updatedInput) before reaching
@@ -3444,6 +3496,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               // the eager path sends `agentContext.agentId` — this must
               // match it at the top level too.
               agentId: this.executingAgentId,
+              callerCapabilityProjection:
+                this.getCallerCapabilityProjectionSnapshot(),
               configurable: stripRunBreakerScope(
                   config.configurable as Record<string, unknown> | undefined
               ),
@@ -3927,10 +3981,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        * a user message; `role` is metadata only.
        */
       injected.push(
-        new HumanMessage({
-          content: batchAdditionalContexts.join('\n\n'),
-          additional_kwargs: { role: 'system', source: 'hook' },
-        })
+        stampSyntheticProviderMessage(
+          new HumanMessage({
+            content: batchAdditionalContexts.join('\n\n'),
+            additional_kwargs: { role: 'system', source: 'hook' },
+          })
+        )
       );
     }
 
@@ -4423,13 +4479,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         directAdditionalContexts.length > 0
           ? [
             sendOutput,
-            new HumanMessage({
-              content: directAdditionalContexts.join('\n\n'),
-              // Match the event-driven path's marker so hosts /
-              // model-side annotators treat this as system intent
-              // rather than ordinary user text. Codex P2 [46].
-              additional_kwargs: { role: 'system', source: 'hook' },
-            }),
+            stampSyntheticProviderMessage(
+              new HumanMessage({
+                content: directAdditionalContexts.join('\n\n'),
+                // Match the event-driven path's marker so hosts /
+                // model-side annotators treat this as system intent
+                // rather than ordinary user text. Codex P2 [46].
+                additional_kwargs: { role: 'system', source: 'hook' },
+              })
+            ),
           ]
           : [sendOutput];
       await this.handleRunToolCompletions(
@@ -4477,7 +4535,6 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         this.toolMap =
           toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
         this.applyToolExecutionOverrides();
-        this.programmaticCache = undefined; // Invalidate cache on toolMap change
       }
 
       const filteredCalls =
@@ -4721,14 +4778,16 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const directInjected: BaseMessage[] =
           directAdditionalContexts.length > 0
             ? [
-              new HumanMessage({
-                content: directAdditionalContexts.join('\n\n'),
-                // System-role metadata to match the event-driven
-                // path so policy/recovery guidance is treated
-                // consistently regardless of whether the tool ran
-                // direct or dispatched. Codex P2 [46].
-                additional_kwargs: { role: 'system', source: 'hook' },
-              }),
+              stampSyntheticProviderMessage(
+                new HumanMessage({
+                  content: directAdditionalContexts.join('\n\n'),
+                  // System-role metadata to match the event-driven
+                  // path so policy/recovery guidance is treated
+                  // consistently regardless of whether the tool ran
+                  // direct or dispatched. Codex P2 [46].
+                  additional_kwargs: { role: 'system', source: 'hook' },
+                })
+              ),
             ]
             : [];
         outputs = [
@@ -4782,13 +4841,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               ...promotedPrefix,
               ...toolOutputs,
               ...invalidCallResults,
-              new HumanMessage({
-                content: directAdditionalContexts.join('\n\n'),
-                // Same system-role marker the event-driven path
-                // uses so direct vs dispatched is invisible to
-                // downstream consumers. Codex P2 [46].
-                additional_kwargs: { role: 'system', source: 'hook' },
-              }),
+              stampSyntheticProviderMessage(
+                new HumanMessage({
+                  content: directAdditionalContexts.join('\n\n'),
+                  // Same system-role marker the event-driven path
+                  // uses so direct vs dispatched is invisible to
+                  // downstream consumers. Codex P2 [46].
+                  additional_kwargs: { role: 'system', source: 'hook' },
+                })
+              ),
             ]
             : [...promotedPrefix, ...toolOutputs, ...invalidCallResults];
       }

package/src/tools/cloudflare/CloudflareProgrammaticToolCalling.ts

@@ -9,14 +9,17 @@ import {
   ProgrammaticToolCallingDescription,
   ProgrammaticToolCallingName,
   ProgrammaticToolCallingSchema,
-  filterToolsByUsage,
 } from '@/tools/ProgrammaticToolCalling';
 import {
   BashProgrammaticToolCallingDescription,
   BashProgrammaticToolCallingSchema,
-  filterBashToolsByUsage,
   normalizeToBashIdentifier,
 } from '@/tools/BashProgrammaticToolCalling';
+import {
+  resolveProgrammaticToolDefinitions,
+  selectProgrammaticTools,
+  type ProgrammaticInvocationParams,
+} from '@/tools/ProgrammaticCallerPolicy';
 import { Constants } from '@/common';
 import {
   clientExecTimeoutMs,
@@ -27,13 +30,7 @@ import {
   validateCloudflareBashCommand,
 } from './CloudflareSandboxExecutionEngine';
 
-type ProgrammaticParams = {
-  code: string;
-  timeout?: number;
-  lang?: string;
-  runtime?: string;
-  language?: string;
-};
+type ProgrammaticParams = ProgrammaticInvocationParams;
 
 const DEFAULT_TIMEOUT = 60000;
 const MIN_TIMEOUT = 1000;
@@ -224,15 +221,8 @@ function resolveRuntime(params: ProgrammaticParams): 'python' | 'bash' {
   return raw === 'py' || raw === 'python' ? 'python' : 'bash';
 }
 
-function filterNativeTools(
-  toolDefs: t.LCTool[],
-  code: string,
-  runtime: 'python' | 'bash'
-): t.LCTool[] {
-  const nativeDefs = toolDefs.filter((def) => NATIVE_TOOL_NAMES.has(def.name));
-  const filter =
-    runtime === 'bash' ? filterBashToolsByUsage : filterToolsByUsage;
-  return filter(nativeDefs, code);
+function filterNativeTools(toolDefs: t.LCTool[]): t.LCTool[] {
+  return toolDefs.filter((def) => NATIVE_TOOL_NAMES.has(def.name));
 }
 
 function indent(code: string, spaces = 4): string {
@@ -1060,14 +1050,22 @@ async function runProgrammatic(args: {
   cloudflareConfig: t.CloudflareSandboxExecutionConfig;
   runtime: 'python' | 'bash';
 }): Promise<[string, t.ProgrammaticExecutionArtifact]> {
-  const toolCall = (args.config?.toolCall ??
-    {}) as Partial<t.ProgrammaticCache>;
-  const toolDefs = toolCall.toolDefs ?? [];
-  const effectiveTools = filterNativeTools(
-    toolDefs,
-    args.params.code,
-    args.runtime
-  );
+  const toolCall = (args.config?.toolCall ?? {}) as Partial<
+    t.ProgrammaticCache
+  > & { tools?: t.LCTool[] };
+  const toolDefs = resolveProgrammaticToolDefinitions(toolCall);
+  const programmaticToolName =
+    toolCall.programmaticToolName ??
+    (args.runtime === 'bash'
+      ? Constants.BASH_PROGRAMMATIC_TOOL_CALLING
+      : Constants.PROGRAMMATIC_TOOL_CALLING);
+  const selectedTools = selectProgrammaticTools({
+    requestedToolNames: args.params.tool_manifest,
+    allowedToolDefs: toolDefs,
+    disallowedToolDefs: toolCall.disallowedToolDefs,
+    programmaticToolName,
+  });
+  const effectiveTools = filterNativeTools(selectedTools);
   const timeoutMs = clampExecutionTimeout(
     args.params.timeout,
     args.cloudflareConfig.timeoutMs

package/src/tools/local/LocalProgrammaticToolCalling.ts

@@ -7,7 +7,6 @@ import type { AddressInfo } from 'net';
 import type * as t from '@/types';
 import {
   executeTools,
-  filterToolsByUsage,
   formatCompletedResponse,
   normalizeToPythonIdentifier,
   ProgrammaticToolCallingName,
@@ -17,9 +16,13 @@ import {
 import {
   BashProgrammaticToolCallingSchema,
   BashProgrammaticToolCallingDescription,
-  filterBashToolsByUsage,
   normalizeToBashIdentifier,
 } from '@/tools/BashProgrammaticToolCalling';
+import {
+  resolveProgrammaticToolDefinitions,
+  selectProgrammaticTools,
+  type ProgrammaticInvocationParams,
+} from '@/tools/ProgrammaticCallerPolicy';
 import {
   executeLocalBash,
   executeLocalCode,
@@ -150,15 +153,7 @@ function constantTimeEquals(a: string, b: string): boolean {
 
 type LocalProgrammaticRuntime = 'python' | 'bash';
 
-type LocalProgrammaticParams = {
-  code: string;
-  timeout?: number;
-  lang?: string;
-  runtime?: string;
-  language?: string;
-};
-
-type ToolFilter = (toolDefs: t.LCTool[], code: string) => t.LCTool[];
+type LocalProgrammaticParams = ProgrammaticInvocationParams;
 
 function resolveRuntime(
   params: LocalProgrammaticParams
@@ -547,17 +542,16 @@ ${code}
 
 function getProgrammaticContext(config?: {
   toolCall?: unknown;
-}): Partial<t.ProgrammaticCache> {
-  return (config?.toolCall ?? {}) as Partial<t.ProgrammaticCache>;
+}): Partial<t.ProgrammaticCache> & { tools?: t.LCTool[] } {
+  return (config?.toolCall ?? {}) as Partial<t.ProgrammaticCache> & {
+    tools?: t.LCTool[];
+  };
 }
 
 function createEffectiveToolMap(
   toolMap: t.ToolMap,
-  toolDefs: t.LCTool[],
-  code: string,
-  filterTools: ToolFilter
+  effectiveTools: t.LCTool[]
 ): { effectiveTools: t.LCTool[]; effectiveMap: t.ToolMap } {
-  const effectiveTools = filterTools(toolDefs, code);
   const effectiveMap = new Map<string, t.GenericTool>(
     effectiveTools
       .map((def) => {
@@ -578,9 +572,22 @@ async function runLocalProgrammaticTool(args: {
   localConfig: t.LocalExecutionConfig;
   runtime: LocalProgrammaticRuntime;
 }): Promise<[string, t.ProgrammaticExecutionArtifact]> {
-  const { toolMap, toolDefs, hookContext } = getProgrammaticContext(
-    args.config
-  );
+  const context = getProgrammaticContext(args.config);
+  const { toolMap, disallowedToolDefs, programmaticToolName, hookContext } =
+    context;
+  const toolDefs = resolveProgrammaticToolDefinitions(context);
+
+  const runnerName =
+    programmaticToolName ??
+    (args.runtime === 'bash'
+      ? Constants.BASH_PROGRAMMATIC_TOOL_CALLING
+      : Constants.PROGRAMMATIC_TOOL_CALLING);
+  const selectedTools = selectProgrammaticTools({
+    requestedToolNames: args.params.tool_manifest,
+    allowedToolDefs: toolDefs,
+    disallowedToolDefs,
+    programmaticToolName: runnerName,
+  });
 
   if (toolMap == null || toolMap.size === 0) {
     throw new Error('No toolMap provided for local programmatic execution.');
@@ -593,9 +600,7 @@ async function runLocalProgrammaticTool(args: {
 
   const { effectiveTools, effectiveMap } = createEffectiveToolMap(
     toolMap,
-    toolDefs,
-    args.params.code,
-    args.runtime === 'bash' ? filterBashToolsByUsage : filterToolsByUsage
+    selectedTools
   );
   const bridge = await createToolBridge(effectiveMap, hookContext);