@librechat/agents 3.1.89 → 3.1.91

package/src/specs/langfuse-config.test.ts

@@ -0,0 +1,57 @@
+import { LangfuseSpanProcessor } from '@langfuse/otel';
+import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+import { createLangfuseHandler } from '@/langfuse';
+
+jest.mock('@langfuse/otel', () => ({
+  LangfuseSpanProcessor: jest.fn().mockImplementation(() => ({})),
+}));
+
+jest.mock('@opentelemetry/sdk-trace-base', () => ({
+  BasicTracerProvider: jest.fn().mockImplementation(() => ({
+    forceFlush: jest.fn(),
+    getTracer: jest.fn(),
+    shutdown: jest.fn(),
+  })),
+}));
+
+describe('createLangfuseHandler', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('creates a handler when keys are provided and baseUrl is omitted', () => {
+    const handler = createLangfuseHandler({
+      langfuse: {
+        enabled: true,
+        publicKey: 'pk-test',
+        secretKey: 'sk-test',
+      },
+    });
+
+    expect(handler).toBeDefined();
+    expect(LangfuseSpanProcessor).toHaveBeenCalledWith(
+      expect.objectContaining({
+        publicKey: 'pk-test',
+        secretKey: 'sk-test',
+        exportMode: 'immediate',
+      })
+    );
+    expect(
+      (LangfuseSpanProcessor as jest.Mock).mock.calls[0][0].baseUrl
+    ).toBeUndefined();
+    expect(BasicTracerProvider).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not create a handler when a required key is missing', () => {
+    const handler = createLangfuseHandler({
+      langfuse: {
+        enabled: true,
+        publicKey: 'pk-test',
+      },
+    });
+
+    expect(handler).toBeUndefined();
+    expect(LangfuseSpanProcessor).not.toHaveBeenCalled();
+    expect(BasicTracerProvider).not.toHaveBeenCalled();
+  });
+});

package/src/specs/langfuse-metadata.test.ts

@@ -10,7 +10,10 @@ const MockedCallbackHandler = CallbackHandler as jest.MockedClass<
   typeof CallbackHandler
 >;
 
