@librechat/agents 3.2.55 → 3.2.57

package/dist/types/graphs/Graph.d.ts

@@ -81,6 +81,7 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
      * consumes the settled promises while preserving final ToolMessage order.
      */
     eagerEventToolExecution: t.EagerEventToolExecutionConfig | undefined;
+    codeSessionToolNames: string[] | undefined;
     eagerEventToolExecutions: Map<string, t.EagerEventToolExecution>;
     eagerEventToolUsageCount: Map<string, number>;
     private eagerEventToolUsageCountsByAgentId;

package/dist/types/run.d.ts

@@ -13,6 +13,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private langfuse?;
     private toolOutputReferences?;
     private eagerEventToolExecution?;
+    private codeSessionToolNames?;
     private toolExecution?;
     private subagentUsageSink?;
     private indexTokenCountMap?;

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

@@ -91,6 +91,8 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private eventDrivenMode;
     /** Opt-in stream-layer prestart config for event-driven tools. */
     private eagerEventToolExecution?;
+    /** Host tools that write to the code sandbox and share its exec session. */
+    private codeSessionToolNames?;
     /** Shared per-run prestarted tool registry populated by ChatModelStreamHandler. */
     private eagerEventToolExecutions?;
     /** Shared per-run per-tool turn counter used by eager and normal event dispatch. */
@@ -145,7 +147,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, executingAgentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, }: t.ToolNodeConstructorParams);
+    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, executingAgentId, directToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     /**
      * Returns the run-scoped tool output registry, or `undefined` when
@@ -304,6 +306,14 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * Extracts code execution session context from tool results and stores in Graph.sessions.
      * Mirrors the session storage logic in handleRunToolCompletions for direct execution.
      */
+    /**
+     * True when a tool's successful result should fold its returned exec
+     * `session_id` into the shared code session: built-in `CODE_EXECUTION_TOOLS`,
+     * plus host-declared sandbox-writing tools (`codeSessionToolNames`, e.g.
+     * create_file/edit_file). Kept name-scoped rather than a blanket artifact
+     * opt-in so only host-declared tools can influence the shared session.
+     */
+    private participatesInCodeSession;
     private storeCodeSessionFromResults;
     /**
      * Post-processes standard runTool outputs: dispatches ON_RUN_STEP_COMPLETED

package/dist/types/types/run.d.ts

@@ -170,6 +170,15 @@ export type RunConfig = {
      * eager dispatch unsafe.
      */
     eagerEventToolExecution?: EagerEventToolExecutionConfig;
+    /**
+     * Names of host tools that write to the code-execution sandbox but are not
+     * built-in `CODE_EXECUTION_TOOLS` (e.g. LibreChat's create_file/edit_file).
+     * Their successful results fold the returned exec `session_id` into the
+     * shared code session, so a file such a tool writes is visible to later
+     * bash_tool/execute_code calls running in the same sandbox. Host-declared so
+     * the SDK stays name-agnostic.
+     */
+    codeSessionToolNames?: string[];
     /**
      * Selects the execution backend for built-in code tools. Omit this to keep
      * the remote LibreChat Code API sandbox. Set `{ engine: 'local' }` to run

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

@@ -31,6 +31,16 @@ export type EagerEventToolExecutionConfig = {
      * ToolMessages so provider message ordering is preserved.
      */
     enabled?: boolean;
