@librechat/agents 3.1.88 → 3.1.90

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
       );
@@ -1062,13 +1065,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             handlerError:
               handlerError instanceof Error
                 ? {
-                    message: handlerError.message,
-                    stack: handlerError.stack ?? undefined,
-                  }
+                  message: handlerError.message,
+                  stack: handlerError.stack ?? undefined,
+                }
                 : {
-                    message: String(handlerError),
-                    stack: undefined,
-                  },
+                  message: String(handlerError),
+                  stack: undefined,
+                },
           });
         }
       }
@@ -1076,11 +1079,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       const refMeta =
         unresolvedRefs.length > 0
           ? this.recordOutputReference(
-              runId,
-              errorContent,
-              undefined,
-              unresolvedRefs
-            )
+            runId,
+            errorContent,
+            undefined,
+            unresolvedRefs
+          )
           : undefined;
       return new ToolMessage({
         status: 'error',
@@ -2432,59 +2435,77 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         dispatchRequests.length === 0
           ? Promise.resolve([] as t.ToolExecuteResult[])
           : new Promise<t.ToolExecuteResult[]>((resolve, reject) => {
-              let dispatchSettled = false;
-              let resultSettled = false;
-              let settledResults: t.ToolExecuteResult[] | undefined;
+            let dispatchSettled = false;
+            let resultSettled = false;
+            let settledResults: t.ToolExecuteResult[] | undefined;
 
-              const maybeResolve = (): void => {
-                if (dispatchSettled && resultSettled) {
-                  resolve(settledResults ?? []);
-                }
-              };
+            const maybeResolve = (): void => {
+              if (dispatchSettled && resultSettled) {
+                resolve(settledResults ?? []);
+              }
+            };
 
-              const batchRequest: t.ToolExecuteBatchRequest = {
-                toolCalls: dispatchRequests,
-                userId: config.configurable?.user_id as string | undefined,
-                agentId: this.agentId,
-                configurable: config.configurable as
+            const batchRequest: t.ToolExecuteBatchRequest = {
+              toolCalls: dispatchRequests,
+              userId: config.configurable?.user_id as string | undefined,
+              agentId: this.agentId,
+              configurable: config.configurable as
                   | Record<string, unknown>
                   | undefined,
-                metadata: config.metadata as
+              metadata: config.metadata as
                   | Record<string, unknown>
                   | undefined,
-                resolve: (results): void => {
-                  resultSettled = true;
-                  settledResults = results;
-                  maybeResolve();
-                },
-                reject,
-              };
+              resolve: (results): void => {
+                resultSettled = true;
+                settledResults = results;
+                maybeResolve();
+              },
+              reject,
+            };
 
-              void safeDispatchCustomEvent(
-                GraphEvents.ON_TOOL_EXECUTE,
-                batchRequest,
-                config
-              )
-                .then(() => {
-                  dispatchSettled = true;
-                  maybeResolve();
-                })
-                .catch(reject);
-            });
+            void safeDispatchCustomEvent(
+              GraphEvents.ON_TOOL_EXECUTE,
+              batchRequest,
+              config
+            )
+              .then(() => {
+                dispatchSettled = true;
+                maybeResolve();
+              })
+              .catch(reject);
+          });
 
       const eagerResultsPromise = Promise.all(
-        eagerExecutions.map(({ request, execution }) =>
-          this.resolveEagerEventExecution(request, execution)
-        )
-      ).then((results) => results.flat());
+        eagerExecutions.map(async ({ request, execution }) => {
+          const results = await this.resolveEagerEventExecution(
+            request,
+            execution
+          );
+          return {
+            results,
+            completionDispatched:
+              execution.completionDispatched === true &&
+              execution.request.turn === request.turn,
+            toolCallId: request.id,
+          };
+        })
+      );
 
       const [eagerResults, dispatchedResults] = await Promise.all([
         eagerResultsPromise,
         dispatchPromise,
       ]);
+      const eagerCompletionDispatchedIds = new Set(
+        eagerResults
+          .filter((result) => result.completionDispatched)
+          .map((result) => result.toolCallId)
+      );
+      const flattenedEagerResults = eagerResults.flatMap(
+        (result) => result.results
+      );
       const results = [
         ...plan.rejectedResults,
-        ...eagerResults,
+        ...flattenedEagerResults,
         ...dispatchedResults,
       ];
 