-async function createTestRun(agentName?: string): Promise<Run<never>> {
+async function createTestRun(
+  agentName?: string,
+  agentOverrides: Record<string, unknown> = {}
+): Promise<Run<never>> {
   const run = await Run.create({
     runId: 'test-run-id',
     graphConfig: {
@@ -22,6 +25,7 @@ async function createTestRun(agentName?: string): Promise<Run<never>> {
           provider: Providers.OPENAI,
           clientOptions: { model: 'gpt-4' },
           tools: [],
+          ...agentOverrides,
         },
       ],
     },
@@ -88,4 +92,18 @@ describe('Langfuse trace metadata includes agentName', () => {
 
     expect(MockedCallbackHandler).not.toHaveBeenCalled();
   });
+
+  it('does not create the legacy CallbackHandler when explicit agent config is supplied', async () => {
+    const run = await createTestRun('DWAINE', {
+      langfuse: {
+        enabled: false,
+      },
+    });
+    await run.processStream(
+      { messages: [] },
+      { configurable: { thread_id: 't1', user_id: 'u1' }, version: 'v2' }
+    );
+
+    expect(MockedCallbackHandler).not.toHaveBeenCalled();
+  });
 });

package/src/stream.ts

@@ -136,10 +136,19 @@ function isDirectGraphTool(
 }
 
 function isDirectLocalTool(name: string, graph: StandardGraph): boolean {
-  if (graph.toolExecution?.engine !== 'local') {
+  const toolExecution = graph.toolExecution;
+  const engine = toolExecution?.engine;
+  if (
+    toolExecution == null ||
+    (engine !== 'local' && engine !== 'cloudflare-sandbox')
+  ) {
     return false;
   }
-  if (graph.toolExecution.local?.includeCodingTools === false) {
+  const includeCodingTools =
+    engine === 'cloudflare-sandbox'
+      ? toolExecution.cloudflare?.includeCodingTools
+      : toolExecution.local?.includeCodingTools;
+  if (includeCodingTools === false) {
     return CODE_EXECUTION_TOOLS.has(name);
   }
   return LOCAL_CODING_BUNDLE_NAME_SET.has(name);
@@ -270,7 +279,8 @@ function hasPotentialDirectToolInStreamContext(args: {
   agentContext?: AgentContext;
 }): boolean {
   const { graph, agentContext } = args;
-  if (graph.toolExecution?.engine === 'local') {
+  const engine = graph.toolExecution?.engine;
+  if (engine === 'local' || engine === 'cloudflare-sandbox') {
     return true;
   }
   if ((agentContext?.graphTools?.length ?? 0) > 0) {

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

package/src/tools/ProgrammaticToolCalling.ts

@@ -7,9 +7,13 @@ import type { ToolCall } from '@langchain/core/messages/tool';
 import type { ProgrammaticToolCallingJsonSchema } from './ptcTimeout';
 import type * as t from '@/types';
 import {
+  CODE_ARTIFACT_PATH_GUIDANCE,
+  appendCodeSessionFileSummary,
+  appendFailedExecutionFileReminder,
   buildCodeApiHttpErrorMessage,
   emptyOutputMessage,
   getCodeBaseURL,
+  appendTmpScratchReminder,
   resolveCodeApiAuthHeaders,
 } from './CodeExecutor';
 import {
@@ -36,15 +40,17 @@ You MUST complete your entire workflow in ONE code block: query → process →
 DO NOT split work across multiple calls expecting to reuse variables.`;
 
 const CORE_RULES = `Rules:
-- EVERYTHING in one call—no state persists between executions
-- Just write code with await—auto-wrapped in async context
-- DO NOT define async def main() or call asyncio.run()
+- One call: state does not persist
+- Auto-wrapped async; use await, no main()/asyncio.run()
 - Tools are pre-defined—DO NOT write function definitions
+- Call tools with keyword args only (await tool(arg=value), never pass a dict)
+- Tool results are decoded Python values (dict/list/str)
 - Only print() output returns to the model
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
 - timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;
 
-const ADDITIONAL_RULES = `- Generated files are automatically available in /mnt/data/ for subsequent executions
-- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix`;
+const ADDITIONAL_RULES =
+  '- Tool names normalized: hyphens→underscores, keywords get `_tool` suffix';
 
 const EXAMPLES = `Example (Complete workflow in one call):
   # Query data
@@ -678,15 +684,16 @@ export async function executeTools(
 /**
  * Formats the completed response for the agent.
  *
- * Output is stdout/stderr only — see `CodeExecutor.ts`. 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.
+ * Output includes stdout/stderr plus a compact session-file summary
+ * when artifacts were persisted. The artifact still carries every
+ * file so the host's session map stays in sync.
  *
  * @param response - The completed API response
  * @returns Tuple of [formatted string, artifact]
  */
 export function formatCompletedResponse(
-  response: t.ProgrammaticExecutionResponse
+  response: t.ProgrammaticExecutionResponse,
+  sourceCode = ''
 ): [string, t.ProgrammaticExecutionArtifact] {
   let formatted = '';
 
@@ -700,8 +707,10 @@ export function formatCompletedResponse(
     formatted += `stderr:\n${response.stderr}\n`;
   }
 
+  const outputWithReminder = appendTmpScratchReminder(formatted, sourceCode);
+
   return [
-    formatted.trim(),
+    appendCodeSessionFileSummary(outputWithReminder, response.files),
     {
       session_id: response.session_id,
       files: response.files,
@@ -859,7 +868,7 @@ export function createProgrammaticToolCallingTool(
         // ====================================================================
 
         if (response.status === 'completed') {
-          return formatCompletedResponse(response);
+          return formatCompletedResponse(response, code);
         }
 
         if (response.status === 'error') {
@@ -873,8 +882,12 @@ export function createProgrammaticToolCallingTool(
 
         throw new Error(`Unexpected response status: ${response.status}`);
       } catch (error) {
+        const messageWithReminder = appendFailedExecutionFileReminder(
+          (error as Error).message,
+          code
+        );
         throw new Error(
-          `Programmatic execution failed: ${(error as Error).message}`
+          `Programmatic execution failed: ${messageWithReminder}`
         );
       }
     },

package/src/tools/ToolNode.ts

@@ -46,6 +46,7 @@ import {
   buildReferenceKey,
   ToolOutputReferenceRegistry,
 } from '@/tools/toolOutputReferences';
+import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import {
   resolveLocalToolRegistry,
   resolveLocalExecutionTools,
@@ -911,8 +912,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        * Both session_id and _injected_files are injected directly to invokeParams
        * (not inside args) so they bypass Zod schema validation and reach config.toolCall.
        *
-       * session_id is always injected when available (even without tracked files)
-       * so the CodeExecutor can fall back to the /files endpoint for session continuity.
+       * session_id is always injected when available, but concrete file refs
+       * still need to travel through `_injected_files`; the legacy
+       * `/files/<session_id>` fallback was removed from the executors.
        */
       if (CODE_EXECUTION_TOOLS.has(call.name)) {
         const codeSession = this.sessions?.get(Constants.EXECUTE_CODE) as
@@ -959,6 +961,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         if (this.toolOutputRegistry != null || unresolvedRefs.length > 0) {
           if (typeof toolMsg.content === 'string') {
             const rawContent = toolMsg.content;
+            const registryContent = stripCodeSessionFileSummary(rawContent);
             const llmContent = truncateToolResultContent(
               rawContent,
               this.maxToolResultChars
@@ -966,7 +969,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             toolMsg.content = llmContent;
             const refMeta = this.recordOutputReference(
               runId,
-              rawContent,
+              registryContent,
               refKey,
               unresolvedRefs
             );
@@ -1015,7 +1018,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       );
       const refMeta = this.recordOutputReference(
         runId,
-        rawContent,
+        stripCodeSessionFileSummary(rawContent),
         refKey,
         unresolvedRefs
       );
@@ -2661,7 +2664,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               : undefined;
           const successRefMeta = this.recordOutputReference(
             registryRunId,
-            registryRaw,
+            stripCodeSessionFileSummary(registryRaw),
             refKey,
             unresolved
           );

package/src/tools/__tests__/BashExecutor.test.ts

@@ -18,6 +18,15 @@ describe('buildBashExecutionToolDescription', () => {
     ).toBe(BashExecutionToolDescription);
   });
 
+  it('warns about compact bash shell pitfalls', () => {
+    expect(BashExecutionToolDescription).toContain('heredoc/printf');
+    expect(BashExecutionToolDescription).toContain('not bare Python');
+    expect(BashExecutionToolDescription).toContain(
+      'failed executions do not register new files'
+    );
+    expect(BashExecutionToolDescription).toContain('not later-call storage');
+  });
+
   it('appends the tool-output references guide when enabled', () => {
     const composed = buildBashExecutionToolDescription({
       enableToolOutputReferences: true,