@librechat/agents 3.2.58 → 3.2.60

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

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

@@ -3996,6 +3996,54 @@ describe('AskUserQuestion — interrupt + resume', () => {
     expect(resumedAnswer).toBe('production');
   });
 
+  it('carries multiSelect through the interrupt payload and resumes with the joined option values', async () => {
+    const { askUserQuestion } = await import('@/hitl');
+
+    let resumedAnswer: string | undefined;
+
+    const builder = new StateGraph(MessagesAnnotation)
+      .addNode('clarifier', () => {
+        const resolution = askUserQuestion({
+          question: 'Which environments?',
+          options: [
+            { label: 'Staging', value: 'staging' },
+            { label: 'Production', value: 'production' },
+          ],
+          multiSelect: true,
+        });
+        resumedAnswer = resolution.answer;
+        return { messages: [] };
+      })
+      .addEdge(START, 'clarifier')
+      .addEdge('clarifier', END);
+    const graph = builder.compile({ checkpointer: new MemorySaver() });
+
+    const config = { configurable: { thread_id: 'ask-q-multi-thread' } };
+
+    const interrupted = (await graph.invoke({ messages: [] }, config)) as {
+      __interrupt__?: Array<{ id?: string; value?: t.HumanInterruptPayload }>;
+    };
+    const payload = interrupted.__interrupt__![0].value!;
+    if (payload.type !== 'ask_user_question') {
+      throw new Error('expected ask_user_question');
+    }
+    expect(payload.question.multiSelect).toBe(true);
+    expect(payload.question.options).toHaveLength(2);
+
+    // Host joins the selected option values with ", ".
+    const resolution: t.AskUserQuestionResolution = {
+      answer: 'staging, production',
+    };
+    await resumeGraph(
+      graph as unknown as CompiledMessagesGraph,
+      interrupted,
+      resolution,
+      config
+    );
+
+    expect(resumedAnswer).toBe('staging, production');
+  });
+
   it('a DIRECT tool in event-driven mode can raise ask_user_question from its body and resume with the answer as its ToolMessage', async () => {
     /**
      * The production host shape (e.g. LibreChat's `AgentInputs.graphTools`

package/src/tools/eagerEventExecution.ts

@@ -52,8 +52,30 @@ export type ToolExecutionPlanCall = {
   args: unknown;
   stepId?: string;
   codeSessionContext?: t.ToolCallRequest['codeSessionContext'];
+  runtimeSessionHint?: string;
 };
 
+/**
+ * Stateful runtime session hint for the remote sandbox: only when
+ * `toolExecution.sandbox.statefulSessions` is on; explicit host hint else the
+ * conversation `thread_id`. Undefined disables the wire field. Shared by the
+ * direct ToolNode path and both event-driven planners so they stay in lockstep.
+ */
+export function resolveRuntimeSessionHint(
+  toolExecution: t.ToolExecutionConfig | undefined,
+  threadId: string | undefined
+): string | undefined {
+  const sandbox = toolExecution?.sandbox;
+  if (sandbox?.statefulSessions !== true) {
+    return undefined;
+  }
+  const explicit = sandbox.runtimeSessionHint;
+  if (explicit != null && explicit !== '') {
+    return explicit;
+  }
+  return threadId != null && threadId !== '' ? threadId : undefined;
+}
+
 export type ToolExecutionRequestPlan = {
   allRequests: t.ToolCallRequest[];
   requests: t.ToolCallRequest[];
@@ -73,15 +95,12 @@ export function buildToolExecutionRequestPlan(args: {
     args: Record<string, unknown>;
     stepId?: string;
     codeSessionContext?: t.ToolCallRequest['codeSessionContext'];
+    runtimeSessionHint?: string;
     rejectedErrorMessage?: string;
   }> = [];
 
   for (const toolCall of args.toolCalls) {
-    if (
-      toolCall.id == null ||
-      toolCall.id === '' ||
-      toolCall.name === ''
-    ) {
+    if (toolCall.id == null || toolCall.id === '' || toolCall.name === '') {
       return undefined;
     }
     const coercedArgs = coerceRecordArgs(toolCall.args);
@@ -95,6 +114,7 @@ export function buildToolExecutionRequestPlan(args: {
         args: {},
         stepId: toolCall.stepId,
         codeSessionContext: toolCall.codeSessionContext,
+        runtimeSessionHint: toolCall.runtimeSessionHint,
         rejectedErrorMessage:
           'Invalid tool call arguments: expected a JSON object.',
       });
@@ -106,6 +126,7 @@ export function buildToolExecutionRequestPlan(args: {
       args: coercedArgs,
       stepId: toolCall.stepId,
       codeSessionContext: toolCall.codeSessionContext,
+      runtimeSessionHint: toolCall.runtimeSessionHint,
     });
   }
 
@@ -123,6 +144,12 @@ export function buildToolExecutionRequestPlan(args: {
     if (toolCall.codeSessionContext != null) {
       request.codeSessionContext = toolCall.codeSessionContext;
     }
+    if (
+      toolCall.runtimeSessionHint != null &&
+      toolCall.runtimeSessionHint !== ''
+    ) {
+      request.runtimeSessionHint = toolCall.runtimeSessionHint;
+    }
     return request;
   });
   const requests = allRequests.filter(

package/src/types/hitl.ts

@@ -140,6 +140,13 @@ export interface AskUserQuestionRequest {
    * UI allows it. Omit to require a free-form answer.
    */
   options?: AskUserQuestionOption[];
+  /**
+   * When `true`, the host UI may let the user pick several options; the
+   * resulting `AskUserQuestionResolution.answer` is the selected option
+   * values joined by `", "`. When omitted or `false`, hosts render a
+   * single-select picker. Only meaningful alongside `options`.
+   */
+  multiSelect?: boolean;
 }
 
 /**
@@ -168,9 +175,10 @@ export type HumanInterruptPayload =
 export interface AskUserQuestionResolution {
   /**
    * The human's answer. Free-form text, or — when `options` were
-   * provided — one of the option `value`s. Hosts may also send any
-   * structured object their custom UI defines; see the host docs for
-   * what your downstream consumer expects.
+   * provided — one of the option `value`s (or, when the request set
+   * `multiSelect`, several option `value`s joined by `", "`). Hosts may
+   * also send any structured object their custom UI defines; see the
+   * host docs for what your downstream consumer expects.
    */
   answer: string;
 }
@@ -287,6 +295,44 @@ export function isAskUserQuestionInterrupt(
  * an interrupt. This applies equally to direct tools (handoffs,
  * subagents) and to event tools.
  *
+ * ### Guarding non-idempotent siblings via `interruptingToolNames`
+ *
+ * The "must be idempotent" rule above is unavoidable in the general
+ * case, but the SDK can protect siblings against the one interrupt
+ * shape it can predict: a tool whose *body* raises `interrupt()`
+ * mid-execution — the `ask_user_question` shape, where the tool
+ * suspends the run to collect a human answer. Declare such tools in
+ * `RunConfig.interruptingToolNames`
+ * ({@link ToolNodeOptions.interruptingToolNames}) and the ToolNode
+ * schedules them, within each batch, **ahead of** their
+ * non-interrupting direct siblings. When one interrupts, the batch
+ * unwinds before any declared-safe sibling has run, so the sibling
+ * executes exactly once (on resume) instead of twice. Empirically:
+ *
+ *   - A **direct** sibling sharing the interrupter's in-process
+ *     `Promise.all` is the only shape that double-executes; declaring
+ *     the interrupter closes it.
+ *   - An **event-dispatched** sibling is already safe without any
+ *     config: the ToolNode awaits the whole direct group (where the
+ *     body interrupt unwinds) before it dispatches event tools, so a
+ *     dispatched sibling never runs on the first pass.
+ *
+ * This is a *scheduling* guard, not full resume idempotency: it only
+ * covers tools that interrupt from their own body and only protects
+ * siblings scheduled after them. It does not retroactively make a
+ * `PreToolUse` `'ask'` gate on tool B stop tool A (already executed)
+ * from re-running — unless B is itself declared interrupting, so it
+ * runs first. Tools with side effects should still be written
+ * idempotent as defense in depth.
+ *
+ * The guard only REORDERS the direct group — declaring a name does not
+ * force it onto the direct path. The interrupting tool must already be a
+ * real in-process graphTool (the only kind whose body can reach
+ * `interrupt()`). A name that resolves to a schema-only event stub (an
+ * inherited `toolDefinition` with no executable instance, e.g. in a
+ * self-spawned child that scrubs `graphTools`) stays event-dispatched
+ * and the ordering is a no-op for it.
+ *
  * ## Note on idempotency
  *
  * Same root cause as the resume re-execution above: LangGraph

package/src/types/run.ts

@@ -193,6 +193,27 @@ export type RunConfig = {
    * the SDK stays name-agnostic.
    */
   codeSessionToolNames?: string[];
+  /**
+   * Names of host tools whose in-process body may raise a LangGraph
+   * `interrupt()` mid-execution — the canonical example is an
+   * `ask_user_question` tool that suspends the run to collect a human
+   * answer. Within a single tool-call batch, a named tool that is a real
+   * in-process graphTool (the only kind whose body can reach `interrupt()`;
+   * graphTools are auto-marked direct) is scheduled **ahead of** its
+   * non-interrupting direct siblings. That ordering guarantees a mid-body
+   * interrupt unwinds the tool batch before a non-idempotent sibling
+   * (send_email, billing) executes, so the sibling cannot run once on the
+   * first pass and AGAIN when LangGraph re-runs the interrupted batch on
+   * resume.
+   *
+   * This only reorders the direct group — it does NOT force a name onto
+   * the direct path. A name that is only an inherited event `toolDefinition`
+   * (schema-only stub, e.g. in a self-spawned child) stays event-dispatched;
+   * the guard applies only to tools that are independently direct.
+   * Host-declared so the SDK stays name-agnostic; omit to keep the prior
+   * (unguarded) behavior.
+   */
+  interruptingToolNames?: 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/src/types/tools.ts

@@ -89,10 +89,18 @@ export type ToolNodeOptions = {
   handleToolErrors?: boolean;
   loadRuntimeTools?: ToolRefGenerator;
   toolCallStepIds?: Map<string, string>;
+  /**
+   * Dispatches the error completion event for a failed tool call. Returns
+   * whether the event was actually dispatched — `false` (e.g. no run step is
+   * registered for the call yet, which happens when a tool fails fast on a
+   * resume pass) tells the ToolNode to fall back to its own completion
+   * dispatch for the error ToolMessage. A `void` resolution is treated as
+   * dispatched for backward compatibility.
+   */
   errorHandler?: (
     data: ToolErrorData,
     metadata?: Record<string, unknown>
-  ) => Promise<void>;
+  ) => Promise<boolean | void>;
   /** Tool registry for lazy computation of programmatic tools and tool search */
   toolRegistry?: LCToolRegistry;
   /** Reference to Graph's sessions map for automatic session injection */
@@ -108,6 +116,34 @@ export type ToolNodeOptions = {
   executingAgentId?: string;
   /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
   directToolNames?: Set<string>;
+  /**
+   * Tool names whose in-process body may raise a LangGraph `interrupt()`
+   * mid-execution — e.g. an `ask_user_question` tool that suspends the
+   * run to collect a human answer.
+   *
+   * Within a single tool-call batch, a named tool that is *already*
+   * direct (a real in-process graphTool — the only kind whose body can
+   * reach `interrupt()`; graphTools are auto-marked direct by the graph)
+   * is executed as its own awaited group **before** its non-interrupting
+   * direct siblings. If it interrupts, the ToolNode unwinds before any
+   * sibling runs, so a non-idempotent sibling (send_email, billing)
+   * cannot execute once on the first pass and AGAIN when LangGraph re-runs
+   * the interrupted batch on resume.
+   *
+   * This set only REORDERS the direct group; it does NOT promote a name
+   * into it. A name that resolves to a schema-only event stub (an
+   * inherited `toolDefinition` with no executable instance — e.g. in a
+   * self-spawned child that scrubs `graphTools`) stays event-dispatched.
+   * Forcing such a name direct would invoke the stub, which throws
+   * "should not be invoked directly in event-driven mode". For the guard
+   * to apply, the interrupting tool must independently be direct.
+   *
+   * Opt-in and empty by default: when unset (or when no direct batch call
+   * matches), direct-batch execution is byte-for-byte unchanged. See the
+   * "Resume re-execution" section of {@link HumanInTheLoopConfig} for the
+   * batch re-execution contract this guards against.
+   */
+  interruptingToolNames?: Set<string>;
   /** Opt-in eager execution for event-driven tool calls. */
   eagerEventToolExecution?: EagerEventToolExecutionConfig;
   /**
@@ -292,6 +328,15 @@ export type CodeExecutionToolParams =
       files?: CodeEnvFile[];
       /** Optional host-supplied Code API auth headers. */
       authHeaders?: CodeApiAuthHeaders;
+      /**
+       * Advertise best-effort stateful sessions in the tool description
+       * (variables/files may persist between calls, may reset). Prompt text
+       * only, and it must be set here because the description is bound to the
+       * LLM at construction time. Pair it with the run-scoped
+       * `toolExecution.sandbox.statefulSessions` gate, which drives the wire
+       * hint — set both from one flag so the prompt and the backend agree.
+       */
+      statefulSessions?: boolean;
     };
 
 export type CodeApiAuthHeaderMap = Record<string, string>;
@@ -347,6 +392,13 @@ export type ExecuteResult = {
   stdout: string;
   stderr: string;
   files?: FileRefs;
+  /**
+   * Durable runtime session id echoed by a stateful Code API backend
+   * (hash of tenant+user+hint). Additive; absent on stateless servers.
+   */
+  runtime_session_id?: string;
+  /** Whether this execution reused a warm runtime session or started fresh. */
+  runtime_status?: 'new' | 'reused';
 };
 
 /** JSON Schema type definition for tool parameters */
@@ -413,6 +465,12 @@ export type ToolCallRequest = {
     session_id: string;
     files?: CodeEnvFile[];
   };
+  /**
+   * Stable runtime session hint for stateful sandbox sessions. Orthogonal to
+   * `codeSessionContext` (which threads the transient exec-session for file
+   * continuity): the hint identifies the durable server-side runtime session.
+   */
+  runtimeSessionHint?: string;
 };
 
 /** Batch request containing ALL tool calls for a graph step */
@@ -969,6 +1027,32 @@ export type CloudflareSandboxExecutionConfig = {
   postEditSyntaxCheck?: LocalExecutionConfig['postEditSyntaxCheck'];
 };
 
+export type SandboxExecutionConfig = {
+  /**
+   * Opt into best-effort stateful runtime sessions on the remote Code API
+   * (its warm per-session MicroVM backend). This gate is run-scoped: it only
+   * controls the wire behavior (ToolNode injecting the session hint on
+   * execute_code/bash calls). The transport is otherwise unchanged.
+   *
+   * It does NOT change the model-facing tool description. Tool descriptions are
+   * bound to the LLM at construction time (`createCodeExecutionTool` /
+   * `createBashExecutionTool`), before this run config is applied inside the
+   * graph, so they can only be adjusted via the tools' own `statefulSessions`
+   * factory param. Set BOTH from one flag (as LibreChat does): with this on but
+   * the factory param off, the backend runs statefully while the model is still
+   * told the environment is stateless (non-corrupting — the model just won't
+   * exploit persistence).
+   */
+  statefulSessions?: boolean;
+  /**
+   * Stable identity for the runtime session (e.g. the conversation id). The
+   * server derives the real session id as hash(tenant, user, hint), so this
+   * is never a security boundary. Falls back to `configurable.thread_id` when
+   * omitted.
+   */
+  runtimeSessionHint?: string;
+};
+
 export type ToolExecutionConfig = {
   /** `sandbox` preserves the remote Code API behavior and is the default. */
   engine?: ToolExecutionEngine;
@@ -976,6 +1060,8 @@ export type ToolExecutionConfig = {
   local?: LocalExecutionConfig;
   /** Cloudflare Sandbox execution settings used when `engine` is `cloudflare-sandbox`. */
   cloudflare?: CloudflareSandboxExecutionConfig;
+  /** Remote sandbox settings; applies when `engine` is `sandbox` or omitted. */
+  sandbox?: SandboxExecutionConfig;
 };
 
 export type ProgrammaticCache = {
@@ -1099,6 +1185,10 @@ export type ProgrammaticExecutionResponse = {
   stderr?: string;
   files?: FileRefs;
 
+  /** Durable runtime session echo from a stateful backend (additive). */
+  runtime_session_id?: string;
+  runtime_status?: 'new' | 'reused';
+
   /** Present when status='error' */
   error?: string;
 };
@@ -1110,6 +1200,9 @@ export type ProgrammaticExecutionArtifact = {
   /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
   files?: FileRefs;
+  /** Durable runtime session echo from a stateful backend (additive). */
+  runtime_session_id?: string;
+  runtime_status?: 'new' | 'reused';
 };
 
 /** Parameters for creating a bash execution tool (same API as CodeExecutor, bash-only) */
@@ -1134,6 +1227,11 @@ export type ProgrammaticToolCallingParams = {
   debug?: boolean;
   /** Optional host-supplied Code API auth headers. */
   authHeaders?: CodeApiAuthHeaders;
+  /* No `statefulSessions` here: PTC is stateless in v1. The initial
+   * /exec/programmatic request still forwards a ToolNode-injected
+   * `_runtime_session_hint` when present, but there is no factory-level opt-in
+   * to advertise (it would be a no-op). Re-add with real behavior when PTC
+   * stateful prompting lands. */
 };
 
 // ============================================================================
@@ -1166,6 +1264,9 @@ export type CodeExecutionArtifact = {
   /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
   files?: FileRefs;
+  /** Durable runtime session echo from a stateful backend (additive). */
+  runtime_session_id?: string;
+  runtime_status?: 'new' | 'reused';
 };
 
 /**