@@ -2537,11 +2558,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           const errorRefMeta =
             unresolved.length > 0
               ? this.recordOutputReference(
-                  registryRunId,
-                  contentString,
-                  undefined,
-                  unresolved
-                )
+                registryRunId,
+                contentString,
+                undefined,
+                unresolved
+              )
               : undefined;
           toolMessage = new ToolMessage({
             status: 'error',
@@ -2643,7 +2664,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               : undefined;
           const successRefMeta = this.recordOutputReference(
             registryRunId,
-            registryRaw,
+            stripCodeSessionFileSummary(registryRaw),
             refKey,
             unresolved
           );
@@ -2660,14 +2681,16 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           });
         }
 
-        await this.dispatchStepCompleted(
-          result.toolCallId,
-          toolName,
-          request?.args ?? {},
-          contentString,
-          config,
-          request?.turn
-        );
+        if (!eagerCompletionDispatchedIds.has(result.toolCallId)) {
+          await this.dispatchStepCompleted(
+            result.toolCallId,
+            toolName,
+            request?.args ?? {},
+            contentString,
+            config,
+            request?.turn
+          );
+        }
 
         postToolBatchEntryByCallId.set(result.toolCallId, {
           toolName,
@@ -2706,8 +2729,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       this.eventDrivenMode &&
       this.eagerEventToolExecution?.enabled === true &&
       this.hookRegistry == null &&
-      this.humanInTheLoop?.enabled !== true &&
-      this.toolOutputRegistry == null
+      this.humanInTheLoop?.enabled !== true
     );
   }
 
@@ -2725,10 +2747,14 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
 
     this.eagerEventToolExecutions?.delete(request.id);
 