+    /**
+     * Tool names that must never be started eagerly. Eager execution
+     * speculates on tool args before the model turn commits, so
+     * side-effecting tools (e.g. file writes) should opt out: a
+     * speculative write can land even if the turn is superseded, and a
+     * later arg revision would otherwise trip the "changed after eager
+     * execution" guard. Excluded calls fall through to normal ToolNode
+     * execution with final args.
+     */
+    excludeToolNames?: string[];
 };
 export type EagerEventToolExecutionOutcome = {
     results: ToolExecuteResult[];
@@ -90,6 +100,12 @@ export type ToolNodeOptions = {
     directToolNames?: Set<string>;
     /** Opt-in eager execution for event-driven tool calls. */
     eagerEventToolExecution?: EagerEventToolExecutionConfig;
+    /**
+     * Host tool names that write to the code-execution sandbox but are not
+     * built-in `CODE_EXECUTION_TOOLS`. Their exec `session_id` is folded into the
+     * shared code session so later bash_tool/execute_code calls see written files.
+     */
+    codeSessionToolNames?: string[];
     /** Shared per-run eager execution registry populated by the stream handler. */
     eagerEventToolExecutions?: Map<string, EagerEventToolExecution>;
     /** Shared per-run per-tool turn counter used by eager and normal event dispatch. */

package/package.json

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

package/src/__tests__/stream.eagerEventExecution.test.ts

@@ -4726,4 +4726,148 @@ describe('ChatModelStreamHandler eager event tool execution', () => {
     expect(toolExecuteCalls).toHaveLength(0);
     expect(graph.eagerEventToolExecutions.size).toBe(0);
   });
+
+  it('does not prestart tools listed in excludeToolNames', async () => {
+    const graph = createGraph({
+      eagerEventToolExecution: {
+        enabled: true,
+        excludeToolNames: ['create_file'],
+      },
+    });
+    const toolExecuteCalls: t.ToolExecuteBatchRequest[] = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        const batch = data as t.ToolExecuteBatchRequest;
+        toolExecuteCalls.push(batch);
+        batch.resolve([
+          { toolCallId: 'call_file', status: 'success', content: 'ok' },
+        ]);
+      });
+
+    await new ChatModelStreamHandler().handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_calls: [
+            {
+              id: 'call_file',
+              name: 'create_file',
+              args: { path: '/mnt/data/x.py', content: 'print(1)' },
+            },
+          ],
+          response_metadata: finalToolCallResponseMetadata,
+        } as unknown as t.StreamChunk,
+      },
+      { langgraph_node: 'agent' },
+      graph
+    );
+
+    // Excluded: no eager execution started; the call falls through to ToolNode.
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(graph.eagerEventToolExecutions.has('call_file')).toBe(false);
+  });
+
+  it('does not prestart codeSessionToolNames tools even without excludeToolNames', async () => {
+    // A declared session-writing host tool is side-effecting, so it must not be
+    // eagerly prestarted even when the host didn't also list it in excludeToolNames.
+    const graph = createGraph({
+      eagerEventToolExecution: { enabled: true },
+      codeSessionToolNames: ['create_file', 'edit_file'],
+    });
+    const toolExecuteCalls: t.ToolExecuteBatchRequest[] = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        const batch = data as t.ToolExecuteBatchRequest;
+        toolExecuteCalls.push(batch);
+        batch.resolve([
+          { toolCallId: 'call_cf2', status: 'success', content: 'ok' },
+        ]);
+      });
+
+    await new ChatModelStreamHandler().handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_calls: [
+            {
+              id: 'call_cf2',
+              name: 'create_file',
+              args: { path: '/mnt/data/y.py', content: 'print(2)' },
+            },
+          ],
+          response_metadata: finalToolCallResponseMetadata,
+        } as unknown as t.StreamChunk,
+      },
+      { langgraph_node: 'agent' },
+      graph
+    );
+
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(graph.eagerEventToolExecutions.has('call_cf2')).toBe(false);
+  });
+
+  it('keeps the direct-tool batch guard when an excluded tool is also direct', async () => {
+    // edit_file is both a direct graph tool AND excluded from eager. A mixed
+    // batch with a direct tool must suppress eager for the whole batch, so the
+    // sibling event tool must NOT prestart — excluding edit_file must not hide
+    // it from the batch-level direct-tool guard.
+    const graph = createGraph({
+      eagerEventToolExecution: {
+        enabled: true,
+        excludeToolNames: ['edit_file'],
+      },
+      getAgentContext: jest.fn(() => ({
+        provider: Providers.ANTHROPIC,
+        reasoningKey: 'reasoning',
+        toolDefinitions: [{ name: 'weather' }, { name: 'edit_file' }],
+        graphTools: [{ name: 'edit_file' }],
+        agentId: 'agent_1',
+      })) as unknown as StandardGraph['getAgentContext'],
+    });
+    const toolExecuteCalls: t.ToolExecuteBatchRequest[] = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        toolExecuteCalls.push(data as t.ToolExecuteBatchRequest);
+        (data as t.ToolExecuteBatchRequest).resolve([]);
+      });
+
+    await new ChatModelStreamHandler().handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_calls: [
+            { id: 'call_weather', name: 'weather', args: { city: 'NYC' } },
+            {
+              id: 'call_edit',
+              name: 'edit_file',
+              args: { path: '/mnt/data/x.py' },
+            },
+          ],
+          response_metadata: finalToolCallResponseMetadata,
+        } as unknown as t.StreamChunk,
+      },
+      { langgraph_node: 'agent' },
+      graph
+    );
+
+    // Direct tool in batch suppresses eager for the whole batch.
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(graph.eagerEventToolExecutions.has('call_weather')).toBe(false);
+    expect(graph.eagerEventToolExecutions.has('call_edit')).toBe(false);
+  });
 });

