@librechat/agents 3.5.1 → 3.6.1

package/src/tools/BashProgrammaticToolCalling.ts

@@ -8,8 +8,10 @@ import {
   CODE_ARTIFACT_PATH_GUIDANCE,
   appendFailedExecutionFileReminder,
   buildCodeApiExecutionErrorMessage,
+  buildCodeApiEndpoint,
   CodeApiRequestError,
   getCodeBaseURL,
+  selectRuntimeSessionHint,
 } from './CodeExecutor';
 import {
   clampCodeApiRunTimeoutMs,
@@ -296,7 +298,7 @@ export function createBashProgrammaticToolCallingTool(
   const maxRunTimeoutMs = resolveCodeApiRunTimeoutMs(initParams.runTimeoutMs);
   const proxy = initParams.proxy ?? process.env.PROXY;
   const debug = initParams.debug ?? process.env.BASH_PTC_DEBUG === 'true';
-  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
+  const EXEC_ENDPOINT = buildCodeApiEndpoint(baseUrl, 'exec/programmatic');
 
   return tool(
     async (rawParams, config) => {
@@ -362,13 +364,19 @@ export function createBashProgrammaticToolCallingTool(
           );
         }
 
-        /* Stateful sessions: hint on the INITIAL request only (continuations
-         * bind via continuation_token). Wire-only in v1 — BashPTC keeps its
-         * stateless prompt. */
+        /* The hint rides the INITIAL request only; continuation_token binds
+         * later round-trips. Prefer trusted per-agent factory context over
+         * legacy ToolNode injection. Explicit default profiles always drop it.
+         * BashPTC keeps its stateless runtime prompt in v1. */
+        const selectedRuntimeSessionHint = selectRuntimeSessionHint(
+          initParams.runtimeSessionHint,
+          _runtime_session_hint
+        );
         const runtimeSessionHint =
-          typeof _runtime_session_hint === 'string' &&
-          _runtime_session_hint !== ''
-            ? _runtime_session_hint
+          initParams.executionProfile !== 'default' &&
+          typeof selectedRuntimeSessionHint === 'string' &&
+          selectedRuntimeSessionHint !== ''
+            ? selectedRuntimeSessionHint
             : undefined;
 
         let response = await makeRequest(
@@ -385,7 +393,8 @@ export function createBashProgrammaticToolCallingTool(
               : {}),
           },
           proxy,
-          initParams.authHeaders
+          initParams.authHeaders,
+          initParams.executionProfile
         );
 
         // ====================================================================
@@ -425,7 +434,8 @@ export function createBashProgrammaticToolCallingTool(
               tool_results: toolResults,
             },
             proxy,
-            initParams.authHeaders
+            initParams.authHeaders,
+            initParams.executionProfile
           );
         }
 

package/src/tools/CodeExecutor.ts

@@ -19,6 +19,17 @@ export const getCodeBaseURL = (): string =>
   getEnvironmentVariable(EnvVar.CODE_BASEURL) ??
   Constants.OFFICIAL_CODE_BASEURL;
 
+export function buildCodeApiEndpoint(baseUrl: string, route: string): string {
+  return `${baseUrl.replace(/\/+$/, '')}/${route.replace(/^\/+/, '')}`;
+}
+
+export function selectRuntimeSessionHint(
+  factoryHint?: string,
+  injectedHint?: string
+): string | undefined {
+  return factoryHint != null && factoryHint !== '' ? factoryHint : injectedHint;
+}
+
 export const emptyOutputMessage =
   'stdout: Empty. Ensure you\'re writing output explicitly.\n';
 
@@ -108,8 +119,8 @@ export const CodeExecutionToolSchema = {
   required: ['lang', 'code'],
 } as const;
 
-const baseEndpoint = getCodeBaseURL();
-const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
+export const CODE_API_EXPECTED_PROFILE_HEADER =
+  'X-CodeAPI-Expected-Profile';
 
 type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
 
@@ -226,6 +237,19 @@ export async function resolveCodeApiAuthHeaders(
   return authHeaders;
 }
 
