@librechat/agents 3.2.58 → 3.2.59

package/src/tools/CodeExecutor.ts

@@ -149,6 +149,64 @@ Usage:
 - NEVER use this tool to execute malicious code.
 `.trim();
 
+/**
+ * Best-effort statefulness note. Deliberately hedged: warm reuse is an
+ * optimization, not a guarantee (the runtime may be reset on idle timeout,
+ * eviction, or the 8h VM lifetime), so the model must never depend on carried
+ * state for correctness and must persist anything durable to /mnt/data.
+ */
+export const STATEFUL_ENV_NOTE =
+  'Session state (best-effort): consecutive executions in this conversation usually share one runtime, so variables, imports, and in-memory data from earlier successful calls are typically still available. The runtime may be reset at any time, so treat carried-over state as an optimization, never a guarantee. Anything that must survive MUST be written to /mnt/data. If a NameError/ImportError signals lost state, re-run the needed setup and continue.';
+
+export const StatefulCodeExecutionToolDescription = `
+Runs code and returns stdout/stderr output from a session-based execution environment, similar to a long-running command-line session.
+
+${STATEFUL_ENV_NOTE}
+
+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();
+
+export function buildCodeExecutionToolDescription(opts?: {
+  statefulSessions?: boolean;
+}): string {
+  return opts?.statefulSessions === true
+    ? StatefulCodeExecutionToolDescription
+    : CodeExecutionToolDescription;
+}
+
+const STATELESS_CODE_PARAM_NOTE =
+  'The environment is stateless; variables and imports don\'t persist between executions.';
+const STATEFUL_CODE_PARAM_NOTE =
+  'Executions in this conversation usually share one runtime: variables and imports from prior successful calls are typically still defined, but the runtime may reset between calls. Rebuild state on NameError/ImportError; persist anything important to /mnt/data.';
+
+export function buildCodeExecutionToolSchema(opts?: {
+  statefulSessions?: boolean;
+}): typeof CodeExecutionToolSchema {
+  const note =
+    opts?.statefulSessions === true
+      ? STATEFUL_CODE_PARAM_NOTE
+      : STATELESS_CODE_PARAM_NOTE;
+  const codeDescription =
+    CodeExecutionToolSchema.properties.code.description.replace(
+      STATELESS_CODE_PARAM_NOTE,
+      note
+    );
+  return {
+    ...CodeExecutionToolSchema,
+    properties: {
+      ...CodeExecutionToolSchema.properties,
+      code: {
+        ...CodeExecutionToolSchema.properties.code,
+        description: codeDescription,
+      },
+    },
+  } as typeof CodeExecutionToolSchema;
+}
+
 export const CodeExecutionToolName = Constants.EXECUTE_CODE;
 
 export const CodeExecutionToolDefinition = {
@@ -162,21 +220,42 @@ function createCodeExecutionTool(
 ): DynamicStructuredTool {
   return tool(
     async (rawInput, config) => {
-      const { authHeaders, ...executionParams } = params ?? {};
-      const { lang, code, ...rest } = rawInput as {
+      /* `statefulSessions` is a prompt-only flag (drives the description);
+       * keep it out of the wire body. */
+      const {
+        authHeaders,
+        statefulSessions: _statefulSessions,
+        ...executionParams
+      } = params ?? {};
+      void _statefulSessions;
+      /* Drop any model-supplied `runtime_session_hint` from the raw args: the
+       * hint is host-controlled and must only ever come from ToolNode's
+       * injected `_runtime_session_hint` (below). Spreading `...rest` into
+       * postData would otherwise let a tool call opt itself into / pick a
+       * stateful runtime even when statefulSessions is off. */
+      const {
+        lang,
+        code,
+        runtime_session_hint: _ignoredModelHint,
+        ...rest
+      } = rawInput as {
         lang: SupportedLanguage;
         code: string;
+        runtime_session_hint?: unknown;
         args?: string[];
       };
+      void _ignoredModelHint;
       /**
        * Extract session context from config.toolCall (injected by ToolNode).
        * - session_id: associates with the previous run.
        * - _injected_files: File refs to pass directly (avoids /files endpoint race condition).
        */
-      const { session_id, _injected_files } = (config.toolCall ?? {}) as {
-        session_id?: string;
-        _injected_files?: t.CodeEnvFile[];
-      };
+      const { session_id, _injected_files, _runtime_session_hint } =
+        (config.toolCall ?? {}) as {
+          session_id?: string;
+          _injected_files?: t.CodeEnvFile[];
+          _runtime_session_hint?: string;
+        };
 
       const postData: Record<string, unknown> = {
         lang,
@@ -185,6 +264,16 @@ function createCodeExecutionTool(
         ...executionParams,
       };
 
+      /* Stateful sessions: forward the hint so the Code API can route this
+       * execution to a warm per-session runtime. Additive — stateless
+       * servers ignore the unknown field. */
+      if (
+        typeof _runtime_session_hint === 'string' &&
+        _runtime_session_hint !== ''
+      ) {
+        postData.runtime_session_hint = _runtime_session_hint;
+      }
+
       /* File injection: `_injected_files` from ToolNode (set when host
        * primes a CodeSessionContext) or `params.files` from tool
        * factory (set by hosts that pre-resolve at construction time).
@@ -242,12 +331,27 @@ function createCodeExecutionTool(
           code
         );
         const hasFiles = result.files != null && result.files.length > 0;
+        /* Echo the durable runtime session (stateful backends only) so hosts
+         * can surface a "session active / was reset" signal later. Additive:
+         * absent on stateless servers. */
+        const runtimeEcho =
+          result.runtime_session_id != null
+            ? {
+              runtime_session_id: result.runtime_session_id,
+              runtime_status: result.runtime_status,
+            }
+            : {};
         return [
           appendCodeSessionFileSummary(outputWithReminder, result.files),
           (hasFiles
-            ? { session_id: result.session_id, files: result.files }
+            ? {
+              session_id: result.session_id,
+              files: result.files,
+              ...runtimeEcho,
+            }
             : {
               session_id: result.session_id,
+              ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,
         ];
       } catch (error) {
@@ -260,8 +364,8 @@ function createCodeExecutionTool(
     },
     {
       name: CodeExecutionToolName,
-      description: CodeExecutionToolDescription,
-      schema: CodeExecutionToolSchema,
+      description: buildCodeExecutionToolDescription(params ?? undefined),
+      schema: buildCodeExecutionToolSchema(params ?? undefined),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

package/src/tools/ProgrammaticToolCalling.ts

@@ -830,6 +830,12 @@ export function formatCompletedResponse(
     {
       session_id: response.session_id,
       files: response.files,
+      ...(response.runtime_session_id != null
+        ? {
+          runtime_session_id: response.runtime_session_id,
+          runtime_status: response.runtime_status,
+        }
+        : {}),
     } satisfies t.ProgrammaticExecutionArtifact,
   ];
 }
@@ -878,8 +884,15 @@ export function createProgrammaticToolCallingTool(
         Partial<t.ProgrammaticCache> & {
           session_id?: string;
           _injected_files?: t.CodeEnvFile[];
+          _runtime_session_hint?: string;
         };
-      const { toolMap, toolDefs, session_id, _injected_files } = toolCall;
+      const {
+        toolMap,
+        toolDefs,
+        session_id,
+        _injected_files,
+        _runtime_session_hint,
+      } = toolCall;
 
       if (toolMap == null || toolMap.size === 0) {
         throw new Error(
@@ -928,6 +941,16 @@ export function createProgrammaticToolCallingTool(
           );
         }
 
+        /* Stateful sessions: hint rides the INITIAL request only; the server
+         * binds continuation round-trips to the same runtime via the
+         * continuation_token. Additive — ignored by stateless servers. PTC
+         * keeps its stateless prompt in v1; only the wire hint plumbs here. */
+        const runtimeSessionHint =
+          typeof _runtime_session_hint === 'string' &&
+          _runtime_session_hint !== ''
+            ? _runtime_session_hint
+            : undefined;
+
         let response = await makeRequest(
           EXEC_ENDPOINT,
           {
@@ -936,6 +959,9 @@ export function createProgrammaticToolCallingTool(
             session_id,
             timeout,
             ...(files && files.length > 0 ? { files } : {}),
+            ...(runtimeSessionHint != null
+              ? { runtime_session_hint: runtimeSessionHint }
+              : {}),
           },
           proxy,
           initParams.authHeaders

package/src/tools/ToolNode.ts

@@ -37,6 +37,11 @@ import type {
   PostToolBatchEntry,
 } from '@/hooks';
 import type * as t from '@/types';
+import {
+  buildToolExecutionRequestPlan,
+  resolveRuntimeSessionHint,
+  recordArgsEqual,
+} from '@/tools/eagerEventExecution';
 import {
   resolveLangfuseRuntimeScope,
   withLangfuseRuntimeScope,
@@ -45,10 +50,6 @@ import {
   buildReferenceKey,
   ToolOutputReferenceRegistry,
 } from '@/tools/toolOutputReferences';
-import {
-  buildToolExecutionRequestPlan,
-  recordArgsEqual,
-} from '@/tools/eagerEventExecution';
 import {
   calculateMaxToolResultChars,
   truncateToolResultContent,
@@ -997,6 +998,20 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             );
           }
         }
+
+        /**
+         * Stateful runtime session hint — orthogonal to the transient
+         * exec-session above, and injected independently (a first call has a
+         * hint but no exec session yet). Explicit host hint wins; otherwise
+         * fall back to the conversation's thread_id.
+         */
+        const runtimeSessionHint = this.resolveRuntimeSessionHint(config);
+        if (runtimeSessionHint != null) {
+          invokeParams = {
+            ...invokeParams,
+            _runtime_session_hint: runtimeSessionHint,
+          };
+        }
       }
 
       /**
@@ -1783,6 +1798,17 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     );
   }
 
+  /** Delegates to the shared resolver so the direct and event-driven planning
+   *  paths derive the runtime session hint identically. */
+  private resolveRuntimeSessionHint(
+    config: RunnableConfig
+  ): string | undefined {
+    return resolveRuntimeSessionHint(
+      this.toolExecution,
+      config.configurable?.thread_id as string | undefined
+    );
+  }
+
   private storeCodeSessionFromResults(
     results: t.ToolExecuteResult[],
     requestMap: Map<string, t.ToolCallRequest>
@@ -2492,12 +2518,18 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             entry.call.name === Constants.READ_FILE
               ? this.getCodeSessionContext()
               : undefined;
+          const runtimeSessionHint = this.participatesInCodeSession(
+            entry.call.name
+          )
+            ? this.resolveRuntimeSessionHint(config)
+            : undefined;
           return {
             id: entry.call.id,
             name: entry.call.name,
             args: entry.args,
             stepId: entry.stepId,
             codeSessionContext,
+            runtimeSessionHint,
           };
         }),
         usageCount: this.toolUsageCount,

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

@@ -2,8 +2,10 @@ import { describe, it, expect } from '@jest/globals';
 import {
   BashExecutionToolDescription,
   BashToolOutputReferencesGuide,
+  StatefulBashExecutionToolDescription,
   buildBashExecutionToolDescription,
 } from '../BashExecutor';
+import { CODE_ARTIFACT_PATH_GUIDANCE } from '../CodeExecutor';
 
 describe('buildBashExecutionToolDescription', () => {
   it('returns the base description by default', () => {
@@ -55,4 +57,41 @@ describe('buildBashExecutionToolDescription', () => {
     });
     expect(composed.includes(`${BashExecutionToolDescription}\n\n`)).toBe(true);
   });
+
+  describe('stateful variant', () => {
+    it('selects the stateful description when statefulSessions is on', () => {
+      expect(
+        buildBashExecutionToolDescription({ statefulSessions: true })
+      ).toBe(StatefulBashExecutionToolDescription);
+    });
+
+    it('hedges: usually-persists but may-reset, and only /mnt/data is durable', () => {
+      const d = StatefulBashExecutionToolDescription;
+      expect(d).toContain('usually');
+      expect(d).toContain('may be reset');
+      expect(d).toContain('Only /mnt/data is durable');
+      /* filesystem-tier, not shell-variable-tier */
+      expect(d).toContain('do not rely on shell variables');
+    });
+
+    it('keeps the artifact-path guidance in both variants', () => {
+      expect(BashExecutionToolDescription).toContain(
+        CODE_ARTIFACT_PATH_GUIDANCE
+      );
+      expect(StatefulBashExecutionToolDescription).toContain(
+        CODE_ARTIFACT_PATH_GUIDANCE
+      );
+    });
+
+    it('still composes with the output-references guide', () => {
+      const composed = buildBashExecutionToolDescription({
+        statefulSessions: true,
+        enableToolOutputReferences: true,
+      });
+      expect(composed.startsWith(StatefulBashExecutionToolDescription)).toBe(
+        true
+      );
+      expect(composed).toContain(BashToolOutputReferencesGuide);
+    });
+  });
 });

package/src/tools/__tests__/CodeExecutor.stateful.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, jest, afterEach } from '@jest/globals';
+import type { RunnableConfig } from '@langchain/core/runnables';
+
+/* CodeExecutor imports the default export of node-fetch; capture POST bodies. */
+const fetchCalls: Array<Record<string, unknown>> = [];
+jest.mock('node-fetch', () => ({
+  __esModule: true,
+  default: async (_url: string, init?: { body?: string }) => {
+    fetchCalls.push(JSON.parse(init?.body ?? '{}'));
+    return {
+      ok: true,
+      json: async () => ({
+        session_id: 's1',
+        stdout: 'ok',
+        stderr: '',
+        files: [],
+      }),
+    };
+  },
+}));
+
+import {
+  CODE_ARTIFACT_PATH_GUIDANCE,
+  CodeExecutionToolDescription,
+  StatefulCodeExecutionToolDescription,
+  buildCodeExecutionToolDescription,
+  buildCodeExecutionToolSchema,
+  createCodeExecutionTool,
+} from '../CodeExecutor';
+
+describe('CodeExecutor stateful description', () => {
+  it('selects the stateful description only when statefulSessions is on', () => {
+    expect(buildCodeExecutionToolDescription()).toBe(
+      CodeExecutionToolDescription
+    );
+    expect(buildCodeExecutionToolDescription({ statefulSessions: false })).toBe(
+      CodeExecutionToolDescription
+    );
+    expect(buildCodeExecutionToolDescription({ statefulSessions: true })).toBe(
+      StatefulCodeExecutionToolDescription
+    );
+  });
+
+  it('hedges the stateful wording and keeps /mnt/data as the durable store', () => {
+    const d = StatefulCodeExecutionToolDescription;
+    expect(d).toContain('usually share one runtime');
+    expect(d).toContain('may be reset at any time');
+    expect(d).toContain('MUST be written to /mnt/data');
+    expect(d).toContain(CODE_ARTIFACT_PATH_GUIDANCE);
+  });
+
+  it('adjusts the code-param note per mode', () => {
+    const stateless =
+      buildCodeExecutionToolSchema().properties.code.description;
+    const stateful = buildCodeExecutionToolSchema({ statefulSessions: true })
+      .properties.code.description;
+    expect(stateless).toContain('variables and imports don\'t persist');
+    expect(stateful).toContain('typically still defined');
+    expect(stateful).toContain('may reset between calls');
+  });
+});
+
+describe('CodeExecutor runtime_session_hint wire field', () => {
+  afterEach(() => {
+    fetchCalls.length = 0;
+  });
+
+  async function run(
+    toolCall: Record<string, unknown>,
+    params: Record<string, unknown> = {}
+  ): Promise<Record<string, unknown>[]> {
+    const codeTool = createCodeExecutionTool(params);
+    await codeTool.invoke({ lang: 'py', code: 'print(1)' }, {
+      toolCall,
+    } as unknown as RunnableConfig);
+    return fetchCalls;
+  }
+
+  it('sends runtime_session_hint when ToolNode injected it', async () => {
+    const calls = await run({ _runtime_session_hint: 'conv-42' });
+    expect(calls[0].runtime_session_hint).toBe('conv-42');
+  });
+
+  it('omits runtime_session_hint when not injected', async () => {
+    const calls = await run({});
+    expect('runtime_session_hint' in calls[0]).toBe(false);
+  });
+
+  it('does not leak the statefulSessions factory flag onto the wire', async () => {
+    const calls = await run({}, { statefulSessions: true });
+    expect('statefulSessions' in calls[0]).toBe(false);
+  });
+
+  it('strips a model-supplied runtime_session_hint from the raw args', async () => {
+    const codeTool = createCodeExecutionTool({});
+    await codeTool.invoke(
+      { lang: 'py', code: 'print(1)', runtime_session_hint: 'model-picked' },
+      { toolCall: {} } as unknown as RunnableConfig
+    );
+    expect('runtime_session_hint' in fetchCalls[0]).toBe(false);
+  });
+
+  it('lets only the ToolNode-injected hint reach the wire, ignoring model args', async () => {
+    const codeTool = createCodeExecutionTool({});
+    await codeTool.invoke(
+      { lang: 'py', code: 'print(1)', runtime_session_hint: 'model-picked' },
+      {
+        toolCall: { _runtime_session_hint: 'host-conv' },
+      } as unknown as RunnableConfig
+    );
+    expect(fetchCalls[0].runtime_session_hint).toBe('host-conv');
+  });
+});

package/src/tools/__tests__/ToolNode.session.test.ts

@@ -1263,4 +1263,90 @@ describe('ToolNode code execution session management', () => {
       );
     });
   });
+
+  describe('stateful runtime session hint injection', () => {
+    it('injects the explicit runtimeSessionHint when statefulSessions is on', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: {
+            statefulSessions: true,
+            runtimeSessionHint: 'conv-explicit',
+          },
+        },
+      });
+
+      await toolNode.invoke({ messages: [createAIMessageWithCodeCall('c1')] });
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('conv-explicit');
+    });
+
+    it('falls back to configurable.thread_id when no explicit hint is given', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: true },
+        },
+      });
+
+      await toolNode.invoke(
+        { messages: [createAIMessageWithCodeCall('c1')] },
+        { configurable: { thread_id: 'thread-abc' } }
+      );
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('thread-abc');
+    });
+
+    it('does not inject a hint when statefulSessions is off', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: false },
+        },
+      });
+
+      await toolNode.invoke(
+        { messages: [createAIMessageWithCodeCall('c1')] },
+        { configurable: { thread_id: 'thread-abc' } }
+      );
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBeUndefined();
+    });
+
+    it('injects the hint independently of an existing exec session', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: 'exec-1',
+        files: [],
+        lastUpdated: 0,
+      });
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions,
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: true, runtimeSessionHint: 'conv-1' },
+        },
+      });
+
+      await toolNode.invoke({ messages: [createAIMessageWithCodeCall('c1')] });
+
+      expect(capturedConfigs[0].session_id).toBe('exec-1');
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('conv-1');
+    });
+  });
 });