package/src/graphs/Graph.ts

@@ -66,8 +66,8 @@ import {
   type CallbackEntry,
 } from '@/utils/callbacks';
 import { partitionAndMarkOpenRouterToolCache } from '@/llm/openrouter/toolCache';
-import { shouldTraceToolNodeForLangfuse } from '@/langfuseToolOutputTracing';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
+import { shouldTraceToolNodeForLangfuse } from '@/langfuseToolOutputTracing';
 import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
 import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
 import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
@@ -608,6 +608,7 @@ export abstract class Graph<
    * consumes the settled promises while preserving final ToolMessage order.
    */
   eagerEventToolExecution: t.EagerEventToolExecutionConfig | undefined;
+  codeSessionToolNames: string[] | undefined;
   eagerEventToolExecutions: Map<string, t.EagerEventToolExecution> = new Map();
   eagerEventToolUsageCount: Map<string, number> = new Map();
   private eagerEventToolUsageCountsByAgentId: Map<string, Map<string, number>> =
@@ -656,6 +657,7 @@ export abstract class Graph<
     this.humanInTheLoop = undefined;
     this.toolOutputReferences = undefined;
     this.eagerEventToolExecution = undefined;
+    this.codeSessionToolNames = undefined;
     this.eagerEventToolExecutions.clear();
     this.clearEagerEventToolUsageCounts();
     this.eagerEventToolCallChunks.clear();
@@ -1260,6 +1262,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         hookRegistry: this.hookRegistry,
         humanInTheLoop: this.humanInTheLoop,
         eagerEventToolExecution: this.eagerEventToolExecution,
+        codeSessionToolNames: this.codeSessionToolNames,
         eagerEventToolExecutions: this.eagerEventToolExecutions,
         eagerEventToolUsageCount: this.getEagerEventToolUsageCount(
           agentContext?.agentId
@@ -1309,6 +1312,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       toolRegistry: agentContext?.toolRegistry,
       sessions: this.sessions,
       toolExecution: this.toolExecution,
+      codeSessionToolNames: this.codeSessionToolNames,
       hookRegistry: this.hookRegistry,
       humanInTheLoop: this.humanInTheLoop,
       maxContextTokens: agentContext?.maxContextTokens,
@@ -2333,6 +2337,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
              */
             childGraph.toolOutputReferences = this.toolOutputReferences;
             childGraph.eagerEventToolExecution = this.eagerEventToolExecution;
+            childGraph.codeSessionToolNames = this.codeSessionToolNames;
             childGraph.toolExecution = this.toolExecution;
             childGraph.eventToolExecutionAvailable =
               this.handlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) !=

package/src/run.ts

