@librechat/agents 3.1.83 → 3.1.84

package/dist/types/agents/AgentContext.d.ts

@@ -186,13 +186,15 @@ export declare 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
      * - Code_execution-only tools that ARE deferred but have been discovered via tool search
      */
     private buildProgrammaticOnlyToolsInstructions;
+    private getProgrammaticToolInstructionTarget;
+    private hasAvailableTool;
     /**
      * Gets the system runnable, creating it lazily if needed.
      * Includes stable instructions, dynamic additional instructions, and

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

@@ -25,6 +25,11 @@ export declare const CodeExecutionToolSchema: {
     };
     readonly required: readonly ["lang", "code"];
 };
+export declare function resolveCodeApiAuthHeaders(authHeaders?: t.CodeApiAuthHeaders): Promise<t.CodeApiAuthHeaderMap>;
+export declare function buildCodeApiHttpErrorMessage(method: string, endpoint: string, response: {
+    status: number;
+    text: () => Promise<string>;
+}): Promise<string>;
 export declare const CodeExecutionToolDescription: string;
 export declare const CodeExecutionToolName = Constants.EXECUTE_CODE;
 export declare const CodeExecutionToolDefinition: {

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

@@ -43,6 +43,15 @@ export declare const ProgrammaticToolCallingDefinition: {
         readonly required: readonly ["code"];
     };
 };
+export type FetchSessionFilesScope = {
+    kind: 'skill';
+    id: string;
+    version: number;
+} | {
+    kind: 'agent' | 'user';
+    id: string;
+    version?: never;
+};
 /**
  * Normalizes a tool name to Python identifier format.
  * Must match the Code API's `normalizePythonFunctionName` exactly:
@@ -76,10 +85,12 @@ export declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string, d
  * Files are returned as CodeEnvFile references to be included in the request.
  * @param baseUrl - The base URL for the Code API
  * @param sessionId - The session ID to fetch files from
+ * @param scope - Resource scope used by CodeAPI to authorize the session
  * @param proxy - Optional HTTP proxy URL
  * @returns Array of CodeEnvFile references, or empty array if fetch fails
  */
-export declare function fetchSessionFiles(baseUrl: string, sessionId: string, proxy?: string): Promise<t.CodeEnvFile[]>;
+export declare function fetchSessionFiles(baseUrl: string, sessionId: string, proxy?: string, authHeaders?: t.CodeApiAuthHeaders): Promise<t.CodeEnvFile[]>;
+export declare function fetchSessionFiles(baseUrl: string, sessionId: string, scope: FetchSessionFilesScope, proxyOrAuthHeaders?: string | t.CodeApiAuthHeaders, authHeaders?: t.CodeApiAuthHeaders): Promise<t.CodeEnvFile[]>;
 /**
  * Makes an HTTP request to the Code API.
  * @param endpoint - The API endpoint URL
@@ -87,7 +98,7 @@ export declare function fetchSessionFiles(baseUrl: string, sessionId: string, pr
  * @param proxy - Optional HTTP proxy URL
  * @returns The parsed API response
  */
-export declare function makeRequest(endpoint: string, body: Record<string, unknown>, proxy?: string): Promise<t.ProgrammaticExecutionResponse>;
+export declare function makeRequest(endpoint: string, body: Record<string, unknown>, proxy?: string, authHeaders?: t.CodeApiAuthHeaders): Promise<t.ProgrammaticExecutionResponse>;
 /**
  * Unwraps tool responses that may be formatted as tuples or content blocks.
  * MCP tools return [content, artifacts], we need to extract the raw data.
@@ -104,7 +115,7 @@ export declare function unwrapToolResponse(result: unknown, isMCPTool: boolean):
  * @param toolMap - Map of tool names to executable tools
  * @returns Array of tool results
  */
-export declare function executeTools(toolCalls: t.PTCToolCall[], toolMap: t.ToolMap): Promise<t.PTCToolResult[]>;
+export declare function executeTools(toolCalls: t.PTCToolCall[], toolMap: t.ToolMap, programmaticToolName?: Constants): Promise<t.PTCToolResult[]>;
 /**
  * Formats the completed response for the agent.
  *

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

@@ -205,7 +205,11 @@ export type CodeExecutionToolParams = undefined | {
     session_id?: string;
     user_id?: string;
     files?: CodeEnvFile[];
+    /** Optional host-supplied Code API auth headers. */
+    authHeaders?: CodeApiAuthHeaders;
 };
+export type CodeApiAuthHeaderMap = Record<string, string>;
+export type CodeApiAuthHeaders = CodeApiAuthHeaderMap | (() => CodeApiAuthHeaderMap | Promise<CodeApiAuthHeaderMap>);
 export type FileRef = {
     /**
      * Storage file id (the per-file uuid). See `CodeEnvFile.id` for
@@ -825,6 +829,8 @@ export type ProgrammaticToolCallingParams = {
     proxy?: string;
     /** Enable debug logging (or set PTC_DEBUG=true env var) */
     debug?: boolean;
+    /** Optional host-supplied Code API auth headers. */
+    authHeaders?: CodeApiAuthHeaders;
 };
 /**
  * Tracks code execution session state for automatic file persistence.

package/package.json

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

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/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/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

@@ -312,7 +312,8 @@ export function createBashProgrammaticToolCallingTool(
             timeout,
             ...(files && files.length > 0 ? { files } : {}),
           },
-          proxy
+          proxy,
+          initParams.authHeaders
         );
 
         // ====================================================================
@@ -339,7 +340,8 @@ export function createBashProgrammaticToolCallingTool(
 
           const toolResults = await executeTools(
             response.tool_calls ?? [],
-            toolMap
+            toolMap,
+            Constants.BASH_PROGRAMMATIC_TOOL_CALLING
           );
 
           response = await makeRequest(
@@ -348,7 +350,8 @@ export function createBashProgrammaticToolCallingTool(
               continuation_token: response.continuation_token,
               tool_results: toolResults,
             },
-            proxy
+            proxy,
+            initParams.authHeaders
           );
         }
 

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();