package/src/tools/__tests__/eagerEventExecution.session.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from '@jest/globals';
+import type * as t from '@/types';
+import {
+  buildToolExecutionRequestPlan,
+  resolveRuntimeSessionHint,
+} from '../eagerEventExecution';
+
+describe('buildToolExecutionRequestPlan — runtimeSessionHint', () => {
+  const usageCount = () => new Map<string, number>();
+
+  it('carries runtimeSessionHint onto the built ToolCallRequest', () => {
+    const plan = buildToolExecutionRequestPlan({
+      toolCalls: [
+        {
+          id: 'call_1',
+          name: 'execute_code',
+          args: { lang: 'py', code: 'print(1)' },
+          runtimeSessionHint: 'conv-42',
+        },
+      ],
+      usageCount: usageCount(),
+    });
+    expect(plan?.requests[0].runtimeSessionHint).toBe('conv-42');
+  });
+
+  it('omits the field entirely when the hint is absent or empty', () => {
+    const plan = buildToolExecutionRequestPlan({
+      toolCalls: [{ id: 'c1', name: 'execute_code', args: {} }],
+      usageCount: usageCount(),
+    });
+    expect('runtimeSessionHint' in (plan?.requests[0] as object)).toBe(false);
+
+    const empty = buildToolExecutionRequestPlan({
+      toolCalls: [
+        { id: 'c2', name: 'execute_code', args: {}, runtimeSessionHint: '' },
+      ],
+      usageCount: usageCount(),
+    });
+    expect('runtimeSessionHint' in (empty?.requests[0] as object)).toBe(false);
+  });
+
+  it('carries the hint onto invalid-arg (rejected) requests too', () => {
+    const plan = buildToolExecutionRequestPlan({
+      toolCalls: [
+        {
+          id: 'c1',
+          name: 'execute_code',
+          args: 'not-an-object',
+          runtimeSessionHint: 'conv-9',
+        },
+      ],
+      usageCount: usageCount(),
+      invalidArgsBehavior: 'error-result',
+    });
+    expect(plan?.allRequests[0].runtimeSessionHint).toBe('conv-9');
+    expect(plan?.rejectedResults).toHaveLength(1);
+  });
+});
+
+describe('resolveRuntimeSessionHint', () => {
+  const sandbox = (
+    o: Partial<t.SandboxExecutionConfig>
+  ): t.ToolExecutionConfig => ({
+    sandbox: o,
+  });
+
+  it('returns undefined unless statefulSessions is on', () => {
+    expect(resolveRuntimeSessionHint(undefined, 'thread-1')).toBeUndefined();
+    expect(resolveRuntimeSessionHint(sandbox({}), 'thread-1')).toBeUndefined();
+    expect(
+      resolveRuntimeSessionHint(
+        sandbox({ statefulSessions: false }),
+        'thread-1'
+      )
+    ).toBeUndefined();
+  });
+
+  it('prefers an explicit hint, else falls back to thread_id', () => {
+    expect(
+      resolveRuntimeSessionHint(
+        sandbox({ statefulSessions: true, runtimeSessionHint: 'explicit' }),
+        'thread-1'
+      )
+    ).toBe('explicit');
+    expect(
+      resolveRuntimeSessionHint(sandbox({ statefulSessions: true }), 'thread-1')
+    ).toBe('thread-1');
+    expect(
+      resolveRuntimeSessionHint(sandbox({ statefulSessions: true }), '')
+    ).toBeUndefined();
+  });
+});