@@ -127,6 +127,7 @@ export class Run<_T extends t.BaseGraphState> {
   private langfuse?: t.LangfuseConfig;
   private toolOutputReferences?: t.ToolOutputReferencesConfig;
   private eagerEventToolExecution?: t.EagerEventToolExecutionConfig;
+  private codeSessionToolNames?: string[];
   private toolExecution?: t.ToolExecutionConfig;
   private subagentUsageSink?: t.SubagentUsageSink;
   private indexTokenCountMap?: Record<string, number>;
@@ -182,6 +183,7 @@ export class Run<_T extends t.BaseGraphState> {
     this.langfuse = config.langfuse;
     this.toolOutputReferences = config.toolOutputReferences;
     this.eagerEventToolExecution = config.eagerEventToolExecution;
+    this.codeSessionToolNames = config.codeSessionToolNames;
     this.toolExecution = config.toolExecution;
     this.subagentUsageSink = config.subagentUsageSink;
 
@@ -268,6 +270,7 @@ export class Run<_T extends t.BaseGraphState> {
     standardGraph.humanInTheLoop = this.humanInTheLoop;
     standardGraph.toolOutputReferences = this.toolOutputReferences;
     standardGraph.eagerEventToolExecution = this.eagerEventToolExecution;
+    standardGraph.codeSessionToolNames = this.codeSessionToolNames;
     standardGraph.toolExecution = this.toolExecution;
     this.Graph = standardGraph;
     return standardGraph.createWorkflow();
@@ -297,6 +300,7 @@ export class Run<_T extends t.BaseGraphState> {
     multiAgentGraph.humanInTheLoop = this.humanInTheLoop;
     multiAgentGraph.toolOutputReferences = this.toolOutputReferences;
     multiAgentGraph.eagerEventToolExecution = this.eagerEventToolExecution;
+    multiAgentGraph.codeSessionToolNames = this.codeSessionToolNames;
     multiAgentGraph.toolExecution = this.toolExecution;
     this.Graph = multiAgentGraph;
     return multiAgentGraph.createWorkflow();

package/src/stream.ts

@@ -127,6 +127,24 @@ function hasToolOutputReference(value: unknown): boolean {
   return false;
 }
 
+function isEagerExecutionExcludedTool(
+  name: string,
+  graph: StandardGraph
+): boolean {
+  if (name === '') {
+    return false;
+  }
+  const excluded = graph.eagerEventToolExecution?.excludeToolNames;
+  if (excluded != null && excluded.includes(name)) {
+    return true;
+  }
+  // A code-session participant writes to the shared sandbox, so it is
+  // side-effecting: never prestart it speculatively (a revised/superseded turn
+  // would leave the write applied). Implies exclusion without the host having
+  // to also list the name in excludeToolNames.
+  return graph.codeSessionToolNames?.includes(name) === true;
+}
+
 function isDirectGraphTool(
   name: string,
   agentContext: AgentContext | undefined
@@ -184,7 +202,8 @@ function getCodeSessionContext(
   if (
     !CODE_EXECUTION_TOOLS.has(name) &&
     name !== Constants.SKILL_TOOL &&
-    name !== Constants.READ_FILE
+    name !== Constants.READ_FILE &&
+    graph.codeSessionToolNames?.includes(name) !== true
   ) {
     return undefined;
   }
@@ -615,7 +634,7 @@ function createEagerToolExecutionPlan(args: {
     return undefined;
   }
 
-  const candidateToolCalls = skipExisting
+  const unstartedToolCalls = skipExisting
     ? toolCalls.filter((toolCall) => {
       if (toolCall.id == null || toolCall.id === '') {
         return true;
@@ -623,6 +642,13 @@ function createEagerToolExecutionPlan(args: {
       return !graph.eagerEventToolExecutions.has(toolCall.id);
     })
     : toolCalls;
+  // Drop host-excluded tools only AFTER the batch-level guards above have run
+  // against the full batch, so excluding a call never hides a sibling direct
+  // tool from `hasDirectToolCallInBatch`. Excluded calls fall through to normal
+  // ToolNode execution; siblings may still eager-execute.
+  const candidateToolCalls = unstartedToolCalls.filter(
+    (toolCall) => !isEagerExecutionExcludedTool(toolCall.name, graph)
+  );
   if (candidateToolCalls.length === 0) {
     return [];
   }

package/src/tools/ToolNode.ts

@@ -439,6 +439,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private eventDrivenMode: boolean = false;
   /** Opt-in stream-layer prestart config for event-driven tools. */
   private eagerEventToolExecution?: t.EagerEventToolExecutionConfig;
+  /** Host tools that write to the code sandbox and share its exec session. */
+  private codeSessionToolNames?: ReadonlySet<string>;
   /** Shared per-run prestarted tool registry populated by ChatModelStreamHandler. */
   private eagerEventToolExecutions?: Map<string, t.EagerEventToolExecution>;
   /** Shared per-run per-tool turn counter used by eager and normal event dispatch. */
@@ -515,6 +517,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     agentId,
     executingAgentId,
     directToolNames,
+    codeSessionToolNames,
     maxContextTokens,
     maxToolResultChars,
     hookRegistry,
@@ -552,6 +555,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     // existing agentId option) still get attribution without knowing the new option.
     this.executingAgentId = executingAgentId ?? agentId;
     this.directToolNames = directToolNames;
+    this.codeSessionToolNames =
+      codeSessionToolNames != null && codeSessionToolNames.length > 0
+        ? new Set(codeSessionToolNames)
+        : undefined;
     this.maxToolResultChars =
       maxToolResultChars ?? calculateMaxToolResultChars(maxContextTokens);
     this.hookRegistry = hookRegistry;
@@ -973,7 +980,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        * 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)) {
+      if (this.participatesInCodeSession(call.name)) {
         const codeSession = this.sessions?.get(Constants.EXECUTE_CODE) as
           | t.CodeSessionContext
           | undefined;
@@ -1759,6 +1766,23 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    * Extracts code execution session context from tool results and stores in Graph.sessions.
    * Mirrors the session storage logic in handleRunToolCompletions for direct execution.
    */
+  /**
+   * True when a tool's successful result should fold its returned exec
+   * `session_id` into the shared code session: built-in `CODE_EXECUTION_TOOLS`,
+   * plus host-declared sandbox-writing tools (`codeSessionToolNames`, e.g.
+   * create_file/edit_file). Kept name-scoped rather than a blanket artifact
+   * opt-in so only host-declared tools can influence the shared session.
+   */
+  private participatesInCodeSession(name: string): boolean {
+    if (name === '') {
+      return false;
+    }
+    return (
+      CODE_EXECUTION_TOOLS.has(name) ||
+      this.codeSessionToolNames?.has(name) === true
+    );
+  }
+
   private storeCodeSessionFromResults(
     results: t.ToolExecuteResult[],
     requestMap: Map<string, t.ToolCallRequest>
@@ -1777,7 +1801,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       if (
         request?.name == null ||
         request.name === '' ||
-        (!CODE_EXECUTION_TOOLS.has(request.name) &&
+        (!this.participatesInCodeSession(request.name) &&
           request.name !== Constants.SKILL_TOOL)
       ) {
         continue;
@@ -1830,7 +1854,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         continue;
       }
 
-      if (this.sessions && CODE_EXECUTION_TOOLS.has(call.name)) {
+      if (this.sessions && this.participatesInCodeSession(call.name)) {
         const artifact = toolMessage.artifact as
           | t.CodeExecutionArtifact
           | undefined;
@@ -2463,7 +2487,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       const plan = buildToolExecutionRequestPlan({
         toolCalls: approvedEntries.map((entry) => {
           const codeSessionContext =
-            CODE_EXECUTION_TOOLS.has(entry.call.name) ||
+            this.participatesInCodeSession(entry.call.name) ||
             entry.call.name === Constants.SKILL_TOOL ||
             entry.call.name === Constants.READ_FILE
               ? this.getCodeSessionContext()

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

@@ -140,6 +140,52 @@ describe('ToolNode code execution session management', () => {
       expect(capturedConfigs[0]._injected_files).toBeUndefined();
     });
 
+    it('injects the existing session into declared host tools on the direct path', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: 'host-session',
+        files: [
+          { id: 'g1', name: 'gen.png', storage_session_id: 'host-session' },
+        ],
+        lastUpdated: Date.now(),
+      } satisfies t.CodeSessionContext);
+
+      const cfTool = tool(
+        async (_input, config) => {
+          capturedConfigs.push({ ...(config.toolCall ?? {}) });
+          return 'Created /mnt/data/x.py';
+        },
+        {
+          name: 'create_file',
+          description: 'write a file',
+          schema: z.object({ path: z.string(), content: z.string() }),
+        }
+      ) as unknown as StructuredToolInterface;
+
+      const toolNode = new ToolNode({
+        tools: [cfTool],
+        sessions,
+        codeSessionToolNames: ['create_file', 'edit_file'],
+      });
+
+      const aiMsg = new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_cf',
+            name: 'create_file',
+            args: { path: '/mnt/data/x.py', content: 'print(1)' },
+          },
+        ],
+      });
+      await toolNode.invoke({ messages: [aiMsg] });
+
+      // Declared host tool writes into the current sandbox, not a fresh one.
+      expect(capturedConfigs).toHaveLength(1);
+      expect(capturedConfigs[0].session_id).toBe('host-session');
+    });
+
     it('preserves per-file storage_session_id for multi-session files', async () => {
       const capturedConfigs: Record<string, unknown>[] = [];
       const sessions: t.ToolSessionMap = new Map();
@@ -774,6 +820,78 @@ describe('ToolNode code execution session management', () => {
       expect(sessions.has(Constants.EXECUTE_CODE)).toBe(false);
     });
 
+    it('stores the exec session for host tools declared in codeSessionToolNames', () => {
+      const sessions: t.ToolSessionMap = new Map();
+      const toolNode = new ToolNode({
+        tools: [createMockCodeTool({ capturedConfigs: [] })],
+        sessions,
+        eventDrivenMode: true,
+        codeSessionToolNames: ['create_file', 'edit_file'],
+      });
+
+      const storeMethod = (
+        toolNode as unknown as {
+          storeCodeSessionFromResults: (
+            results: t.ToolExecuteResult[],
+            requestMap: Map<string, t.ToolCallRequest>
+          ) => void;
+        }
+      ).storeCodeSessionFromResults.bind(toolNode);
+
+      storeMethod(
+        [
+          {
+            toolCallId: 'tc-cf',
+            content: 'Created /mnt/data/x.py (10 chars).',
+            artifact: { session_id: 'authoring-session' },
+            status: 'success',
+          },
+        ],
+        new Map([['tc-cf', { id: 'tc-cf', name: 'create_file', args: {} }]])
+      );
+
+      // create_file's exec session is folded into the shared code session, so a
+      // later bash_tool/execute_code call reuses the same sandbox.
+      const stored = sessions.get(Constants.EXECUTE_CODE) as
+        | t.CodeSessionContext
+        | undefined;
+      expect(stored?.session_id).toBe('authoring-session');
+    });
+
+    it('does not store a host authoring tool session when not declared', () => {
+      const sessions: t.ToolSessionMap = new Map();
+      const toolNode = new ToolNode({
+        tools: [createMockCodeTool({ capturedConfigs: [] })],
+        sessions,
+        eventDrivenMode: true,
+        // codeSessionToolNames omitted — create_file must NOT be treated as a
+        // code-session participant.
+      });
+
+      const storeMethod = (
+        toolNode as unknown as {
+          storeCodeSessionFromResults: (
+            results: t.ToolExecuteResult[],
+            requestMap: Map<string, t.ToolCallRequest>
+          ) => void;
+        }
+      ).storeCodeSessionFromResults.bind(toolNode);
+
+      storeMethod(
+        [
+          {
+            toolCallId: 'tc-cf2',
+            content: 'Created /mnt/data/x.py (10 chars).',
+            artifact: { session_id: 'authoring-session' },
+            status: 'success',
+          },
+        ],
+        new Map([['tc-cf2', { id: 'tc-cf2', name: 'create_file', args: {} }]])
+      );
+
+      expect(sessions.has(Constants.EXECUTE_CODE)).toBe(false);
+    });
+
     it('ignores error results', () => {
       const sessions: t.ToolSessionMap = new Map();
 
@@ -1102,5 +1220,47 @@ describe('ToolNode code execution session management', () => {
       expect(capturedRequests[0].name).toBe('web_search');
       expect(capturedRequests[0].codeSessionContext).toBeUndefined();
     });
+
+    it('attaches codeSessionContext to declared host tools so they write into the current sandbox', async () => {
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: 'cf-session',
+        files: [
+          { id: 'g1', name: 'gen.png', storage_session_id: 'cf-session' },
+        ],
+        lastUpdated: Date.now(),
+      } satisfies t.CodeSessionContext);
+
+      const { capturedRequests } = captureBatchRequests();
+
+      const toolNode = new ToolNode({
+        tools: [createDummyTool('create_file')],
+        sessions,
+        eventDrivenMode: true,
+        codeSessionToolNames: ['create_file', 'edit_file'],
+        toolCallStepIds: new Map([['call_cf', 'step_cf']]),
+      });
+
+      const aiMsg = new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_cf',
+            name: 'create_file',
+            args: { path: '/mnt/data/x.py', content: 'print(1)' },
+          },
+        ],
+      });
+
+      await toolNode.invoke({ messages: [aiMsg] });
+
+      expect(capturedRequests).toHaveLength(1);
+      expect(capturedRequests[0].name).toBe('create_file');
+      // Existing session is injected so create_file writes into the current
+      // sandbox instead of spawning a separate one.
+      expect(capturedRequests[0].codeSessionContext?.session_id).toBe(
+        'cf-session'
+      );
+    });
   });
 });

package/src/types/run.ts

@@ -184,6 +184,15 @@ export type RunConfig = {
    * eager dispatch unsafe.
    */
   eagerEventToolExecution?: EagerEventToolExecutionConfig;
+  /**
+   * Names of host tools that write to the code-execution sandbox but are not
+   * built-in `CODE_EXECUTION_TOOLS` (e.g. LibreChat's create_file/edit_file).
+   * Their successful results fold the returned exec `session_id` into the
+   * shared code session, so a file such a tool writes is visible to later
+   * bash_tool/execute_code calls running in the same sandbox. Host-declared so
+   * the SDK stays name-agnostic.
+   */
+  codeSessionToolNames?: string[];
   /**
    * Selects the execution backend for built-in code tools. Omit this to keep
    * the remote LibreChat Code API sandbox. Set `{ engine: 'local' }` to run