@librechat/agents 3.1.88 → 3.1.90

package/src/stream.ts

@@ -27,11 +27,16 @@ import {
   coerceRecordArgs,
   normalizeError,
 } from '@/tools/eagerEventExecution';
+import {
+  calculateMaxToolResultChars,
+  truncateToolResultContent,
+} from '@/utils/truncation';
 import {
   getStreamedToolCallSeal,
   getStreamedToolCallAdapter,
   type StreamedToolCallSeal,
 } from '@/tools/streamedToolCallSeals';
+import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
 
 const LOCAL_CODING_BUNDLE_NAME_SET: ReadonlySet<string> = new Set(
   LOCAL_CODING_BUNDLE_NAMES
@@ -98,11 +103,22 @@ function getNonEmptyValue(possibleValues: string[]): string | undefined {
 }
 
 function isBatchSensitiveToolExecution(graph: StandardGraph): boolean {
-  return (
-    graph.hookRegistry != null ||
-    graph.humanInTheLoop?.enabled === true ||
-    graph.toolOutputReferences?.enabled === true
-  );
+  return graph.hookRegistry != null || graph.humanInTheLoop?.enabled === true;
+}
+
+function hasToolOutputReference(value: unknown): boolean {
+  if (typeof value === 'string') {
+    return TOOL_OUTPUT_REF_PATTERN.test(value);
+  }
+  if (Array.isArray(value)) {
+    return value.some((item) => hasToolOutputReference(item));
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.values(value as Record<string, unknown>).some((item) =>
+      hasToolOutputReference(item)
+    );
+  }
+  return false;
 }
 
 function isDirectGraphTool(
@@ -194,7 +210,10 @@ function isEagerToolExecutionEnabledForBatch(args: {
   ) {
     return false;
   }
-  if (graph.handlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) == null) {
+  if (
+    graph.handlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) == null &&
+    graph.eventToolExecutionAvailable !== true
+  ) {
     return false;
   }
   return true;
@@ -257,13 +276,49 @@ function hasPotentialDirectToolInStreamContext(args: {
   if ((agentContext?.graphTools?.length ?? 0) > 0) {
     return true;
   }
+  return false;
+}
+
+function hasDirectToolCallChunkInBatch(args: {
+  graph: StandardGraph;
+  agentContext?: AgentContext;
+  toolCallChunks?: ToolCallChunk[];
+}): boolean {
+  const { graph, agentContext, toolCallChunks } = args;
   return (
-    agentContext?.toolDefinitions?.some((toolDefinition) =>
-      toolDefinition.name.startsWith(Constants.LC_TRANSFER_TO_)
+    toolCallChunks?.some(
+      (toolCallChunk) =>
+        toolCallChunk.name != null &&
+        toolCallChunk.name !== '' &&
+        (isDirectGraphTool(toolCallChunk.name, agentContext) ||
+          isDirectLocalTool(toolCallChunk.name, graph))
     ) === true
   );
 }
 
+function hasDirectToolCallChunkStateInStep(args: {
+  graph: StandardGraph;
+  agentContext?: AgentContext;
+  stepKey: string;
+}): boolean {
+  const { graph, agentContext, stepKey } = args;
+  const prefix = `${stepKey}\u0000`;
+  for (const [key, state] of graph.eagerEventToolCallChunks) {
+    if (!key.startsWith(prefix)) {
+      continue;
+    }
+    const name = state.name;
+    if (
+      name != null &&
+      name !== '' &&
+      (isDirectGraphTool(name, agentContext) || isDirectLocalTool(name, graph))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 type EagerToolExecutionEntry = {
   id: string;
   toolName: string;
@@ -298,6 +353,12 @@ function createEagerToolExecutionPlan(args: {
   if (hasDirectToolCallInBatch({ graph, agentContext, toolCalls })) {
     return undefined;
   }
+  if (
+    graph.toolOutputReferences?.enabled === true &&
+    toolCalls.some((toolCall) => hasToolOutputReference(toolCall.args))
+  ) {
+    return undefined;
+  }
 
   const candidateToolCalls = skipExisting
     ? toolCalls.filter((toolCall) => {
@@ -369,6 +430,7 @@ function startEagerToolExecutions(args: {
     return;
   }
 
+  const records: t.EagerEventToolExecution[] = [];
   const promise: Promise<t.EagerEventToolExecutionOutcome> = new Promise<
     t.ToolExecuteResult[]
   >((resolve, reject) => {
@@ -407,20 +469,104 @@ function startEagerToolExecutions(args: {
       })
       .catch(reject);
   }).then(
-    (results): t.EagerEventToolExecutionOutcome => ({ results }),
+    async (results): Promise<t.EagerEventToolExecutionOutcome> => {
+      await dispatchEagerToolCompletions({
+        graph,
+        agentContext,
+        records,
+        results,
+      });
+      return { results };
+    },
     (error): t.EagerEventToolExecutionOutcome => ({
       error: normalizeError(error),
     })
   );
 
   for (const entry of entries) {
-    graph.eagerEventToolExecutions.set(entry.id, {
+    const record: t.EagerEventToolExecution = {
       toolCallId: entry.id,
       toolName: entry.toolName,
       args: entry.coercedArgs,
       request: entry.request,
       promise,
-    });
+    };
+    records.push(record);
+    graph.eagerEventToolExecutions.set(entry.id, record);
+  }
+}
+
+async function dispatchEagerToolCompletions(args: {
+  graph: StandardGraph;
+  agentContext?: AgentContext;
+  records: t.EagerEventToolExecution[];
+  results: t.ToolExecuteResult[];
+}): Promise<void> {
+  const { graph, agentContext, records, results } = args;
+  const recordById = new Map(
+    records.map((record) => [record.toolCallId, record])
+  );
+  const maxToolResultChars =
+    agentContext?.maxToolResultChars ??
+    calculateMaxToolResultChars(agentContext?.maxContextTokens);
+
+  for (const result of results) {
+    const record = recordById.get(result.toolCallId);
+    if (record == null) {
+      continue;
+    }
+    if (graph.eagerEventToolExecutions.get(result.toolCallId) !== record) {
+      continue;
+    }
+    const stepId =
+      record.request.stepId ??
+      graph.toolCallStepIds.get(result.toolCallId) ??
+      '';
+    if (stepId === '') {
+      continue;
+    }
+    const output =
+      result.status === 'error'
+        ? `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`
+        : truncateToolResultContent(
+          typeof result.content === 'string'
+            ? result.content
+            : JSON.stringify(result.content),
+          maxToolResultChars
+        );
+
+    try {
+      const dispatched = await safeDispatchCustomEvent(
+        GraphEvents.ON_RUN_STEP_COMPLETED,
+        {
+          result: {
+            id: stepId,
+            index: record.request.turn ?? 0,
+            type: 'tool_call' as const,
+            eager: true,
+            tool_call: {
+              args: JSON.stringify(record.request.args),
+              name: record.toolName,
+              id: result.toolCallId,
+              output,
+              progress: 1,
+            } as t.ProcessedToolCall,
+          },
+        },
+        graph.config
+      );
+      if (dispatched === false) {
+        continue;
+      }
+      record.completionDispatched = true;
+    } catch (error) {
+      // Let ToolNode dispatch the completion through the normal path later.
+
+      console.warn(
+        `[stream] eager completion dispatch failed for toolCallId=${result.toolCallId}:`,
+        error instanceof Error ? error.message : error
+      );
+    }
   }
 }
 
@@ -699,6 +845,8 @@ function startReadyStreamedEagerToolExecutions(args: {
   } = args;
   if (
     hasPotentialDirectToolInStreamContext({ graph, agentContext }) ||
+    hasDirectToolCallChunkInBatch({ graph, agentContext, toolCallChunks }) ||
+    hasDirectToolCallChunkStateInStep({ graph, agentContext, stepKey }) ||
     !isEagerToolExecutionEnabledForBatch({ graph, metadata, agentContext })
   ) {
     return;
@@ -1265,9 +1413,12 @@ export function createContentAggregator(): t.ContentAggregatorResult {
 
       const existingContent = contentParts[index] as
         | (Omit<t.ToolCallContent, 'tool_call'> & {
-            tool_call?: t.ToolCallPart;
+            tool_call?: t.ToolCallPart & t.PartMetadata;
           })
         | undefined;
+      if (!finalUpdate && existingContent?.tool_call?.progress === 1) {
+        return;
+      }
 
       /** When args are a valid object, they are likely already invoked */
       let args =

package/src/tools/BashExecutor.ts

@@ -4,6 +4,11 @@ import { HttpsProxyAgent } from 'https-proxy-agent';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 import {
+  BASH_SHELL_GUIDANCE,
+  CODE_ARTIFACT_PATH_GUIDANCE,
+  appendFailedExecutionFileReminder,
+  appendTmpScratchReminder,
+  appendCodeSessionFileSummary,
   emptyOutputMessage,
   buildCodeApiHttpErrorMessage,
   getCodeBaseURL,
@@ -23,8 +28,9 @@ export const BashExecutionToolSchema = {
       type: 'string',
       description: `The bash command or script to execute.
 - The environment is stateless; variables and state don't persist between executions.
-- Generated files from previous executions are automatically available in "/mnt/data/".
-- Files from previous executions are automatically available and can be modified in place.
+- Prior /mnt/data files are available and can be modified in place.
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
+- ${BASH_SHELL_GUIDANCE}
 - Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.
 - Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.
 - IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.
@@ -46,6 +52,8 @@ Runs bash commands and returns stdout/stderr output from a stateless execution e
 Usage:
 - No network access available.
 - Generated files are automatically delivered; **DO NOT** provide download links.
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
+- ${BASH_SHELL_GUIDANCE}
 - NEVER use this tool to execute malicious commands.
 `.trim();
 
@@ -105,7 +113,7 @@ export const BashExecutionToolDefinition = {
 } as const;
 
 function createBashExecutionTool(
-  params: t.BashExecutionToolParams = {}
+  params: t.BashExecutionToolParams | null = {}
 ): DynamicStructuredTool {
   return tool(
     async (rawInput, config) => {
@@ -166,11 +174,6 @@ function createBashExecutionTool(
         }
 
         const result: t.ExecuteResult = await response.json();
-        /* See `CodeExecutor.ts` — file listings were removed from the
-         * LLM-facing tool result. Bash especially benefits: models
-         * naturally `ls /mnt/data/` to discover what's available
-         * rather than relying on a prescriptive summary that
-         * misleads as often as it helps. */
         let formattedOutput = '';
         if (result.stdout) {
           formattedOutput += `stdout:\n${result.stdout}\n`;
@@ -179,9 +182,13 @@ function createBashExecutionTool(
         }
         if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
 
+        const outputWithReminder = appendTmpScratchReminder(
+          formattedOutput,
+          command
+        );
         const hasFiles = result.files != null && result.files.length > 0;
         return [
-          formattedOutput.trim(),
+          appendCodeSessionFileSummary(outputWithReminder, result.files),
           (hasFiles
             ? { session_id: result.session_id, files: result.files }
             : {
@@ -189,8 +196,12 @@ function createBashExecutionTool(
             }) satisfies t.CodeExecutionArtifact,
         ];
       } catch (error) {
+        const messageWithReminder = appendFailedExecutionFileReminder(
+          (error as Error | undefined)?.message ?? '',
+          command
+        );
         throw new Error(
-          `Execution error:\n\n${(error as Error | undefined)?.message}`
+          `Execution error:\n\n${messageWithReminder}`
         );
       }
     },

package/src/tools/BashProgrammaticToolCalling.ts

@@ -8,7 +8,12 @@ import {
   executeTools,
   formatCompletedResponse,
 } from './ProgrammaticToolCalling';
-import { getCodeBaseURL } from './CodeExecutor';
+import {
+  BASH_SHELL_GUIDANCE,
+  CODE_ARTIFACT_PATH_GUIDANCE,
+  appendFailedExecutionFileReminder,
+  getCodeBaseURL,
+} from './CodeExecutor';
 import {
   clampCodeApiRunTimeoutMs,
   createCodeApiRunTimeoutSchema,
@@ -62,11 +67,14 @@ You MUST complete your entire workflow in ONE code block.
 DO NOT split work across multiple calls expecting to reuse variables.`;
 
 const CORE_RULES = `Rules:
-- EVERYTHING in one call—no state persists between executions
+- One call: state does not persist
 - Tools are pre-defined as bash functions—DO NOT redefine them
 - Each tool function accepts a JSON string argument
+- Save tool output with raw=$(tool '{}'); printf '%s\n' "$raw" > /mnt/data/file.json; direct tool > file may be empty
+- jq: use fromjson? // . on saved tool stdout and again on JSON-string fields; check types since arrays may contain strings
 - Only echo/printf output returns to the model
-- Generated files are automatically available in /mnt/data/ for subsequent executions
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
+- ${BASH_SHELL_GUIDANCE}
 - timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;
 
 const ADDITIONAL_RULES =
@@ -78,11 +86,11 @@ const EXAMPLES = `Example (Complete workflow in one call):
   echo "$data" | jq '.[] | .name'
 
 Example (Parallel calls):
-  web_search '{"query": "SF weather"}' > /tmp/sf.txt &
-  web_search '{"query": "NY weather"}' > /tmp/ny.txt &
+  { sf=$(web_search '{"query": "SF weather"}'); printf '%s\n' "$sf" > /mnt/data/sf.json; } &
+  { ny=$(web_search '{"query": "NY weather"}'); printf '%s\n' "$ny" > /mnt/data/ny.json; } &
   wait
-  echo "SF: $(cat /tmp/sf.txt)"
-  echo "NY: $(cat /tmp/ny.txt)"`;
+  echo "SF: $(jq -r . /mnt/data/sf.json)"
+  echo "NY: $(jq -r . /mnt/data/ny.json)"`;
 
 const CODE_PARAM_DESCRIPTION = `Bash code that calls tools programmatically. Tools are available as bash functions.
 
@@ -369,7 +377,7 @@ export function createBashProgrammaticToolCallingTool(
         // ====================================================================
 
         if (response.status === 'completed') {
-          return formatCompletedResponse(response);
+          return formatCompletedResponse(response, code);
         }
 
         if (response.status === 'error') {
@@ -383,8 +391,12 @@ export function createBashProgrammaticToolCallingTool(
 
         throw new Error(`Unexpected response status: ${response.status}`);
       } catch (error) {
+        const messageWithReminder = appendFailedExecutionFileReminder(
+          (error as Error).message,
+          code
+        );
         throw new Error(
-          `Bash programmatic execution failed: ${(error as Error).message}`
+          `Bash programmatic execution failed: ${messageWithReminder}`
         );
       }
     },

package/src/tools/CodeExecutor.ts

@@ -4,8 +4,14 @@ import { HttpsProxyAgent } from 'https-proxy-agent';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import { getEnvironmentVariable } from '@langchain/core/utils/env';
 import type * as t from '@/types';
+import { appendCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { EnvVar, Constants } from '@/common';
 
+export {
+  appendCodeSessionFileSummary,
+  stripCodeSessionFileSummary,
+} from '@/tools/CodeSessionFileSummary';
+
 config();
 
 export const getCodeBaseURL = (): string =>
@@ -15,6 +21,41 @@ export const getCodeBaseURL = (): string =>
 export const emptyOutputMessage =
   'stdout: Empty. Ensure you\'re writing output explicitly.\n';
 
+export const CODE_ARTIFACT_PATH_GUIDANCE =
+  'Persist handoff artifacts in `/mnt/data` with standard extensions (.json/.txt/.csv/.tsv/.log/.parquet/.png/.jpg/.pdf/.xlsx); failed executions do not register new files; `/tmp` and odd extensions are same-call scratch only, not later-call storage.';
+
+export const BASH_SHELL_GUIDANCE =
+  'Bash: multi-line files use heredoc/printf; run Python via python3 -c/heredoc, not bare Python.';
+
+const TMP_PATH_PATTERN = /(^|[^A-Za-z0-9_])\/tmp(?:\/|\b)/;
+const MNT_DATA_PATH_PATTERN = /(^|[^A-Za-z0-9_])\/mnt\/data(?:\/|\b)/;
+
+export const TMP_SCRATCH_OUTPUT_REMINDER =
+  'Note: /tmp files are same-call scratch only and were not persisted; use /mnt/data for files needed later.';
+
+export const FAILED_EXECUTION_FILE_REMINDER =
+  'Note: any files written during this failed call were not registered for later calls; fix the error and rerun before relying on them.';
+
+export function appendTmpScratchReminder(output: string, code: string): string {
+  if (!TMP_PATH_PATTERN.test(code)) {
+    return output;
+  }
+  return `${output.trimEnd()}\n${TMP_SCRATCH_OUTPUT_REMINDER}\n`;
+}
+
+export function appendFailedExecutionFileReminder(
+  output: string,
+  code: string
+): string {
+  if (
+    !MNT_DATA_PATH_PATTERN.test(code) ||
+    output.includes(FAILED_EXECUTION_FILE_REMINDER)
+  ) {
+    return output;
+  }
+  return `${output.trimEnd()}\n${FAILED_EXECUTION_FILE_REMINDER}\n`;
+}
+
 const SUPPORTED_LANGUAGES = [
   'py',
   'js',
@@ -44,8 +85,8 @@ export const CodeExecutionToolSchema = {
       type: 'string',
       description: `The complete, self-contained code to execute, without any truncation or minimization.
 - The environment is stateless; variables and imports don't persist between executions.
-- Generated files from previous executions are automatically available in "/mnt/data/".
-- Files from previous executions are automatically available and can be modified in place.
+- Prior /mnt/data files are available and can be modified in place.
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
 - Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.
 - Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.
 - IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.
@@ -104,6 +145,7 @@ Runs code and returns stdout/stderr output from a stateless execution environmen
 Usage:
 - No network access available.
 - Generated files are automatically delivered; **DO NOT** provide download links.
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
 - NEVER use this tool to execute malicious code.
 `.trim();
 
@@ -116,7 +158,7 @@ export const CodeExecutionToolDefinition = {
 } as const;
 
 function createCodeExecutionTool(
-  params: t.CodeExecutionToolParams = {}
+  params: t.CodeExecutionToolParams | null = {}
 ): DynamicStructuredTool {
   return tool(
     async (rawInput, config) => {
@@ -187,13 +229,6 @@ function createCodeExecutionTool(
         }
 
         const result: t.ExecuteResult = await response.json();
-        /* Output is stdout/stderr only — file listings were removed
-         * because the LLM-facing summary (split inherited/generated
-         * with prescriptive notes) caused more confusion than help,
-         * especially for bash where models naturally explore
-         * `/mnt/data/` themselves. The artifact still carries every
-         * file so the host's session map stays in sync; the LLM
-         * doesn't see them in the tool result text. */
         let formattedOutput = '';
         if (result.stdout) {
           formattedOutput += `stdout:\n${result.stdout}\n`;
@@ -202,9 +237,13 @@ function createCodeExecutionTool(
         }
         if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
 
+        const outputWithReminder = appendTmpScratchReminder(
+          formattedOutput,
+          code
+        );
         const hasFiles = result.files != null && result.files.length > 0;
         return [
-          formattedOutput.trim(),
+          appendCodeSessionFileSummary(outputWithReminder, result.files),
           (hasFiles
             ? { session_id: result.session_id, files: result.files }
             : {
@@ -212,8 +251,12 @@ function createCodeExecutionTool(
             }) satisfies t.CodeExecutionArtifact,
         ];
       } catch (error) {
+        const messageWithReminder = appendFailedExecutionFileReminder(
+          (error as Error | undefined)?.message ?? '',
+          code
+        );
         throw new Error(
-          `Execution error:\n\n${(error as Error | undefined)?.message}`
+          `Execution error:\n\n${messageWithReminder}`
         );
       }
     },

package/src/tools/CodeSessionFileSummary.ts

@@ -0,0 +1,80 @@
+import type * as t from '@/types';
+
+const IMAGE_FILE_EXTENSIONS = new Set([
+  '.avif',
+  '.bmp',
+  '.gif',
+  '.ico',
+  '.jpeg',
+  '.jpg',
+  '.png',
+  '.tif',
+  '.tiff',
+  '.webp',
+]);
+
+const CODE_SESSION_FILE_SUMMARY_PATTERN =
+  /^Generated files:\nSession files: \d+ persisted file\(s\) are available in \/mnt\/data, including \d+ image\(s\)\. Use known \/mnt\/data paths directly in later code-tool calls\. The app displays files\/images automatically; do not invent download links or wrap generated images in Markdown\.$/;
+
+function getFileExtension(name: string): string {
+  const lastSlash = name.lastIndexOf('/');
+  const basename = lastSlash >= 0 ? name.slice(lastSlash + 1) : name;
+  const lastDot = basename.lastIndexOf('.');
+  return lastDot >= 0 ? basename.slice(lastDot).toLowerCase() : '';
+}
+
+function isImageFile(file: Partial<t.FileRef> | null | undefined): boolean {
+  const name = file?.name;
+  return (
+    typeof name === 'string' &&
+    IMAGE_FILE_EXTENSIONS.has(getFileExtension(name))
+  );
+}
+
+function buildCodeSessionFileSummary(
+  fileCount: number,
+  imageCount: number
+): string {
+  return (
+    'Generated files:\n' +
+    `Session files: ${fileCount} persisted file(s) are available in /mnt/data, including ${imageCount} image(s). ` +
+    'Use known /mnt/data paths directly in later code-tool calls. ' +
+    'The app displays files/images automatically; do not invent download links or wrap generated images in Markdown.'
+  );
+}
+
+function isGeneratedFile(file: Partial<t.FileRef> | null | undefined): boolean {
+  return file?.inherited !== true;
+}
+
+export function stripCodeSessionFileSummary(output: string): string {
+  const summaryStart = output.lastIndexOf('Generated files:');
+  if (summaryStart < 0) return output;
+  const beforeSummary = output.slice(0, summaryStart);
+  if (beforeSummary !== '' && !beforeSummary.endsWith('\n\n')) return output;
+  const maybeSummary = output.slice(summaryStart);
+  if (!CODE_SESSION_FILE_SUMMARY_PATTERN.test(maybeSummary)) return output;
+  return beforeSummary.trimEnd();
+}
+
+export function appendCodeSessionFileSummary(
+  output: string,
+  files: t.FileRefs | undefined
+): string {
+  if (files == null || files.length === 0) {
+    return output.trim();
+  }
+
+  const generatedFiles = files.filter(isGeneratedFile);
+  if (generatedFiles.length === 0) {
+    return output.trim();
+  }
+
+  const imageCount = generatedFiles.filter(isImageFile).length;
+  const summary = buildCodeSessionFileSummary(
+    generatedFiles.length,
+    imageCount
+  );
+
+  return `${output.trimEnd()}\n\n${summary}`.trim();
+}