@librechat/agents 3.2.58 → 3.2.59

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/tools.ts

@@ -292,6 +292,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 +356,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 +429,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 +991,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 +1024,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 +1149,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 +1164,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 +1191,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 +1228,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';
 };
 
 /**