@librechat/agents 3.1.83 → 3.1.85

package/src/agents/AgentContext.ts

@@ -13,6 +13,7 @@ import {
   ANTHROPIC_TOOL_TOKEN_MULTIPLIER,
   DEFAULT_TOOL_TOKEN_MULTIPLIER,
   ContentTypes,
+  Constants,
   Providers,
 } from '@/common';
 import { createSchemaOnlyTools } from '@/tools/schema';
@@ -389,7 +390,7 @@ 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
-   * run_tools_with_code tool.
+   * configured programmatic tool.
    *
    * Includes:
    * - Code_execution-only tools that are NOT deferred
@@ -416,6 +417,7 @@ export class AgentContext {
 
     if (programmaticOnlyTools.length === 0) return '';
 
+    const programmaticTool = this.getProgrammaticToolInstructionTarget();
     const toolDescriptions = programmaticOnlyTools
       .map((tool) => {
         let desc = `- **${tool.name}**`;
@@ -431,12 +433,39 @@ export class AgentContext {
 
     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' +
+      `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` +
       toolDescriptions
     );
   }
 
+  private getProgrammaticToolInstructionTarget(): {
+    name: string;
+    language: 'bash' | 'Python';
+    } {
+    if (this.hasAvailableTool(Constants.BASH_PROGRAMMATIC_TOOL_CALLING)) {
+      return {
+        name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+        language: 'bash',
+      };
+    }
+
+    if (this.hasAvailableTool(Constants.PROGRAMMATIC_TOOL_CALLING)) {
+      return { name: Constants.PROGRAMMATIC_TOOL_CALLING, language: 'Python' };
+    }
+
+    return { name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING, language: 'bash' };
+  }
+
+  private hasAvailableTool(name: string): boolean {
+    if (this.toolDefinitions?.some((tool) => tool.name === name)) return true;
+    if (this.tools?.some((tool) => 'name' in tool && tool.name === name)) {
+      return true;
+    }
+    if (this.toolMap?.has(name)) return true;
+    return this.toolRegistry?.has(name) === true;
+  }
+
   /**
    * Gets the system runnable, creating it lazily if needed.
    * Includes stable instructions, dynamic additional instructions, and

package/src/agents/__tests__/AgentContext.test.ts

@@ -1,7 +1,7 @@
 // src/agents/__tests__/AgentContext.test.ts
 import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import { AgentContext } from '../AgentContext';
-import { Providers } from '@/common';
+import { Constants, Providers } from '@/common';
 import { addBedrockCacheControl } from '@/messages/cache';
 import type * as t from '@/types';
 
@@ -593,7 +593,7 @@ describe('AgentContext', () => {
   });
 
   describe('buildProgrammaticOnlyToolsInstructions', () => {
-    it('includes code_execution-only tools in system message', () => {
+    it('includes code_execution-only tools in system message', async () => {
       const toolRegistry: t.LCToolRegistry = new Map([
         [
           'programmatic_tool',
@@ -606,11 +606,44 @@ describe('AgentContext', () => {
       ]);
 
       const ctx = createBasicContext({
-        agentConfig: { instructions: 'Base', toolRegistry },
+        agentConfig: {
+          instructions: 'Base',
+          toolDefinitions: [{ name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING }],
+          toolRegistry,
+        },
       });
 
       const runnable = ctx.systemRunnable;
       expect(runnable).toBeDefined();
+      const result = await runnable!.invoke([]);
+      expect(result[0].content).toContain('run_tools_with_bash');
+      expect(result[0].content).not.toContain('run_tools_with_code');
+    });
+
+    it('uses Python PTC guidance when only run_tools_with_code is available', async () => {
+      const toolRegistry: t.LCToolRegistry = new Map([
+        [
+          'programmatic_tool',
+          {
+            name: 'programmatic_tool',
+            description: 'Only callable via code execution',
+            allowed_callers: ['code_execution'],
+          },
+        ],
+      ]);
+
+      const ctx = createBasicContext({
+        agentConfig: {
+          instructions: 'Base',
+          toolDefinitions: [{ name: Constants.PROGRAMMATIC_TOOL_CALLING }],
+          toolRegistry,
+        },
+      });
+
+      const result = await ctx.systemRunnable!.invoke([]);
+      expect(result[0].content).toContain('run_tools_with_code');
+      expect(result[0].content).toContain('Python code');
+      expect(result[0].content).not.toContain('run_tools_with_bash');
     });
 
     it('excludes direct-callable tools from programmatic section', () => {

package/src/common/enum.ts

@@ -261,4 +261,5 @@ export enum TitleMethod {
 
 export enum EnvVar {
   CODE_BASEURL = 'LIBRECHAT_CODE_BASEURL',
+  CODE_API_RUN_TIMEOUT_MS = 'CODE_API_RUN_TIMEOUT_MS',
 }

package/src/events.ts

@@ -90,7 +90,10 @@ export class ToolEndHandler implements t.EventHandler {
         return;
       }
 
-      if (metadata[Constants.PROGRAMMATIC_TOOL_CALLING] === true) {
+      if (
+        metadata[Constants.PROGRAMMATIC_TOOL_CALLING] === true ||
+        metadata[Constants.BASH_PROGRAMMATIC_TOOL_CALLING] === true
+      ) {
         return;
       }
 

package/src/graphs/MultiAgentGraph.ts

@@ -1074,10 +1074,11 @@ export class MultiAgentGraph extends StandardGraph {
              * to pass filtered messages + prompt to the destination agent
              */
             const filteredMessages = state.messages.slice(0, this.startIndex);
+            const promptMessage = new HumanMessage(promptText);
             return {
-              messages: [new HumanMessage(promptText)],
+              messages: [promptMessage],
               agentMessages: messagesStateReducer(filteredMessages, [
-                new HumanMessage(promptText),
+                promptMessage,
               ]),
             };
           }

package/src/graphs/__tests__/composition.smoke.test.ts

@@ -1,11 +1,17 @@
-import { HumanMessage } from '@langchain/core/messages';
-import type { ToolCall } from '@langchain/core/messages/tool';
+import { HumanMessage, getBufferString } from '@langchain/core/messages';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { MultiAgentGraph } from '../MultiAgentGraph';
 import { Constants, Providers } from '@/common';
+import { FakeChatModel } from '@/llm/fake';
 import { StandardGraph } from '../Graph';
 
+const CHAIN_PROMPT_PREFIX = 'Previous context:\n';
+
 const makeAgent = (agentId: string): t.AgentInputs => ({
   agentId,
   provider: Providers.OPENAI,
@@ -29,6 +35,36 @@ const getAiContents = (messages: t.BaseGraphState['messages']): string[] =>
     .map((message) => message.content)
     .filter((content): content is string => typeof content === 'string');
 
+const getChainPromptContent = (messages: BaseMessage[]): string => {
+  const promptMessage = messages.find(
+    (message) =>
+      message.getType() === 'human' &&
+      typeof message.content === 'string' &&
+      message.content.startsWith(CHAIN_PROMPT_PREFIX)
+  );
+  if (promptMessage == null || typeof promptMessage.content !== 'string') {
+    throw new Error('Expected chain prompt message');
+  }
+  return promptMessage.content;
+};
+
+class CapturingChatModel extends FakeChatModel {
+  readonly invocations: BaseMessage[][] = [];
+
+  constructor(responses: string[]) {
+    super({ responses });
+  }
+
+  override async *_streamResponseChunks(
+    messages: BaseMessage[],
+    options: this['ParsedCallOptions'],
+    runManager?: CallbackManagerForLLMRun
+  ): AsyncGenerator<ChatGenerationChunk> {
+    this.invocations.push(messages);
+    yield* super._streamResponseChunks(messages, options, runManager);
+  }
+}
+
 const expectCompiledWorkflow = (
   workflow: t.CompiledWorkflow | t.CompiledMultiAgentWorkflow
 ): void => {
@@ -119,6 +155,52 @@ describe('LangGraph composition smoke tests', () => {
     expect(getAiContents(result.messages)).toEqual(['from A', 'from B']);
   });
 
+  it('does not duplicate excludeResults chain prompt history for downstream agents', async () => {
+    const model = new CapturingChatModel(['from A', 'from B', 'from C']);
+    const prompt = (messages: BaseMessage[], startIndex: number): string =>
+      `${CHAIN_PROMPT_PREFIX}${getBufferString(messages.slice(startIndex))}`;
+    const graph = new MultiAgentGraph({
+      runId: 'exclude-results-chain-smoke',
+      agents: [makeAgent('A'), makeAgent('B'), makeAgent('C')],
+      edges: [
+        {
+          from: 'A',
+          to: 'B',
+          edgeType: 'direct',
+          prompt,
+          excludeResults: true,
+        },
+        {
+          from: 'B',
+          to: 'C',
+          edgeType: 'direct',
+          prompt,
+          excludeResults: true,
+        },
+      ],
+    });
+    graph.overrideModel = model;
+
+    const result = await graph
+      .createWorkflow()
+      .invoke(
+        { messages: [new HumanMessage('start')] },
+        makeConfig('exclude-results-chain-smoke')
+      );
+
+    expect(getAiContents(result.messages)).toEqual([
+      'from A',
+      'from B',
+      'from C',
+    ]);
+    expect(model.invocations).toHaveLength(3);
+
+    const downstreamPrompt = getChainPromptContent(model.invocations[2]);
+    const previousPromptCount =
+      downstreamPrompt.match(/Human: Previous context:/g)?.length ?? 0;
+    expect(previousPromptCount).toBe(1);
+  });
+
   it('compiles and invokes a handoff edge using graph-managed transfer tools', async () => {
     const transferToolCall: ToolCall = {
       id: 'call_transfer_to_B',

package/src/tools/BashExecutor.ts

@@ -3,7 +3,12 @@ import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
-import { emptyOutputMessage, getCodeBaseURL } from './CodeExecutor';
+import {
+  emptyOutputMessage,
+  buildCodeApiHttpErrorMessage,
+  getCodeBaseURL,
+  resolveCodeApiAuthHeaders,
+} from './CodeExecutor';
 import { Constants } from '@/common';
 
 config();
@@ -104,6 +109,7 @@ function createBashExecutionTool(
 ): DynamicStructuredTool {
   return tool(
     async (rawInput, config) => {
+      const { authHeaders, ...executionParams } = params ?? {};
       const { command, ...rest } = rawInput as {
         command: string;
         args?: string[];
@@ -117,7 +123,7 @@ function createBashExecutionTool(
         lang: 'bash',
         code: command,
         ...rest,
-        ...params,
+        ...executionParams,
       };
 
       /* See `CodeExecutor.ts` for the rationale — `/files/<session_id>`
@@ -137,11 +143,14 @@ function createBashExecutionTool(
       }
 
       try {
+        const resolvedAuthHeaders =
+          await resolveCodeApiAuthHeaders(authHeaders);
         const fetchOptions: RequestInit = {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
             'User-Agent': 'LibreChat/1.0',
+            ...resolvedAuthHeaders,
           },
           body: JSON.stringify(postData),
         };
@@ -151,7 +160,9 @@ function createBashExecutionTool(
         }
         const response = await fetch(EXEC_ENDPOINT, fetchOptions);
         if (!response.ok) {
-          throw new Error(`HTTP error! status: ${response.status}`);
+          throw new Error(
+            await buildCodeApiHttpErrorMessage('POST', EXEC_ENDPOINT, response)
+          );
         }
 
         const result: t.ExecuteResult = await response.json();

package/src/tools/BashProgrammaticToolCalling.ts

@@ -1,6 +1,7 @@
 import { config } from 'dotenv';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type { ProgrammaticToolCallingJsonSchema } from './ptcTimeout';
 import type * as t from '@/types';
 import {
   makeRequest,
@@ -8,6 +9,11 @@ import {
   formatCompletedResponse,
 } from './ProgrammaticToolCalling';
 import { getCodeBaseURL } from './CodeExecutor';
+import {
+  clampCodeApiRunTimeoutMs,
+  createCodeApiRunTimeoutSchema,
+  resolveCodeApiRunTimeoutMs,
+} from './ptcTimeout';
 import { Constants } from '@/common';
 
 config();
@@ -17,7 +23,7 @@ config();
 // ============================================================================
 
 const DEFAULT_MAX_ROUND_TRIPS = 20;
-const DEFAULT_TIMEOUT = 60000;
+const DEFAULT_RUN_TIMEOUT_MS = resolveCodeApiRunTimeoutMs();
 
 /** Bash reserved words that get `_tool` suffix when used as function names */
 const BASH_RESERVED = new Set([
@@ -60,7 +66,8 @@ const CORE_RULES = `Rules:
 - Tools are pre-defined as bash functions—DO NOT redefine them
 - Each tool function accepts a JSON string argument
 - Only echo/printf output returns to the model
-- Generated files are automatically available in /mnt/data/ for subsequent executions`;
+- Generated files are automatically available in /mnt/data/ for subsequent executions
+- timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;
 
 const ADDITIONAL_RULES =
   '- Tool names normalized: hyphens→underscores, reserved words get `_tool` suffix';
@@ -92,25 +99,25 @@ ${CORE_RULES}`;
 // Schema
 // ============================================================================
 
-export const BashProgrammaticToolCallingSchema = {
-  type: 'object',
-  properties: {
-    code: {
-      type: 'string',
-      minLength: 1,
-      description: CODE_PARAM_DESCRIPTION,
-    },
-    timeout: {
-      type: 'integer',
-      minimum: 1000,
-      maximum: 300000,
-      default: DEFAULT_TIMEOUT,
-      description:
-        'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.',
+export function createBashProgrammaticToolCallingSchema(
+  maxRunTimeoutMs = DEFAULT_RUN_TIMEOUT_MS
+): ProgrammaticToolCallingJsonSchema {
+  return {
+    type: 'object',
+    properties: {
+      code: {
+        type: 'string',
+        minLength: 1,
+        description: CODE_PARAM_DESCRIPTION,
+      },
+      timeout: createCodeApiRunTimeoutSchema(maxRunTimeoutMs),
     },
-  },
-  required: ['code'],
-} as const;
+    required: ['code'],
+  } as const;
+}
+
+export const BashProgrammaticToolCallingSchema =
+  createBashProgrammaticToolCallingSchema();
 
 export const BashProgrammaticToolCallingName =
   Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
@@ -242,6 +249,7 @@ export function createBashProgrammaticToolCallingTool(
 ): DynamicStructuredTool {
   const baseUrl = initParams.baseUrl ?? getCodeBaseURL();
   const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;
+  const maxRunTimeoutMs = resolveCodeApiRunTimeoutMs(initParams.runTimeoutMs);
   const proxy = initParams.proxy ?? process.env.PROXY;
   const debug = initParams.debug ?? process.env.BASH_PTC_DEBUG === 'true';
   const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
@@ -249,7 +257,8 @@ export function createBashProgrammaticToolCallingTool(
   return tool(
     async (rawParams, config) => {
       const params = rawParams as { code: string; timeout?: number };
-      const { code, timeout = DEFAULT_TIMEOUT } = params;
+      const { code } = params;
+      const timeout = clampCodeApiRunTimeoutMs(params.timeout, maxRunTimeoutMs);
 
       const toolCall = (config.toolCall ?? {}) as ToolCall &
         Partial<t.ProgrammaticCache> & {
@@ -312,7 +321,8 @@ export function createBashProgrammaticToolCallingTool(
             timeout,
             ...(files && files.length > 0 ? { files } : {}),
           },
-          proxy
+          proxy,
+          initParams.authHeaders
         );
 
         // ====================================================================
@@ -339,7 +349,8 @@ export function createBashProgrammaticToolCallingTool(
 
           const toolResults = await executeTools(
             response.tool_calls ?? [],
-            toolMap
+            toolMap,
+            Constants.BASH_PROGRAMMATIC_TOOL_CALLING
           );
 
           response = await makeRequest(
@@ -348,7 +359,8 @@ export function createBashProgrammaticToolCallingTool(
               continuation_token: response.continuation_token,
               tool_results: toolResults,
             },
-            proxy
+            proxy,
+            initParams.authHeaders
           );
         }
 
@@ -379,7 +391,7 @@ export function createBashProgrammaticToolCallingTool(
     {
       name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
       description: BashProgrammaticToolCallingDescription,
-      schema: BashProgrammaticToolCallingSchema,
+      schema: createBashProgrammaticToolCallingSchema(maxRunTimeoutMs),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

package/src/tools/CodeExecutor.ts

@@ -70,6 +70,34 @@ const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
 
 type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
 
+export async function resolveCodeApiAuthHeaders(
+  authHeaders?: t.CodeApiAuthHeaders
+): Promise<t.CodeApiAuthHeaderMap> {
+  if (authHeaders == null) {
+    return {};
+  }
+  if (typeof authHeaders === 'function') {
+    return authHeaders();
+  }
+  return authHeaders;
+}
+
+export async function buildCodeApiHttpErrorMessage(
+  method: string,
+  endpoint: string,
+  response: { status: number; text: () => Promise<string> }
+): Promise<string> {
+  let responseBody = '';
+  try {
+    responseBody = await response.text();
+  } catch {
+    responseBody = '';
+  }
+  const body = responseBody.trim();
+  const bodySuffix = body === '' ? '' : `, body: ${body.slice(0, 1000)}`;
+  return `CodeAPI request failed: ${method} ${endpoint} returned ${response.status}${bodySuffix}`;
+}
+
 export const CodeExecutionToolDescription = `
 Runs code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
 
@@ -92,6 +120,7 @@ function createCodeExecutionTool(
 ): DynamicStructuredTool {
   return tool(
     async (rawInput, config) => {
+      const { authHeaders, ...executionParams } = params ?? {};
       const { lang, code, ...rest } = rawInput as {
         lang: SupportedLanguage;
         code: string;
@@ -111,7 +140,7 @@ function createCodeExecutionTool(
         lang,
         code,
         ...rest,
-        ...params,
+        ...executionParams,
       };
 
       /* File injection: `_injected_files` from ToolNode (set when host
@@ -135,11 +164,14 @@ function createCodeExecutionTool(
       }
 
       try {
+        const resolvedAuthHeaders =
+          await resolveCodeApiAuthHeaders(authHeaders);
         const fetchOptions: RequestInit = {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
             'User-Agent': 'LibreChat/1.0',
+            ...resolvedAuthHeaders,
           },
           body: JSON.stringify(postData),
         };
@@ -149,7 +181,9 @@ function createCodeExecutionTool(
         }
         const response = await fetch(EXEC_ENDPOINT, fetchOptions);
         if (!response.ok) {
-          throw new Error(`HTTP error! status: ${response.status}`);
+          throw new Error(
+            await buildCodeApiHttpErrorMessage('POST', EXEC_ENDPOINT, response)
+          );
         }
 
         const result: t.ExecuteResult = await response.json();