+export function addCodeApiExecutionProfileHeader(
+  headers: t.CodeApiAuthHeaderMap,
+  executionProfile?: t.CodeApiExecutionProfile
+): t.CodeApiAuthHeaderMap {
+  if (executionProfile == null) {
+    return headers;
+  }
+  return {
+    ...headers,
+    [CODE_API_EXPECTED_PROFILE_HEADER]: executionProfile,
+  };
+}
+
 export async function buildCodeApiHttpErrorMessage(
   _method: string,
   _endpoint: string,
@@ -333,16 +357,24 @@ export const CodeExecutionToolDefinition = {
 function createCodeExecutionTool(
   params: t.CodeExecutionToolParams | null = {}
 ): DynamicStructuredTool {
+  const execEndpoint = buildCodeApiEndpoint(
+    params?.baseUrl ?? getCodeBaseURL(),
+    'exec'
+  );
+
   return tool(
     async (rawInput, config) => {
-      /* `statefulSessions` is a prompt-only flag (drives the description);
-       * keep it out of the wire body. */
+      /* `statefulSessions` drives the description and gates trusted runtime
+       * affinity hints. Keep the flag itself out of the wire body. */
       const {
         authHeaders,
-        statefulSessions: _statefulSessions,
+        baseUrl: _baseUrl,
+        executionProfile,
+        runtimeSessionHint,
+        statefulSessions,
         ...executionParams
       } = params ?? {};
-      void _statefulSessions;
+      void _baseUrl;
       /* 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
@@ -383,14 +415,20 @@ 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. */
+      /* Stateful sessions: prefer the per-agent factory hint, falling back to
+       * legacy ToolNode injection. Explicit default-profile tools always drop
+       * the hint so a mixed graph cannot promote them to the stateful path. */
+      const effectiveRuntimeSessionHint = selectRuntimeSessionHint(
+        runtimeSessionHint,
+        _runtime_session_hint
+      );
       if (
-        typeof _runtime_session_hint === 'string' &&
-        _runtime_session_hint !== ''
+        statefulSessions === true &&
+        executionProfile !== 'default' &&
+        typeof effectiveRuntimeSessionHint === 'string' &&
+        effectiveRuntimeSessionHint !== ''
       ) {
-        postData.runtime_session_hint = _runtime_session_hint;
+        postData.runtime_session_hint = effectiveRuntimeSessionHint;
       }
 
       /* File injection: `_injected_files` from ToolNode (set when host
@@ -421,19 +459,22 @@ function createCodeExecutionTool(
           headers: {
             'Content-Type': 'application/json',
             'User-Agent': 'LibreChat/1.0',
-            ...resolvedAuthHeaders,
+            ...addCodeApiExecutionProfileHeader(
+              resolvedAuthHeaders,
+              executionProfile
+            ),
           },
           body: JSON.stringify(postData),
         };
 
-        const proxyAgent = resolveFetchProxyAgent(EXEC_ENDPOINT);
+        const proxyAgent = resolveFetchProxyAgent(execEndpoint);
         if (proxyAgent) {
           fetchOptions.agent = proxyAgent;
         }
-        const response = await fetch(EXEC_ENDPOINT, fetchOptions);
+        const response = await fetch(execEndpoint, fetchOptions);
         if (!response.ok) {
           throw new CodeApiRequestError(
-            await buildCodeApiHttpErrorMessage('POST', EXEC_ENDPOINT, response)
+            await buildCodeApiHttpErrorMessage('POST', execEndpoint, response)
           );
         }
 

package/src/tools/ProgrammaticToolCalling.ts

@@ -7,16 +7,19 @@ import type { ProgrammaticToolCallingJsonSchema } from './ptcTimeout';
 import type * as t from '@/types';
 import {
   CODE_ARTIFACT_PATH_GUIDANCE,
+  addCodeApiExecutionProfileHeader,
   appendCodeSessionFileSummary,
   appendFailedExecutionFileReminder,
   buildCodeApiExecutionErrorMessage,
   buildCodeApiHttpErrorMessage,
   CodeApiRequestError,
+  buildCodeApiEndpoint,
   emptyOutputMessage,
   getCodeBaseURL,
   appendTmpScratchReminder,
   normalizeCodeApiRequestError,
   resolveCodeApiAuthHeaders,
+  selectRuntimeSessionHint,
 } from './CodeExecutor';
 import {
   clampCodeApiRunTimeoutMs,
@@ -478,7 +481,8 @@ export async function makeRequest(
   endpoint: string,
   body: Record<string, unknown>,
   proxy?: string,
-  authHeaders?: t.CodeApiAuthHeaders
+  authHeaders?: t.CodeApiAuthHeaders,
+  executionProfile?: t.CodeApiExecutionProfile
 ): Promise<t.ProgrammaticExecutionResponse> {
   try {
     const resolvedAuthHeaders = await resolveCodeApiAuthHeaders(authHeaders);
@@ -487,7 +491,10 @@ export async function makeRequest(
       headers: {
         'Content-Type': 'application/json',
         'User-Agent': 'LibreChat/1.0',
-        ...resolvedAuthHeaders,
+        ...addCodeApiExecutionProfileHeader(
+          resolvedAuthHeaders,
+          executionProfile
+        ),
       },
       body: JSON.stringify(body),
     };
@@ -882,7 +889,7 @@ export function createProgrammaticToolCallingTool(
   const maxRunTimeoutMs = resolveCodeApiRunTimeoutMs(initParams.runTimeoutMs);
   const proxy = initParams.proxy ?? process.env.PROXY;
   const debug = initParams.debug ?? process.env.PTC_DEBUG === 'true';
-  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
+  const EXEC_ENDPOINT = buildCodeApiEndpoint(baseUrl, 'exec/programmatic');
 
   return tool(
     async (rawParams, config) => {
@@ -952,14 +959,19 @@ 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. */
+        /* The hint rides the INITIAL request only; continuation_token binds
+         * later round-trips. Prefer trusted per-agent factory context over
+         * legacy ToolNode injection. Explicit default profiles always drop it.
+         * PTC keeps its stateless runtime prompt in v1. */
+        const selectedRuntimeSessionHint = selectRuntimeSessionHint(
+          initParams.runtimeSessionHint,
+          _runtime_session_hint
+        );
         const runtimeSessionHint =
-          typeof _runtime_session_hint === 'string' &&
-          _runtime_session_hint !== ''
-            ? _runtime_session_hint
+          initParams.executionProfile !== 'default' &&
+          typeof selectedRuntimeSessionHint === 'string' &&
+          selectedRuntimeSessionHint !== ''
+            ? selectedRuntimeSessionHint
             : undefined;
 
         let response = await makeRequest(
@@ -975,7 +987,8 @@ export function createProgrammaticToolCallingTool(
               : {}),
           },
           proxy,
-          initParams.authHeaders
+          initParams.authHeaders,
+          initParams.executionProfile
         );
 
         // ====================================================================
@@ -1012,7 +1025,8 @@ export function createProgrammaticToolCallingTool(
               tool_results: toolResults,
             },
             proxy,
-            initParams.authHeaders
+            initParams.authHeaders,
+            initParams.executionProfile
           );
         }
 

package/src/tools/ToolNode.ts

@@ -62,6 +62,7 @@ import {
   SUBAGENT_PARENT_BATCH_CONFIG_KEY,
   SUBAGENT_REPLAY_CONTROLLER,
 } from '@/tools/subagent/SubagentReplay';
+import { attachRunStepResumeState } from '@/tools/runStepResume';
 import {
   INTENT_ARG,
   readOutcomeFields,
@@ -595,17 +596,18 @@ function fileIdentityKey(file: {
 
 function updateCodeSession(
   sessions: t.ToolSessionMap,
+  sessionKey: string,
   execSessionId: string,
   files: t.FileRefs | undefined
 ): void {
   const newFiles = files ?? [];
-  const existingSession = sessions.get(Constants.EXECUTE_CODE) as
+  const existingSession = sessions.get(sessionKey) as
     | t.CodeSessionContext
     | undefined;
   const existingFiles = existingSession?.files ?? [];
 
   if (newFiles.length === 0) {
-    sessions.set(Constants.EXECUTE_CODE, {
+    sessions.set(sessionKey, {
       session_id: execSessionId,
       files: existingFiles,
       lastUpdated: Date.now(),
@@ -643,7 +645,7 @@ function updateCodeSession(
     }
   }
 
-  sessions.set(Constants.EXECUTE_CODE, {
+  sessions.set(sessionKey, {
     session_id: execSessionId,
     files: [...filteredExisting, ...filesWithSession],
     lastUpdated: Date.now(),
@@ -694,6 +696,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private programmaticCache?: t.ProgrammaticCache;
   /** Reference to Graph's sessions map for automatic session injection */
   private sessions?: t.ToolSessionMap;
+  /** Partition within `sessions` owned by this agent's execution profile. */
+  private codeSessionKey: string;
   /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
   private eventDrivenMode: boolean = false;
   /** Opt-in stream-layer prestart config for event-driven tools. */
@@ -794,6 +798,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     loadRuntimeTools,
     toolRegistry,
     sessions,
+    codeSessionKey,
     eventDrivenMode,
     eagerEventToolExecution,
     eagerEventToolExecutions,
@@ -814,11 +819,45 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     fileCheckpointer,
     getBreakerSignal,
     getRunScope,
+    restoreRunStepResumeState,
+    createRunStepResumeState,
   }: t.ToolNodeConstructorParams) {
     super({
       name: name ?? TOOL_NODE_RUN_NAME,
       tags,
-      func: (input, config) => this.run(input, config),
+      func: async (input, config) => {
+        const state = input as T & Pick<t.BaseGraphState, 'runStepState'>;
+        restoreRunStepResumeState?.(state.runStepState, config);
+        let result: T;
+        try {
+          result = await this.run(input, config);
+        } catch (error) {
+          if (!isGraphInterrupt(error) || createRunStepResumeState == null) {
+            throw error;
+          }
+          const resumeState = createRunStepResumeState();
+          throw new GraphInterrupt(
+            error.interrupts.map((pendingInterrupt) => ({
+              ...pendingInterrupt,
+              value: attachRunStepResumeState(
+                pendingInterrupt.value,
+                resumeState
+              ),
+            }))
+          );
+        }
+        if (createRunStepResumeState == null) {
+          return result;
+        }
+        const runStepState = createRunStepResumeState();
+        if (Array.isArray(result)) {
+          return [...result, { runStepState }] as T;
+        }
+        return {
+          ...result,
+          runStepState,
+        };
+      },
     });
     this.trace = trace ?? this.trace;
     this.runLangfuse = runLangfuse;
@@ -834,6 +873,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       toolExecution,
     });
     this.sessions = sessions;
+    this.codeSessionKey = codeSessionKey ?? Constants.EXECUTE_CODE;
     this.eventDrivenMode = eventDrivenMode ?? false;
     this.eagerEventToolExecution = eagerEventToolExecution;
     this.eagerEventToolExecutions = eagerEventToolExecutions;
@@ -1328,7 +1368,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        * `/files/<session_id>` fallback was removed from the executors.
        */
       if (this.participatesInCodeSession(call.name)) {
-        const codeSession = this.sessions?.get(Constants.EXECUTE_CODE) as
+        const codeSession = this.sessions?.get(this.codeSessionKey) as
           | t.CodeSessionContext
           | undefined;
         const execSessionId = codeSession?.session_id;
@@ -2356,7 +2396,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       return undefined;
     }
 
-    const codeSession = this.sessions.get(Constants.EXECUTE_CODE) as
+    const codeSession = this.sessions.get(this.codeSessionKey) as
       | t.CodeSessionContext
       | undefined;
     if (!codeSession) {
@@ -2439,7 +2479,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         continue;
       }
 
-      updateCodeSession(this.sessions, execSessionId, artifact?.files);
+      updateCodeSession(
+        this.sessions,
+        this.codeSessionKey,
+        execSessionId,
+        artifact?.files
+      );
     }
   }
 
@@ -2502,7 +2547,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           | undefined;
         const execSessionId = artifact?.session_id;
         if (execSessionId != null && execSessionId !== '') {
-          updateCodeSession(this.sessions, execSessionId, artifact?.files);
+          updateCodeSession(
+            this.sessions,
+            this.codeSessionKey,
+            execSessionId,
+            artifact?.files
+          );
         }
       }
 

package/src/tools/ToolSearch.ts

@@ -25,7 +25,7 @@ import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
-import { getCodeBaseURL } from './CodeExecutor';
+import { buildCodeApiEndpoint, getCodeBaseURL } from './CodeExecutor';
 import { Constants } from '@/common';
 
 config();
@@ -914,7 +914,7 @@ function createToolSearch(
   const schema = createToolSearchSchema(mode);
 
   const baseEndpoint = initParams.baseUrl ?? getCodeBaseURL();
-  const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
+  const EXEC_ENDPOINT = buildCodeApiEndpoint(baseEndpoint, 'exec');
 
   const deferredToolsListing = getDeferredToolsListing(
     initParams.toolRegistry,

package/src/tools/runStepResume.ts

@@ -0,0 +1,121 @@
+import type { RunStepResumeEntry, RunStepResumeState } from '@/types';
+
+const RUN_STEP_RESUME_STATE_KEY = '__librechat_run_step_resume_state';
+const RUN_STEP_RESUME_PAYLOAD_KEY = '__librechat_run_step_resume_payload';
+const RUN_STEP_RESUME_WRAPPER_KEY = '__librechat_run_step_resume_wrapper';
+
+type RunStepResumePayload = {
+  [RUN_STEP_RESUME_STATE_KEY]: RunStepResumeState;
+  [RUN_STEP_RESUME_PAYLOAD_KEY]: unknown;
+  [RUN_STEP_RESUME_WRAPPER_KEY]: 1;
+};
+
+export function isRunStepResumeState(
+  value: unknown
+): value is RunStepResumeState {
+  if (value == null || typeof value !== 'object') {
+    return false;
+  }
+  const state = value as Partial<RunStepResumeState>;
+  if (
+    state.version !== 1 ||
+    !Number.isSafeInteger(state.revision) ||
+    (state.revision ?? -1) < 0 ||
+    !Number.isSafeInteger(state.nextIndex) ||
+    (state.nextIndex ?? -1) < 0 ||
+    !Array.isArray(state.toolCallSteps) ||
+    !Array.isArray(state.steps)
+  ) {
+    return false;
+  }
+  const toolCallSteps = new Map<string, string>();
+  for (const reference of state.toolCallSteps as unknown[]) {
+    if (reference == null || typeof reference !== 'object') {
+      return false;
+    }
+    const { toolCallId, stepId } = reference as {
+      toolCallId?: unknown;
+      stepId?: unknown;
+    };
+    if (
+      typeof toolCallId !== 'string' ||
+      toolCallId === '' ||
+      typeof stepId !== 'string' ||
+      stepId === '' ||
+      toolCallSteps.has(toolCallId)
+    ) {
+      return false;
+    }
+    toolCallSteps.set(toolCallId, stepId);
+  }
+  const stepIds = new Set<string>();
+  for (const value of state.steps as unknown[]) {
+    if (value == null || typeof value !== 'object') {
+      return false;
+    }
+    const entry = value as Partial<RunStepResumeEntry>;
+    const step = entry.step;
+    if (
+      step == null ||
+      typeof step.id !== 'string' ||
+      step.id === '' ||
+      !Number.isSafeInteger(step.index) ||
+      step.index < 0 ||
+      !Array.isArray(entry.pendingToolCallIds) ||
+      entry.pendingToolCallIds.some(
+        (toolCallId) => typeof toolCallId !== 'string' || toolCallId === ''
+      ) ||
+      (entry.latestCompletionAt != null &&
+        !Number.isFinite(entry.latestCompletionAt)) ||
+      typeof entry.openMessageStep !== 'boolean' ||
+      entry.pendingToolCallIds.some(
+        (toolCallId) => toolCallSteps.get(toolCallId) !== step.id
+      ) ||
+      stepIds.has(step.id)
+    ) {
+      return false;
+    }
+    stepIds.add(step.id);
+  }
+  return true;
+}
+
+function isRunStepResumePayload(value: unknown): value is RunStepResumePayload {
+  if (value == null || typeof value !== 'object') {
+    return false;
+  }
+  const payload = value as Partial<RunStepResumePayload>;
+  return (
+    payload[RUN_STEP_RESUME_WRAPPER_KEY] === 1 &&
+    Object.prototype.hasOwnProperty.call(value, RUN_STEP_RESUME_PAYLOAD_KEY) &&
+    isRunStepResumeState(payload[RUN_STEP_RESUME_STATE_KEY])
+  );
+}
+
+export function attachRunStepResumeState(
+  payload: unknown,
+  state: RunStepResumeState
+): object {
+  const publicPayload = isRunStepResumePayload(payload)
+    ? payload[RUN_STEP_RESUME_PAYLOAD_KEY]
+    : payload;
+  return {
+    [RUN_STEP_RESUME_WRAPPER_KEY]: 1,
+    [RUN_STEP_RESUME_PAYLOAD_KEY]: publicPayload,
+    [RUN_STEP_RESUME_STATE_KEY]: state,
+  } satisfies RunStepResumePayload;
+}
+
+export function getRunStepResumeState(
+  payload: unknown
+): RunStepResumeState | undefined {
+  return isRunStepResumePayload(payload)
+    ? payload[RUN_STEP_RESUME_STATE_KEY]
+    : undefined;
+}
+
+export function stripRunStepResumeState(payload: unknown): unknown {
+  return isRunStepResumePayload(payload)
+    ? payload[RUN_STEP_RESUME_PAYLOAD_KEY]
+    : payload;
+}