@librechat/agents 3.5.1 → 3.6.0

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

package/src/tools/subagent/SubagentExecutor.ts

@@ -46,6 +46,7 @@ import type {
   RunStep,
   RunStepDeltaEvent,
   RunStepClosedEvent,
+  RunStepStatus,
   StandardGraphInput,
   ExecutableSubagentConfigEntry,
   ResolvedSubagentConfig,
@@ -61,7 +62,6 @@ import type {
   ToolApprovalInterruptPayload,
   ToolExecuteBatchRequest,
   ToolCallDelta,
-  ToolSessionContext,
   TokenCounter,
   ToolApprovalDecision,
   ToolApprovalDecisionMap,
@@ -87,6 +87,7 @@ import type {
 import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
 import type { HandlerRegistry } from '@/events';
+import { stripRunStepResumeState } from '@/tools/runStepResume';
 import {
   getSubagentApprovalExecutionScope,
   SubagentDefinitionBindingError,
@@ -124,6 +125,7 @@ import {
   createChildGraphPlan,
   isGraphSubagentConfig,
 } from './childGraphConfig';
+import { seedAgentInitialSessions } from '@/utils/toolSessions';
 import { stableStringify } from '@/tools/eagerEventExecution';
 import { composeAbortSignals } from '@/utils/misc';
 
@@ -147,71 +149,11 @@ const SUBAGENT_CONFIG_CHANGED_MESSAGE =
 const SUBAGENT_INVOCATION_CHANGED_MESSAGE =
   'Subagent error: Subagent invocation changed for this execution.';
 
-function cloneToolSessionContext(
-  context: ToolSessionContext
-): ToolSessionContext {
-  return {
-    ...context,
-    ...(context.files == null
-      ? {}
-      : {
-        files: context.files.map((file) => ({
-          ...file,
-          storage_session_id: file.storage_session_id ?? context.session_id,
-        })),
-      }),
-  };
-}
-
 function seedChildGraphSessions(
   childGraph: StandardGraph,
   agents: AgentInputs[]
 ): void {
-  const seenFilesByTool = new Map<string, Set<string>>();
-  for (const agent of agents) {
-    if (agent.initialSessions == null) {
-      continue;
-    }
-    for (const [toolName, context] of agent.initialSessions) {
-      const existing = childGraph.sessions.get(toolName);
-      if (existing == null) {
-        const cloned = cloneToolSessionContext(context);
-        childGraph.sessions.set(toolName, cloned);
-        seenFilesByTool.set(
-          toolName,
-          new Set(
-            cloned.files?.map(
-              (file) => `${file.storage_session_id ?? ''}\0${file.id}`
-            ) ?? []
-          )
-        );
-        continue;
-      }
-      if (context.files == null || context.files.length === 0) {
-        continue;
-      }
-      const seenFiles =
-        seenFilesByTool.get(toolName) ??
-        new Set(
-          existing.files?.map(
-            (file) =>
-              `${file.storage_session_id ?? existing.session_id}\0${file.id}`
-          ) ?? []
-        );
-      const files = existing.files == null ? [] : [...existing.files];
-      for (const file of context.files) {
-        const storageSessionId = file.storage_session_id ?? context.session_id;
-        const key = `${storageSessionId}\0${file.id}`;
-        if (seenFiles.has(key)) {
-          continue;
-        }
-        seenFiles.add(key);
-        files.push({ ...file, storage_session_id: storageSessionId });
-      }
-      seenFilesByTool.set(toolName, seenFiles);
-      childGraph.sessions.set(toolName, { ...existing, files });
-    }
-  }
+  seedAgentInitialSessions(childGraph.sessions, agents);
 }
 
 async function dispatchObservationalSubagentUpdate(
@@ -713,11 +655,11 @@ function addSubagentScope(
   resumeManifest?: SubagentResumeManifest
 ): Interrupt[] {
   return interrupts.map((childInterrupt) => {
-    let payload = childInterrupt.value;
+    let payload = stripRunStepResumeState(childInterrupt.value);
     if (isToolApprovalPayload(payload)) {
       payload = {
-        ...childInterrupt.value,
-        subagent: childInterrupt.value.subagent ?? scope,
+        ...payload,
+        subagent: payload.subagent ?? scope,
       };
     }
     return {
@@ -1610,6 +1552,42 @@ export class SubagentExecutor {
     graph.clearHeavyState();
   }
 
+  /**
+   * Terminal sweep for a child graph's run steps. `Run.processStream` sweeps
+   * only the graph it owns, and a child executes through `workflow.invoke()`
+   * outside that loop — so without this, a child's last message step (no
+   * successor step ever opens to close it) and every step of an aborted child
+   * stay `in_progress` forever, leaving hosts with unmatched starts.
+   *
+   * Must run BEFORE `forwarding.drain()`: closures reach the parent only as
+   * child custom events through the forwarder, which stops relaying once
+   * drained.
+   *
+   * Deliberately not called on the interrupt path, mirroring the parent's
+   * `isAwaitingResume` guard: an in-process resume continues into these same
+   * steps, so closing them would strand the resumed run. A resume that
+   * crosses a process boundary is a known gap either way — the child rebuilds
+   * from `SubagentGraphResumeState`, which carries tool-call identity but not
+   * `contentData`, so pre-interrupt steps are unreachable from the new graph
+   * and stay open. That is the child-level instance of the same cross-process
+   * orphan the parent graph has, and it needs persisted lifecycle state to
+   * fix rather than a sweep here.
+   *
+   * `at` is the moment execution actually ended, threaded through so
+   * observational work between then and the sweep cannot inflate the stamps.
+   */
+  private async closeChildRunSteps(
+    graph: StandardGraph,
+    status: Exclude<RunStepStatus, 'in_progress'>,
+    at?: number
+  ): Promise<void> {
+    try {
+      await graph.closeUnfinishedRunSteps(status, at);
+    } catch (_e) {
+      /** A failed sweep must never mask the subagent's own outcome */
+    }
+  }
+
   clearHeavyState(): void {
     this.executions.clear((record) => {
       if (record.activeRun != null) {
@@ -2470,6 +2448,8 @@ export class SubagentExecutor {
         result = childResult;
       }
     } catch (error) {
+      /** Stamped at failure, not after the error-envelope work below. */
+      const childTerminalAt = Date.now();
       if (isGraphInterrupt(error)) {
         const activeChildRun = execution.activeRun;
         if (activeChildRun != null) {
@@ -2505,6 +2485,16 @@ export class SubagentExecutor {
         childBreaker.abort(error);
       }
       const errorMessage = truncateErrorMessage(error);
+      /**
+       * `cancelled` vs `failed` mirrors `Run.resolveSweepStatus`: an aborted
+       * child was stopped on purpose (caller abort, or a breaker trip from a
+       * parallel sibling), anything else died of an unexpected error.
+       */
+      await this.closeChildRunSteps(
+        childGraph,
+        childSignal.aborted ? 'cancelled' : 'failed',
+        childTerminalAt
+      );
       if (forwarding) {
         await forwarding.drain();
         await this.emitSubagentUpdate(parentRegistry!, {
@@ -2537,6 +2527,14 @@ export class SubagentExecutor {
       };
     }
 
+    /**
+     * Child execution ended here. Captured before the observational work
+     * below — an awaited `SubagentStop` hook, then the forwarder drain — so a
+     * slow hook cannot inflate the closure stamps with its own latency.
+     * Mirrors the parent's `terminalAt` capture in `Run.processStream`.
+     */
+    const childTerminalAt = Date.now();
+
     if (result == null) {
       throw new Error('Subagent completed without producing graph state.');
     }
@@ -2573,6 +2571,10 @@ export class SubagentExecutor {
       });
     }
 
+    if (!childAlreadyCompleted) {
+      await this.closeChildRunSteps(childGraph, 'completed', childTerminalAt);
+    }
+
     if (forwarding && !childAlreadyCompleted) {
       await forwarding.drain();
       await this.emitSubagentUpdate(parentRegistry!, {

package/src/tools/subagent/SubagentReplay.ts

@@ -2,7 +2,13 @@ import type { ToolCall, ToolMessage } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
 import type { ToolApprovalReplaySnapshot } from '@/hooks';
-import type { ToolSessionContext } from '@/types';
+import type { RunStepResumeState, ToolSessionContext } from '@/types';
+import {
+  attachRunStepResumeState,
+  getRunStepResumeState,
+  isRunStepResumeState,
+  stripRunStepResumeState,
+} from '@/tools/runStepResume';
 
 export const SUBAGENT_RESUME_MANIFEST_CONFIG_KEY =
   '__librechat_subagent_resume_manifest';
@@ -57,6 +63,7 @@ export interface SubagentGraphResumeState {
   toolNodes: SubagentToolNodeResumeState[];
   eagerToolUsage: SubagentEagerToolUsageState[];
   eagerToolSuppressions: string[];
+  runStepState?: RunStepResumeState;
   toolOutputReferences?: ToolOutputReferenceState;
 }
 
@@ -291,6 +298,8 @@ function isGraphResumeState(value: unknown): value is SubagentGraphResumeState {
     !state.eagerToolUsage.every(isEagerToolUsageState) ||
     !Array.isArray(state.eagerToolSuppressions) ||
     !state.eagerToolSuppressions.every(isString) ||
+    (state.runStepState != null &&
+      !isRunStepResumeState(state.runStepState)) ||
     (state.toolOutputReferences != null &&
       !isToolOutputReferenceState(state.toolOutputReferences))
   ) {
@@ -412,6 +421,7 @@ function isSubagentResumeManifest(
 export function getSubagentResumeManifest(
   payload: unknown
 ): SubagentResumeManifest | undefined {
+  payload = stripRunStepResumeState(payload);
   if (payload == null || typeof payload !== 'object') {
     return undefined;
   }
@@ -489,6 +499,16 @@ export function attachSubagentResumeManifest(
   payload: unknown,
   manifest: SubagentResumeManifest
 ): object {
+  const runStepState = getRunStepResumeState(payload);
+  if (runStepState != null) {
+    return attachRunStepResumeState(
+      attachSubagentResumeManifest(
+        stripRunStepResumeState(payload),
+        manifest
+      ),
+      runStepState
+    );
+  }
   if (
     isWrappedSubagentResumePayload(payload) ||
     isInlineSubagentResumePayload(payload)
@@ -512,6 +532,7 @@ export function attachSubagentResumeManifest(
 }
 
 export function stripSubagentResumeManifest(payload: unknown): unknown {
+  payload = stripRunStepResumeState(payload);
   if (isWrappedSubagentResumePayload(payload)) {
     return payload[SUBAGENT_RESUME_WRAPPED_PAYLOAD_KEY];
   }

package/src/types/graph.ts

@@ -20,6 +20,7 @@ import type {
 import type {
   RunStep,
   RunStepDeltaEvent,
+  RunStepResumeState,
   RunStepClosedEvent,
   MessageDeltaEvent,
   ReasoningDeltaEvent,
@@ -76,6 +77,7 @@ export type SystemCallbacks = {
 
 export type BaseGraphState = {
   messages: BaseMessage[];
+  runStepState?: RunStepResumeState;
 };
 
 export type AgentSubgraphState = BaseGraphState & {
@@ -803,6 +805,14 @@ export interface LangfuseConfig {
 
 export interface AgentInputs {
   agentId: string;
+  /**
+   * Partition key for transient code-session ids and file refs. Agents with
+   * the same key share those refs; different execution profiles/scopes must
+   * use different keys. Defaults to the legacy shared `execute_code` slot.
+   * Non-default partitions also disable speculative eager execution of code
+   * tools because their factory may target a durable backend.
+   */
+  codeSessionKey?: string;
   /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
   name?: string;
   toolEnd?: boolean;

package/src/types/stream.ts

@@ -103,6 +103,23 @@ export type RunStep = {
   // };
 };
 
+/** Minimal durable lifecycle state needed to continue open run steps. */
+export interface RunStepResumeEntry {
+  step: RunStep;
+  pendingToolCallIds: string[];
+  latestCompletionAt?: number;
+  openMessageStep: boolean;
+}
+
+/** SDK-private state persisted in LangGraph checkpoints for process-safe resume. */
+export interface RunStepResumeState {
+  version: 1;
+  revision: number;
+  nextIndex: number;
+  toolCallSteps: Array<{ toolCallId: string; stepId: string }>;
+  steps: RunStepResumeEntry[];
+}
+
 /**
  * Represents a run step delta i.e. any changed fields on a run step during
  * streaming.