+    // Only tool identity + canonical args define side-effect identity here.
+    // `request.turn` is final-planning metadata; if it drifts between the
+    // streamed eager reservation and model-end materialization, consume the
+    // same-name/same-args eager result and let the final request drive refs,
+    // completion metadata, and PostToolBatch state.
     if (
       execution.toolName !== request.name ||
-      !recordArgsEqual(execution.args, request.args) ||
-      execution.request.turn !== request.turn
+      !recordArgsEqual(execution.args, request.args)
     ) {
       return {
         toolCallId: request.id,
@@ -3015,15 +3041,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       outputs =
         directAdditionalContexts.length > 0
           ? [
-              sendOutput,
-              new HumanMessage({
-                content: directAdditionalContexts.join('\n\n'),
-                // Match the event-driven path's marker so hosts /
-                // model-side annotators treat this as system intent
-                // rather than ordinary user text. Codex P2 [46].
-                additional_kwargs: { role: 'system', source: 'hook' },
-              }),
-            ]
+            sendOutput,
+            new HumanMessage({
+              content: directAdditionalContexts.join('\n\n'),
+              // Match the event-driven path's marker so hosts /
+              // model-side annotators treat this as system intent
+              // rather than ordinary user text. Codex P2 [46].
+              additional_kwargs: { role: 'system', source: 'hook' },
+            }),
+          ]
           : [sendOutput];
       await this.handleRunToolCompletions(
         [input.lg_tool_call],
@@ -3174,17 +3200,17 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const directOutputs: (BaseMessage | Command)[] =
           directCalls.length > 0
             ? await Promise.all(
-                directCalls.map((call, i) =>
-                  this.runDirectToolWithLifecycleHooks(call, config, {
-                    batchIndex: directIndices[i],
-                    turn,
-                    batchScopeId,
-                    resolvedArgsByCallId,
-                    preBatchSnapshot,
-                    additionalContextsSink: directAdditionalContexts,
-                  })
-                )
+              directCalls.map((call, i) =>
+                this.runDirectToolWithLifecycleHooks(call, config, {
+                  batchIndex: directIndices[i],
+                  turn,
+                  batchScopeId,
+                  resolvedArgsByCallId,
+                  preBatchSnapshot,
+                  additionalContextsSink: directAdditionalContexts,
+                })
               )
+            )
             : [];
 
         if (directCalls.length > 0 && directOutputs.length > 0) {
@@ -3199,29 +3225,29 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const eventResult =
           eventCalls.length > 0
             ? await this.dispatchToolEvents(eventCalls, config, {
-                batchIndices: eventIndices,
-                turn,
-                batchScopeId,
-                preResolvedArgs: preResolvedEventArgs,
-                preBatchSnapshot,
-              })
+              batchIndices: eventIndices,
+              turn,
+              batchScopeId,
+              preResolvedArgs: preResolvedEventArgs,
+              preBatchSnapshot,
+            })
             : {
-                toolMessages: [] as ToolMessage[],
-                injected: [] as BaseMessage[],
-              };
+              toolMessages: [] as ToolMessage[],
+              injected: [] as BaseMessage[],
+            };
 
         const directInjected: BaseMessage[] =
           directAdditionalContexts.length > 0
             ? [
-                new HumanMessage({
-                  content: directAdditionalContexts.join('\n\n'),
-                  // System-role metadata to match the event-driven
-                  // path so policy/recovery guidance is treated
-                  // consistently regardless of whether the tool ran
-                  // direct or dispatched. Codex P2 [46].
-                  additional_kwargs: { role: 'system', source: 'hook' },
-                }),
-              ]
+              new HumanMessage({
+                content: directAdditionalContexts.join('\n\n'),
+                // System-role metadata to match the event-driven
+                // path so policy/recovery guidance is treated
+                // consistently regardless of whether the tool ran
+                // direct or dispatched. Codex P2 [46].
+                additional_kwargs: { role: 'system', source: 'hook' },
+              }),
+            ]
             : [];
         outputs = [
           ...directOutputs,
@@ -3260,15 +3286,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         outputs =
           directAdditionalContexts.length > 0
             ? [
-                ...toolOutputs,
-                new HumanMessage({
-                  content: directAdditionalContexts.join('\n\n'),
-                  // Same system-role marker the event-driven path
-                  // uses so direct vs dispatched is invisible to
-                  // downstream consumers. Codex P2 [46].
-                  additional_kwargs: { role: 'system', source: 'hook' },
-                }),
-              ]
+              ...toolOutputs,
+              new HumanMessage({
+                content: directAdditionalContexts.join('\n\n'),
+                // Same system-role marker the event-driven path
+                // uses so direct vs dispatched is invisible to
+                // downstream consumers. Codex P2 [46].
+                additional_kwargs: { role: 'system', source: 'hook' },
+              }),
+            ]
             : toolOutputs;
       }
     }

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,

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

@@ -165,6 +165,17 @@ describe('CodeAPI auth header injection', () => {
     ).not.toHaveProperty('authHeaders');
   });
 
+  it('tolerates null params for direct code execution', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ session_id: 'session_123', stdout: '1\n' })
+    );
+    const tool = createCodeExecutionTool(null);
+
+    await expect(
+      tool.invoke({ lang: 'py', code: 'print(1)' })
+    ).resolves.toBeDefined();
+  });
+
   it('forwards Authorization for bash execution', async () => {
     fetchMock.mockResolvedValueOnce(
       jsonResponse({ session_id: 'session_123', stdout: '1\n' })
@@ -333,6 +344,38 @@ describe('CodeAPI auth header injection', () => {
     );
   });
 
+  it('reminds that failed bash programmatic executions do not register new files', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        status: 'error',
+        error: 'jq failed',
+        stderr: 'jq: Cannot index string with string "name"',
+      })
+    );
+    const tool = createBashProgrammaticToolCallingTool();
+
+    await expect(
+      tool.invoke(
+        {
+          code: [
+            'lookup_user "{}" > /mnt/data/user.json',
+            'jq -r \'.result.name\' /mnt/data/user.json',
+          ].join('\n'),
+        },
+        {
+          toolCall: {
+            name: 'bash_programmatic_code_execution',
+            args: {},
+            toolMap: toolMap(),
+            toolDefs,
+          },
+        }
+      )
+    ).rejects.toThrow(
+      'files written during this failed call were not registered for later calls'
+    );
+  });
+
   it('fetches session files with the CodeAPI resource scope and auth headers', async () => {
     fetchMock.mockResolvedValueOnce(
       jsonResponse([