@librechat/agents 3.6.9 → 3.6.11

package/src/run.ts

@@ -93,6 +93,7 @@ import {
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { LANGFUSE_OPERATION_METADATA_KEY } from '@/langfuseOperation';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
+import { stampSyntheticProviderMessage } from '@/messages/provenance';
 import { initializeLangfuseTracing } from './instrumentation';
 import { seedRunInitialSessions } from '@/utils/toolSessions';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
@@ -469,6 +470,7 @@ export class Run<_T extends t.BaseGraphState> {
         subagentTasks: this.subagentTasks,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
+        toolExecution: this.toolExecution,
       },
     });
     /** Propagate compile options from graph config */
@@ -508,6 +510,7 @@ export class Run<_T extends t.BaseGraphState> {
         subagentTasks: this.subagentTasks,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
+        toolExecution: this.toolExecution,
       },
     });
 
@@ -699,10 +702,12 @@ export class Run<_T extends t.BaseGraphState> {
        * it into the agent's `instructions` config instead.
        */
       stateInputs.messages.push(
-        new HumanMessage({
-          content: preStreamContexts.join('\n\n'),
-          additional_kwargs: { role: 'system', source: 'hook' },
-        })
+        stampSyntheticProviderMessage(
+          new HumanMessage({
+            content: preStreamContexts.join('\n\n'),
+            additional_kwargs: { role: 'system', source: 'hook' },
+          })
+        )
       );
     }
 

package/src/stream.ts

@@ -820,6 +820,12 @@ function startEagerToolExecutions(args: {
       toolCalls: entries.map((entry) => entry.request),
       userId: graph.config?.configurable?.user_id as string | undefined,
       agentId: agentContext?.agentId,
+      callerCapabilityProjection:
+        (
+          agentContext as
+            | Partial<Pick<AgentContext, 'getCallerCapabilityProjectionSnapshot'>>
+            | undefined
+        )?.getCallerCapabilityProjectionSnapshot?.(),
       configurable: graph.config?.configurable as
         | Record<string, unknown>
         | undefined,

package/src/tools/BashProgrammaticToolCalling.ts

@@ -13,16 +13,22 @@ import {
   getCodeBaseURL,
   selectRuntimeSessionHint,
 } from './CodeExecutor';
-import {
-  clampCodeApiRunTimeoutMs,
-  createCodeApiRunTimeoutSchema,
-  resolveCodeApiRunTimeoutMs,
-} from './ptcTimeout';
 import {
   makeRequest,
   executeTools,
   formatCompletedResponse,
 } from './ProgrammaticToolCalling';
+import {
+  projectProgrammaticToolMap,
+  resolveProgrammaticToolDefinitions,
+  selectProgrammaticTools,
+  type ProgrammaticInvocationParams,
+} from './ProgrammaticCallerPolicy';
+import {
+  clampCodeApiRunTimeoutMs,
+  createCodeApiRunTimeoutSchema,
+  resolveCodeApiRunTimeoutMs,
+} from './ptcTimeout';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
@@ -108,6 +114,10 @@ ${EXAMPLES}
 
 ${CORE_RULES}`;
 
+const TOOL_MANIFEST_DESCRIPTION =
+  'Exact registered tool names used by the code. Required when direct-only tools are configured; ' +
+  'validated before execution starts.';
+
 // ============================================================================
 // Schema
 // ============================================================================
@@ -124,6 +134,12 @@ export function createBashProgrammaticToolCallingSchema(
         minLength: 1,
         description: CODE_PARAM_DESCRIPTION,
       },
+      tool_manifest: {
+        type: 'array',
+        items: { type: 'string' },
+        uniqueItems: true,
+        description: TOOL_MANIFEST_DESCRIPTION,
+      },
       timeout: createCodeApiRunTimeoutSchema(maxRunTimeoutMs),
     },
     required: ['code'],
@@ -302,7 +318,7 @@ export function createBashProgrammaticToolCallingTool(
 
   return tool(
     async (rawParams, config) => {
-      const params = rawParams as { code: string; timeout?: number };
+      const params = rawParams as ProgrammaticInvocationParams;
       const { code } = params;
       const timeout = clampCodeApiRunTimeoutMs(params.timeout, maxRunTimeoutMs);
 
@@ -314,11 +330,26 @@ export function createBashProgrammaticToolCallingTool(
         };
       const {
         toolMap,
-        toolDefs,
+        disallowedToolDefs,
         session_id,
         _injected_files,
         _runtime_session_hint,
       } = toolCall;
+      const toolDefs = resolveProgrammaticToolDefinitions(
+        toolCall as typeof toolCall & { tools?: t.LCTool[] }
+      );
+
+      const programmaticToolName =
+        toolCall.programmaticToolName ??
+        (typeof toolCall.name === 'string' && toolCall.name !== ''
+          ? toolCall.name
+          : Constants.BASH_PROGRAMMATIC_TOOL_CALLING);
+      const effectiveTools = selectProgrammaticTools({
+        requestedToolNames: params.tool_manifest,
+        allowedToolDefs: toolDefs,
+        disallowedToolDefs,
+        programmaticToolName,
+      });
 
       if (toolMap == null || toolMap.size === 0) {
         throw new Error(
@@ -334,20 +365,23 @@ export function createBashProgrammaticToolCallingTool(
         );
       }
 
+      const effectiveToolMap = projectProgrammaticToolMap(
+        toolMap,
+        effectiveTools
+      );
+
       let roundTrip = 0;
 
       try {
         // ====================================================================
-        // Phase 1: Filter tools and make initial request
+        // Phase 1: Send the validated tool manifest with the initial request
         // ====================================================================
 
-        const effectiveTools = filterBashToolsByUsage(toolDefs, code, debug);
-
         if (debug) {
           // eslint-disable-next-line no-console
           console.log(
             `[BashPTC Debug] Sending ${effectiveTools.length} tools to API ` +
-              `(filtered from ${toolDefs.length})`
+              `(selected from ${toolDefs.length})`
           );
         }
 
@@ -422,7 +456,7 @@ export function createBashProgrammaticToolCallingTool(
           const toolResults = normalizeBashToolResultsForReplay(
             await executeTools(
               response.tool_calls ?? [],
-              toolMap,
+              effectiveToolMap,
               Constants.BASH_PROGRAMMATIC_TOOL_CALLING
             )
           );

package/src/tools/CallerCapabilities.ts

@@ -0,0 +1,146 @@
+import type * as t from '@/types';
+import { Constants } from '@/common';
+
+const PROGRAMMATIC_CONTROL_TOOL_NAMES = new Set<string>([
+  Constants.PROGRAMMATIC_TOOL_CALLING,
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+  Constants.TOOL_SEARCH,
+]);
+
+export type CallerCapabilityProjection = {
+  directTools: t.LCTool[];
+  codeExecutionTools: t.LCTool[];
+  directOnlyTools: t.LCTool[];
+  codeExecutionOnlyTools: t.LCTool[];
+};
+
+/**
+ * Combines event schemas with runtime capability metadata. Matching runtime
+ * entries override caller/defer policy without replacing the event schema;
+ * runtime-only definitions are appended intact.
+ */
+export function mergeCallerCapabilityDefinitions(
+  toolDefs: Iterable<t.LCTool> | null | undefined,
+  overrides: Iterable<t.LCTool> | null | undefined
+): t.LCTool[] {
+  const runtimeDefinitions = Array.from(overrides ?? []);
+  const merged = new Map(
+    applyCallerCapabilityDefinitionOverrides(
+      toolDefs ?? [],
+      runtimeDefinitions
+    ).map((toolDef) => [toolDef.name, toolDef])
+  );
+  for (const override of runtimeDefinitions) {
+    if (!merged.has(override.name)) {
+      merged.set(override.name, override);
+    }
+  }
+  return Array.from(merged.values());
+}
+
+/**
+ * Applies runtime caller metadata to schema-only event definitions without
+ * adding registry-only tools or replacing their model-facing schemas.
+ */
+export function applyCallerCapabilityDefinitionOverrides(
+  toolDefs: Iterable<t.LCTool>,
+  overrides: Iterable<t.LCTool> | null | undefined
+): t.LCTool[] {
+  const overridesByName = new Map<string, t.LCTool>();
+  for (const override of overrides ?? []) {
+    overridesByName.set(override.name, override);
+  }
+  return Array.from(toolDefs, (toolDef) => {
+    const override = overridesByName.get(toolDef.name);
+    if (override == null) {
+      return toolDef;
+    }
+    return {
+      ...toolDef,
+      allowed_callers: override.allowed_callers,
+      defer_loading: override.defer_loading,
+    };
+  });
+}
+
+/** Converts the live projection into the versioned event transport shape. */
+export function createCallerCapabilityProjectionSnapshot(
+  projection: CallerCapabilityProjection
+): t.CallerCapabilityProjectionSnapshot {
+  return {
+    version: 1,
+    directToolNames: projection.directTools.map((toolDef) => toolDef.name),
+    codeExecutionToolNames: projection.codeExecutionTools.map(
+      (toolDef) => toolDef.name
+    ),
+    directOnlyToolNames: projection.directOnlyTools.map(
+      (toolDef) => toolDef.name
+    ),
+    codeExecutionOnlyToolNames: projection.codeExecutionOnlyTools.map(
+      (toolDef) => toolDef.name
+    ),
+  };
+}
+
+export function getAllowedCallers(
+  toolDef: t.LCTool
+): readonly t.AllowedCaller[] {
+  return toolDef.allowed_callers ?? ['direct'];
+}
+
+export function allowsToolCaller(
+  toolDef: t.LCTool,
+  caller: t.AllowedCaller
+): boolean {
+  return getAllowedCallers(toolDef).includes(caller);
+}
+
+export function isProgrammaticControlTool(name: string): boolean {
+  return PROGRAMMATIC_CONTROL_TOOL_NAMES.has(name);
+}
+
+export function isToolDefinitionActive(
+  toolDef: t.LCTool,
+  discoveredToolNames: ReadonlySet<string>
+): boolean {
+  return (
+    toolDef.defer_loading !== true || discoveredToolNames.has(toolDef.name)
+  );
+}
+
+export function resolveCallerCapabilityProjection(
+  toolDefs: Iterable<t.LCTool>,
+  isActive: (toolDef: t.LCTool) => boolean = () => true
+): CallerCapabilityProjection {
+  const directTools: t.LCTool[] = [];
+  const codeExecutionTools: t.LCTool[] = [];
+  const directOnlyTools: t.LCTool[] = [];
+  const codeExecutionOnlyTools: t.LCTool[] = [];
+
+  for (const toolDef of toolDefs) {
+    if (!isActive(toolDef)) {
+      continue;
+    }
+    const allowsDirect = allowsToolCaller(toolDef, 'direct');
+    const allowsCodeExecution = allowsToolCaller(toolDef, 'code_execution');
+    if (allowsDirect) {
+      directTools.push(toolDef);
+    }
+    if (allowsCodeExecution) {
+      codeExecutionTools.push(toolDef);
+    }
+    if (allowsDirect && !allowsCodeExecution) {
+      directOnlyTools.push(toolDef);
+    }
+    if (allowsCodeExecution && !allowsDirect) {
+      codeExecutionOnlyTools.push(toolDef);
+    }
+  }
+
+  return {
+    directTools,
+    codeExecutionTools,
+    directOnlyTools,
+    codeExecutionOnlyTools,
+  };
+}

package/src/tools/ProgrammaticCallerPolicy.ts

@@ -0,0 +1,97 @@
+import type * as t from '@/types';
+
+export type ProgrammaticInvocationParams = {
+  code: string;
+  tool_manifest?: string[];
+  timeout?: number;
+  lang?: string;
+  runtime?: string;
+  language?: string;
+};
+
+export function resolveProgrammaticToolDefinitions(
+  context: Partial<t.ProgrammaticCache> & { tools?: t.LCTool[] }
+): t.LCTool[] | undefined {
+  return context.toolDefs ?? context.tools;
+}
+
+export function projectProgrammaticToolMap(
+  toolMap: t.ToolMap,
+  selectedToolDefs: readonly t.LCTool[]
+): t.ToolMap {
+  const selectedNames = new Set(selectedToolDefs.map((toolDef) => toolDef.name));
+  return new Map(
+    [...toolMap].filter(([name]) => selectedNames.has(name))
+  );
+}
+
+export function assertDisallowedToolUsage(
+  disallowedNames: ReadonlySet<string>,
+  programmaticToolName: string
+): void {
+  if (disallowedNames.size === 0) {
+    return;
+  }
+
+  const names = [...disallowedNames];
+  throw new Error(
+    `Tool${names.length === 1 ? '' : 's'} ${names
+      .map((name) => `"${name}"`)
+      .join(', ')} cannot be called from "${programmaticToolName}" because ` +
+      `the${names.length === 1 ? ' tool is' : 'se tools are'} not marked for code_execution. ` +
+      `Call ${names.length === 1 ? 'it' : 'them'} directly instead.`
+  );
+}
+
+export function selectProgrammaticTools(args: {
+  requestedToolNames?: string[];
+  allowedToolDefs?: t.LCTool[];
+  disallowedToolDefs?: t.LCTool[];
+  programmaticToolName: string;
+}): t.LCTool[] {
+  const allowedToolDefs = args.allowedToolDefs ?? [];
+  const disallowedToolDefs = args.disallowedToolDefs ?? [];
+  const requestedToolNames = args.requestedToolNames;
+
+  if (requestedToolNames == null) {
+    if (disallowedToolDefs.length > 0) {
+      throw new Error(
+        `"${args.programmaticToolName}" requires a tool_manifest when direct-only tools are configured. ` +
+          'List every registered tool name used by the submitted code in the tool_manifest field.'
+      );
+    }
+    return allowedToolDefs;
+  }
+
+  const disallowedNames = new Set(
+    disallowedToolDefs.map((toolDef) => toolDef.name)
+  );
+  const requestedDisallowedNames = new Set(
+    requestedToolNames.filter((name) => disallowedNames.has(name))
+  );
+  assertDisallowedToolUsage(
+    requestedDisallowedNames,
+    args.programmaticToolName
+  );
+
+  const allowedByName = new Map(
+    allowedToolDefs.map((toolDef) => [toolDef.name, toolDef])
+  );
+  const unknownNames = new Set(
+    requestedToolNames.filter((name) => !allowedByName.has(name))
+  );
+  if (unknownNames.size > 0) {
+    throw new Error(
+      `Tool${unknownNames.size === 1 ? '' : 's'} ${[...unknownNames]
+        .map((name) => `"${name}"`)
+        .join(
+          ', '
+        )} cannot be used by "${args.programmaticToolName}" because ` +
+        `${unknownNames.size === 1 ? 'it is' : 'they are'} not available for code_execution.`
+    );
+  }
+
+  return [...new Set(requestedToolNames)].map(
+    (name) => allowedByName.get(name) as t.LCTool
+  );
+}

package/src/tools/ProgrammaticToolCalling.ts

@@ -26,6 +26,12 @@ import {
   createCodeApiRunTimeoutSchema,
   resolveCodeApiRunTimeoutMs,
 } from './ptcTimeout';
+import {
+  projectProgrammaticToolMap,
+  resolveProgrammaticToolDefinitions,
+  selectProgrammaticTools,
+  type ProgrammaticInvocationParams,
+} from './ProgrammaticCallerPolicy';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
@@ -87,6 +93,10 @@ ${EXAMPLES}
 
 ${CORE_RULES}`;
 
+const TOOL_MANIFEST_DESCRIPTION =
+  'Exact registered tool names used by the code. Required when direct-only tools are configured; ' +
+  'validated before execution starts.';
+
 export function createProgrammaticToolCallingSchema(
   maxRunTimeoutMs = DEFAULT_RUN_TIMEOUT_MS
 ): ProgrammaticToolCallingJsonSchema {
@@ -99,6 +109,12 @@ export function createProgrammaticToolCallingSchema(
         minLength: 1,
         description: CODE_PARAM_DESCRIPTION,
       },
+      tool_manifest: {
+        type: 'array',
+        items: { type: 'string' },
+        uniqueItems: true,
+        description: TOOL_MANIFEST_DESCRIPTION,
+      },
       timeout: createCodeApiRunTimeoutSchema(maxRunTimeoutMs),
     },
     required: ['code'],
@@ -893,7 +909,7 @@ export function createProgrammaticToolCallingTool(
 
   return tool(
     async (rawParams, config) => {
-      const params = rawParams as { code: string; timeout?: number };
+      const params = rawParams as ProgrammaticInvocationParams;
       const { code } = params;
       const timeout = clampCodeApiRunTimeoutMs(params.timeout, maxRunTimeoutMs);
 
@@ -906,11 +922,26 @@ export function createProgrammaticToolCallingTool(
         };
       const {
         toolMap,
-        toolDefs,
+        disallowedToolDefs,
         session_id,
         _injected_files,
         _runtime_session_hint,
       } = toolCall;
+      const toolDefs = resolveProgrammaticToolDefinitions(
+        toolCall as typeof toolCall & { tools?: t.LCTool[] }
+      );
+
+      const programmaticToolName =
+        toolCall.programmaticToolName ??
+        (typeof toolCall.name === 'string' && toolCall.name !== ''
+          ? toolCall.name
+          : Constants.PROGRAMMATIC_TOOL_CALLING);
+      const effectiveTools = selectProgrammaticTools({
+        requestedToolNames: params.tool_manifest,
+        allowedToolDefs: toolDefs,
+        disallowedToolDefs,
+        programmaticToolName,
+      });
 
       if (toolMap == null || toolMap.size === 0) {
         throw new Error(
@@ -926,20 +957,23 @@ export function createProgrammaticToolCallingTool(
         );
       }
 
+      const effectiveToolMap = projectProgrammaticToolMap(
+        toolMap,
+        effectiveTools
+      );
+
       let roundTrip = 0;
 
       try {
         // ====================================================================
-        // Phase 1: Filter tools and make initial request
+        // Phase 1: Send the validated tool manifest with the initial request
         // ====================================================================
 
-        const effectiveTools = filterToolsByUsage(toolDefs, code, debug);
-
         if (debug) {
           // eslint-disable-next-line no-console
           console.log(
             `[PTC Debug] Sending ${effectiveTools.length} tools to API ` +
-              `(filtered from ${toolDefs.length})`
+              `(selected from ${toolDefs.length})`
           );
         }
 
@@ -1015,7 +1049,7 @@ export function createProgrammaticToolCallingTool(
 
           const toolResults = await executeTools(
             response.tool_calls ?? [],
-            toolMap
+            effectiveToolMap
           );
 
           response = await makeRequest(