@librechat/agents 3.2.58 → 3.2.59

package/dist/esm/tools/eagerEventExecution.mjs

@@ -22,6 +22,19 @@ function recordArgsEqual(left, right) {
 function normalizeError(error) {
 	return error instanceof Error ? error : new Error(String(error));
 }
+/**
+* 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.
+*/
+function resolveRuntimeSessionHint(toolExecution, threadId) {
+	const sandbox = toolExecution?.sandbox;
+	if (sandbox?.statefulSessions !== true) return;
+	const explicit = sandbox.runtimeSessionHint;
+	if (explicit != null && explicit !== "") return explicit;
+	return threadId != null && threadId !== "" ? threadId : void 0;
+}
 function buildToolExecutionRequestPlan(args) {
 	const invalidArgsBehavior = args.invalidArgsBehavior ?? "abort";
 	const prepared = [];
@@ -36,6 +49,7 @@ function buildToolExecutionRequestPlan(args) {
 				args: {},
 				stepId: toolCall.stepId,
 				codeSessionContext: toolCall.codeSessionContext,
+				runtimeSessionHint: toolCall.runtimeSessionHint,
 				rejectedErrorMessage: "Invalid tool call arguments: expected a JSON object."
 			});
 			continue;
@@ -45,7 +59,8 @@ function buildToolExecutionRequestPlan(args) {
 			name: toolCall.name,
 			args: coercedArgs,
 			stepId: toolCall.stepId,
-			codeSessionContext: toolCall.codeSessionContext
+			codeSessionContext: toolCall.codeSessionContext,
+			runtimeSessionHint: toolCall.runtimeSessionHint
 		});
 	}
 	const nextUsageCount = new Map(args.usageCount);
@@ -60,6 +75,7 @@ function buildToolExecutionRequestPlan(args) {
 			turn
 		};
 		if (toolCall.codeSessionContext != null) request.codeSessionContext = toolCall.codeSessionContext;
+		if (toolCall.runtimeSessionHint != null && toolCall.runtimeSessionHint !== "") request.runtimeSessionHint = toolCall.runtimeSessionHint;
 		return request;
 	});
 	const requests = allRequests.filter((_, index) => prepared[index].rejectedErrorMessage == null);
@@ -81,6 +97,6 @@ function buildToolExecutionRequestPlan(args) {
 	};
 }
 //#endregion
-export { buildToolExecutionRequestPlan, coerceRecordArgs, normalizeError, recordArgsEqual };
+export { buildToolExecutionRequestPlan, coerceRecordArgs, normalizeError, recordArgsEqual, resolveRuntimeSessionHint };
 
 //# sourceMappingURL=eagerEventExecution.mjs.map

package/dist/esm/tools/eagerEventExecution.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"eagerEventExecution.mjs","names":[],"sources":["../../../src/tools/eagerEventExecution.ts"],"sourcesContent":["import type * as t from '@/types';\n\nexport function coerceRecordArgs(\n  args: unknown\n): Record<string, unknown> | undefined {\n  if (typeof args === 'string') {\n    try {\n      const parsed = JSON.parse(args) as unknown;\n      return coerceRecordArgs(parsed);\n    } catch {\n      return undefined;\n    }\n  }\n\n  if (args === null || typeof args !== 'object' || Array.isArray(args)) {\n    return undefined;\n  }\n\n  return args as Record<string, unknown>;\n}\n\nexport function stableStringify(value: unknown): string {\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item)).join(',')}]`;\n  }\n\n  if (value !== null && typeof value === 'object') {\n    const record = value as Record<string, unknown>;\n    const keys = Object.keys(record).sort();\n    return `{${keys\n      .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)\n      .join(',')}}`;\n  }\n\n  return JSON.stringify(value);\n}\n\nexport function recordArgsEqual(\n  left: Record<string, unknown>,\n  right: Record<string, unknown>\n): boolean {\n  return stableStringify(left) === stableStringify(right);\n}\n\nexport function normalizeError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n\nexport type ToolExecutionPlanCall = {\n  id?: string;\n  name: string;\n  args: unknown;\n  stepId?: string;\n  codeSessionContext?: t.ToolCallRequest['codeSessionContext'];\n};\n\nexport type ToolExecutionRequestPlan = {\n  allRequests: t.ToolCallRequest[];\n  requests: t.ToolCallRequest[];\n  rejectedResults: t.ToolExecuteResult[];\n};\n\nexport function buildToolExecutionRequestPlan(args: {\n  toolCalls: ToolExecutionPlanCall[];\n  usageCount: Map<string, number>;\n  invalidArgsBehavior?: 'abort' | 'error-result';\n  recordTurn?: (toolName: string, turn: number, callId: string) => void;\n}): ToolExecutionRequestPlan | undefined {\n  const invalidArgsBehavior = args.invalidArgsBehavior ?? 'abort';\n  const prepared: Array<{\n    id: string;\n    name: string;\n    args: Record<string, unknown>;\n    stepId?: string;\n    codeSessionContext?: t.ToolCallRequest['codeSessionContext'];\n    rejectedErrorMessage?: string;\n  }> = [];\n\n  for (const toolCall of args.toolCalls) {\n    if (\n      toolCall.id == null ||\n      toolCall.id === '' ||\n      toolCall.name === ''\n    ) {\n      return undefined;\n    }\n    const coercedArgs = coerceRecordArgs(toolCall.args);\n    if (coercedArgs == null) {\n      if (invalidArgsBehavior === 'abort') {\n        return undefined;\n      }\n      prepared.push({\n        id: toolCall.id,\n        name: toolCall.name,\n        args: {},\n        stepId: toolCall.stepId,\n        codeSessionContext: toolCall.codeSessionContext,\n        rejectedErrorMessage:\n          'Invalid tool call arguments: expected a JSON object.',\n      });\n      continue;\n    }\n    prepared.push({\n      id: toolCall.id,\n      name: toolCall.name,\n      args: coercedArgs,\n      stepId: toolCall.stepId,\n      codeSessionContext: toolCall.codeSessionContext,\n    });\n  }\n\n  const nextUsageCount = new Map(args.usageCount);\n  const allRequests = prepared.map((toolCall): t.ToolCallRequest => {\n    const turn = nextUsageCount.get(toolCall.name) ?? 0;\n    nextUsageCount.set(toolCall.name, turn + 1);\n    const request: t.ToolCallRequest = {\n      id: toolCall.id,\n      name: toolCall.name,\n      args: toolCall.args,\n      stepId: toolCall.stepId,\n      turn,\n    };\n    if (toolCall.codeSessionContext != null) {\n      request.codeSessionContext = toolCall.codeSessionContext;\n    }\n    return request;\n  });\n  const requests = allRequests.filter(\n    (_, index) => prepared[index].rejectedErrorMessage == null\n  );\n  const rejectedResults = prepared.flatMap((toolCall) => {\n    if (toolCall.rejectedErrorMessage == null) {\n      return [];\n    }\n    return [\n      {\n        toolCallId: toolCall.id,\n        status: 'error' as const,\n        content: '',\n        errorMessage: toolCall.rejectedErrorMessage,\n      },\n    ];\n  });\n\n  for (const [toolName, count] of nextUsageCount) {\n    args.usageCount.set(toolName, count);\n  }\n  for (const request of allRequests) {\n    args.recordTurn?.(request.name, request.turn ?? 0, request.id);\n  }\n\n  return { allRequests, requests, rejectedResults };\n}\n"],"mappings":";AAEA,SAAgB,iBACd,MACqC;CACrC,IAAI,OAAO,SAAS,UAClB,IAAI;EAEF,OAAO,iBADQ,KAAK,MAAM,IACG,CAAC;CAChC,QAAQ;EACN;CACF;CAGF,IAAI,SAAS,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI,GACjE;CAGF,OAAO;AACT;AAEA,SAAgB,gBAAgB,OAAwB;CACtD,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,IAAI,MAAM,KAAK,SAAS,gBAAgB,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE;CAGlE,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;EAC/C,MAAM,SAAS;EAEf,OAAO,IADM,OAAO,KAAK,MAAM,CAAC,CAAC,KACnB,CAAC,CACZ,KAAK,QAAQ,GAAG,KAAK,UAAU,GAAG,EAAE,GAAG,gBAAgB,OAAO,IAAI,GAAG,CAAC,CACtE,KAAK,GAAG,EAAE;CACf;CAEA,OAAO,KAAK,UAAU,KAAK;AAC7B;AAEA,SAAgB,gBACd,MACA,OACS;CACT,OAAO,gBAAgB,IAAI,MAAM,gBAAgB,KAAK;AACxD;AAEA,SAAgB,eAAe,OAAuB;CACpD,OAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AACjE;AAgBA,SAAgB,8BAA8B,MAKL;CACvC,MAAM,sBAAsB,KAAK,uBAAuB;CACxD,MAAM,WAOD,CAAC;CAEN,KAAK,MAAM,YAAY,KAAK,WAAW;EACrC,IACE,SAAS,MAAM,QACf,SAAS,OAAO,MAChB,SAAS,SAAS,IAElB;EAEF,MAAM,cAAc,iBAAiB,SAAS,IAAI;EAClD,IAAI,eAAe,MAAM;GACvB,IAAI,wBAAwB,SAC1B;GAEF,SAAS,KAAK;IACZ,IAAI,SAAS;IACb,MAAM,SAAS;IACf,MAAM,CAAC;IACP,QAAQ,SAAS;IACjB,oBAAoB,SAAS;IAC7B,sBACE;GACJ,CAAC;GACD;EACF;EACA,SAAS,KAAK;GACZ,IAAI,SAAS;GACb,MAAM,SAAS;GACf,MAAM;GACN,QAAQ,SAAS;GACjB,oBAAoB,SAAS;EAC/B,CAAC;CACH;CAEA,MAAM,iBAAiB,IAAI,IAAI,KAAK,UAAU;CAC9C,MAAM,cAAc,SAAS,KAAK,aAAgC;EAChE,MAAM,OAAO,eAAe,IAAI,SAAS,IAAI,KAAK;EAClD,eAAe,IAAI,SAAS,MAAM,OAAO,CAAC;EAC1C,MAAM,UAA6B;GACjC,IAAI,SAAS;GACb,MAAM,SAAS;GACf,MAAM,SAAS;GACf,QAAQ,SAAS;GACjB;EACF;EACA,IAAI,SAAS,sBAAsB,MACjC,QAAQ,qBAAqB,SAAS;EAExC,OAAO;CACT,CAAC;CACD,MAAM,WAAW,YAAY,QAC1B,GAAG,UAAU,SAAS,MAAM,CAAC,wBAAwB,IACxD;CACA,MAAM,kBAAkB,SAAS,SAAS,aAAa;EACrD,IAAI,SAAS,wBAAwB,MACnC,OAAO,CAAC;EAEV,OAAO,CACL;GACE,YAAY,SAAS;GACrB,QAAQ;GACR,SAAS;GACT,cAAc,SAAS;EACzB,CACF;CACF,CAAC;CAED,KAAK,MAAM,CAAC,UAAU,UAAU,gBAC9B,KAAK,WAAW,IAAI,UAAU,KAAK;CAErC,KAAK,MAAM,WAAW,aACpB,KAAK,aAAa,QAAQ,MAAM,QAAQ,QAAQ,GAAG,QAAQ,EAAE;CAG/D,OAAO;EAAE;EAAa;EAAU;CAAgB;AAClD"}
+{"version":3,"file":"eagerEventExecution.mjs","names":[],"sources":["../../../src/tools/eagerEventExecution.ts"],"sourcesContent":["import type * as t from '@/types';\n\nexport function coerceRecordArgs(\n  args: unknown\n): Record<string, unknown> | undefined {\n  if (typeof args === 'string') {\n    try {\n      const parsed = JSON.parse(args) as unknown;\n      return coerceRecordArgs(parsed);\n    } catch {\n      return undefined;\n    }\n  }\n\n  if (args === null || typeof args !== 'object' || Array.isArray(args)) {\n    return undefined;\n  }\n\n  return args as Record<string, unknown>;\n}\n\nexport function stableStringify(value: unknown): string {\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item)).join(',')}]`;\n  }\n\n  if (value !== null && typeof value === 'object') {\n    const record = value as Record<string, unknown>;\n    const keys = Object.keys(record).sort();\n    return `{${keys\n      .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)\n      .join(',')}}`;\n  }\n\n  return JSON.stringify(value);\n}\n\nexport function recordArgsEqual(\n  left: Record<string, unknown>,\n  right: Record<string, unknown>\n): boolean {\n  return stableStringify(left) === stableStringify(right);\n}\n\nexport function normalizeError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n\nexport type ToolExecutionPlanCall = {\n  id?: string;\n  name: string;\n  args: unknown;\n  stepId?: string;\n  codeSessionContext?: t.ToolCallRequest['codeSessionContext'];\n  runtimeSessionHint?: string;\n};\n\n/**\n * Stateful runtime session hint for the remote sandbox: only when\n * `toolExecution.sandbox.statefulSessions` is on; explicit host hint else the\n * conversation `thread_id`. Undefined disables the wire field. Shared by the\n * direct ToolNode path and both event-driven planners so they stay in lockstep.\n */\nexport function resolveRuntimeSessionHint(\n  toolExecution: t.ToolExecutionConfig | undefined,\n  threadId: string | undefined\n): string | undefined {\n  const sandbox = toolExecution?.sandbox;\n  if (sandbox?.statefulSessions !== true) {\n    return undefined;\n  }\n  const explicit = sandbox.runtimeSessionHint;\n  if (explicit != null && explicit !== '') {\n    return explicit;\n  }\n  return threadId != null && threadId !== '' ? threadId : undefined;\n}\n\nexport type ToolExecutionRequestPlan = {\n  allRequests: t.ToolCallRequest[];\n  requests: t.ToolCallRequest[];\n  rejectedResults: t.ToolExecuteResult[];\n};\n\nexport function buildToolExecutionRequestPlan(args: {\n  toolCalls: ToolExecutionPlanCall[];\n  usageCount: Map<string, number>;\n  invalidArgsBehavior?: 'abort' | 'error-result';\n  recordTurn?: (toolName: string, turn: number, callId: string) => void;\n}): ToolExecutionRequestPlan | undefined {\n  const invalidArgsBehavior = args.invalidArgsBehavior ?? 'abort';\n  const prepared: Array<{\n    id: string;\n    name: string;\n    args: Record<string, unknown>;\n    stepId?: string;\n    codeSessionContext?: t.ToolCallRequest['codeSessionContext'];\n    runtimeSessionHint?: string;\n    rejectedErrorMessage?: string;\n  }> = [];\n\n  for (const toolCall of args.toolCalls) {\n    if (toolCall.id == null || toolCall.id === '' || toolCall.name === '') {\n      return undefined;\n    }\n    const coercedArgs = coerceRecordArgs(toolCall.args);\n    if (coercedArgs == null) {\n      if (invalidArgsBehavior === 'abort') {\n        return undefined;\n      }\n      prepared.push({\n        id: toolCall.id,\n        name: toolCall.name,\n        args: {},\n        stepId: toolCall.stepId,\n        codeSessionContext: toolCall.codeSessionContext,\n        runtimeSessionHint: toolCall.runtimeSessionHint,\n        rejectedErrorMessage:\n          'Invalid tool call arguments: expected a JSON object.',\n      });\n      continue;\n    }\n    prepared.push({\n      id: toolCall.id,\n      name: toolCall.name,\n      args: coercedArgs,\n      stepId: toolCall.stepId,\n      codeSessionContext: toolCall.codeSessionContext,\n      runtimeSessionHint: toolCall.runtimeSessionHint,\n    });\n  }\n\n  const nextUsageCount = new Map(args.usageCount);\n  const allRequests = prepared.map((toolCall): t.ToolCallRequest => {\n    const turn = nextUsageCount.get(toolCall.name) ?? 0;\n    nextUsageCount.set(toolCall.name, turn + 1);\n    const request: t.ToolCallRequest = {\n      id: toolCall.id,\n      name: toolCall.name,\n      args: toolCall.args,\n      stepId: toolCall.stepId,\n      turn,\n    };\n    if (toolCall.codeSessionContext != null) {\n      request.codeSessionContext = toolCall.codeSessionContext;\n    }\n    if (\n      toolCall.runtimeSessionHint != null &&\n      toolCall.runtimeSessionHint !== ''\n    ) {\n      request.runtimeSessionHint = toolCall.runtimeSessionHint;\n    }\n    return request;\n  });\n  const requests = allRequests.filter(\n    (_, index) => prepared[index].rejectedErrorMessage == null\n  );\n  const rejectedResults = prepared.flatMap((toolCall) => {\n    if (toolCall.rejectedErrorMessage == null) {\n      return [];\n    }\n    return [\n      {\n        toolCallId: toolCall.id,\n        status: 'error' as const,\n        content: '',\n        errorMessage: toolCall.rejectedErrorMessage,\n      },\n    ];\n  });\n\n  for (const [toolName, count] of nextUsageCount) {\n    args.usageCount.set(toolName, count);\n  }\n  for (const request of allRequests) {\n    args.recordTurn?.(request.name, request.turn ?? 0, request.id);\n  }\n\n  return { allRequests, requests, rejectedResults };\n}\n"],"mappings":"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"}

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

@@ -19,6 +19,15 @@ export declare const BashExecutionToolSchema: {
     readonly required: readonly ["command"];
 };
 export declare const BashExecutionToolDescription: string;
+/**
+ * Bash statefulness is filesystem-tier: on a warm session the machine (files
+ * including /tmp, installed packages, background processes) persists between
+ * calls, but each call may start a fresh shell — so shell variables and cwd
+ * are NOT reliable, and the machine can be reset at any time. Only /mnt/data
+ * is durable.
+ */
+export declare const STATEFUL_BASH_NOTE = "Session state (best-effort): commands in this conversation usually run on the same machine, so files (including /tmp), installed packages, and running background processes from earlier calls typically persist. Each call may still start a fresh shell \u2014 do not rely on shell variables or the working directory carrying over \u2014 and the machine may be reset at any time. Only /mnt/data is durable.";
+export declare const StatefulBashExecutionToolDescription: string;
 /**
  * Supplemental prompt documenting the tool-output reference feature.
  *
@@ -39,7 +48,11 @@ export declare const BashToolOutputReferencesGuide: string;
  */
 export declare function buildBashExecutionToolDescription(options?: {
     enableToolOutputReferences?: boolean;
+    statefulSessions?: boolean;
 }): string;
+export declare function buildBashExecutionToolSchema(opts?: {
+    statefulSessions?: boolean;
+}): typeof BashExecutionToolSchema;
 export declare const BashExecutionToolName = Constants.BASH_TOOL;
 /**
  * Default bash tool definition using the base description.

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

@@ -38,6 +38,20 @@ export declare function buildCodeApiHttpErrorMessage(method: string, endpoint: s
     text: () => Promise<string>;
 }): Promise<string>;
 export declare const CodeExecutionToolDescription: string;
+/**
+ * Best-effort statefulness note. Deliberately hedged: warm reuse is an
+ * optimization, not a guarantee (the runtime may be reset on idle timeout,
+ * eviction, or the 8h VM lifetime), so the model must never depend on carried
+ * state for correctness and must persist anything durable to /mnt/data.
+ */
+export declare const STATEFUL_ENV_NOTE = "Session state (best-effort): consecutive executions in this conversation usually share one runtime, so variables, imports, and in-memory data from earlier successful calls are typically still available. The runtime may be reset at any time, so treat carried-over state as an optimization, never a guarantee. Anything that must survive MUST be written to /mnt/data. If a NameError/ImportError signals lost state, re-run the needed setup and continue.";
+export declare const StatefulCodeExecutionToolDescription: string;
+export declare function buildCodeExecutionToolDescription(opts?: {
+    statefulSessions?: boolean;
+}): string;
+export declare function buildCodeExecutionToolSchema(opts?: {
+    statefulSessions?: boolean;
+}): typeof CodeExecutionToolSchema;
 export declare const CodeExecutionToolName = Constants.EXECUTE_CODE;
 export declare const CodeExecutionToolDefinition: {
     readonly name: Constants.EXECUTE_CODE;

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

@@ -314,6 +314,9 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * opt-in so only host-declared tools can influence the shared session.
      */
     private participatesInCodeSession;
+    /** Delegates to the shared resolver so the direct and event-driven planning
+     *  paths derive the runtime session hint identically. */
+    private resolveRuntimeSessionHint;
     private storeCodeSessionFromResults;
     /**
      * Post-processes standard runTool outputs: dispatches ON_RUN_STEP_COMPLETED

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

@@ -9,7 +9,15 @@ 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 declare function resolveRuntimeSessionHint(toolExecution: t.ToolExecutionConfig | undefined, threadId: string | undefined): string | undefined;
 export type ToolExecutionRequestPlan = {
     allRequests: t.ToolCallRequest[];
     requests: t.ToolCallRequest[];

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

@@ -278,6 +278,15 @@ export type CodeExecutionToolParams = undefined | {
     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>;
 export type CodeApiAuthHeaders = CodeApiAuthHeaderMap | (() => CodeApiAuthHeaderMap | Promise<CodeApiAuthHeaderMap>);
@@ -326,6 +335,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 */
 export type JsonSchemaType = {
@@ -381,6 +397,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 */
 export type ToolExecuteBatchRequest = {
@@ -896,6 +918,31 @@ export type CloudflareSandboxExecutionConfig = {
     /** Run a fast per-file syntax check after successful edits/writes. */
     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;
@@ -903,6 +950,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 = {
     toolMap: ToolMap;
@@ -1005,6 +1054,9 @@ export type ProgrammaticExecutionResponse = {
     stdout?: string;
     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;
 };
@@ -1015,6 +1067,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) */
 export type BashExecutionToolParams = CodeExecutionToolParams;
@@ -1062,6 +1117,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';
 };
 /**
  * Generic session context union type for different tool types.

package/package.json

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

package/src/stream.ts

@@ -142,7 +142,18 @@ function isEagerExecutionExcludedTool(
   // 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;
+  if (graph.codeSessionToolNames?.includes(name) === true) {
+    return true;
+  }
+  // With stateful sessions on, execute_code/bash run against a DURABLE warm
+  // runtime. Speculative prestart there is unsafe: if the model revises the
+  // args, ToolNode discards the eager result but the mutation has already
+  // landed in the session workspace, corrupting later runs. Stateless mode
+  // uses a throwaway VM per call, so eager prestart stays safe there.
+  return (
+    graph.toolExecution?.sandbox?.statefulSessions === true &&
+    CODE_EXECUTION_TOOLS.has(name)
+  );
 }
 
 function isDirectGraphTool(
@@ -668,6 +679,11 @@ function createEagerToolExecutionPlan(args: {
     return undefined;
   }
 
+  /* No runtimeSessionHint here on purpose: the eager path is speculative, and
+   * code-session tools (the only ones that carry a hint) are excluded from
+   * eager prestart entirely when stateful sessions are on — see
+   * isEagerExecutionExcludedTool. The durable runtime is only ever touched by
+   * the committed ToolNode path. */
   const plan = buildToolExecutionRequestPlan({
     toolCalls: candidateToolCalls.map((toolCall) => ({
       id: toolCall.id,

package/src/tools/BashExecutor.ts

@@ -57,6 +57,29 @@ Usage:
 - NEVER use this tool to execute malicious commands.
 `.trim();
 
+/**
+ * Bash statefulness is filesystem-tier: on a warm session the machine (files
+ * including /tmp, installed packages, background processes) persists between
+ * calls, but each call may start a fresh shell — so shell variables and cwd
+ * are NOT reliable, and the machine can be reset at any time. Only /mnt/data
+ * is durable.
+ */
+export const STATEFUL_BASH_NOTE =
+  'Session state (best-effort): commands in this conversation usually run on the same machine, so files (including /tmp), installed packages, and running background processes from earlier calls typically persist. Each call may still start a fresh shell — do not rely on shell variables or the working directory carrying over — and the machine may be reset at any time. Only /mnt/data is durable.';
+
+export const StatefulBashExecutionToolDescription = `
+Runs bash commands and returns stdout/stderr output from a session-based execution environment, similar to a long-running machine.
+
+${STATEFUL_BASH_NOTE}
+
+Usage:
+- No network access available.
+- Generated files are automatically delivered; **DO NOT** provide download links.
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
+- ${BASH_SHELL_GUIDANCE}
+- NEVER use this tool to execute malicious commands.
+`.trim();
+
 /**
  * Supplemental prompt documenting the tool-output reference feature.
  *
@@ -87,11 +110,45 @@ Referencing previous tool outputs:
  */
 export function buildBashExecutionToolDescription(options?: {
   enableToolOutputReferences?: boolean;
+  statefulSessions?: boolean;
 }): string {
+  const base =
+    options?.statefulSessions === true
+      ? StatefulBashExecutionToolDescription
+      : BashExecutionToolDescription;
   if (options?.enableToolOutputReferences === true) {
-    return `${BashExecutionToolDescription}\n\n${BashToolOutputReferencesGuide}`;
+    return `${base}\n\n${BashToolOutputReferencesGuide}`;
   }
-  return BashExecutionToolDescription;
+  return base;
+}
+
+const STATELESS_BASH_PARAM_NOTE =
+  'The environment is stateless; variables and state don\'t persist between executions.';
+const STATEFUL_BASH_PARAM_NOTE =
+  'Files, installed packages, and background processes usually persist between calls, but each call may start a fresh shell (do not rely on shell variables or cwd) and the machine may reset. Only /mnt/data is durable.';
+
+export function buildBashExecutionToolSchema(opts?: {
+  statefulSessions?: boolean;
+}): typeof BashExecutionToolSchema {
+  const note =
+    opts?.statefulSessions === true
+      ? STATEFUL_BASH_PARAM_NOTE
+      : STATELESS_BASH_PARAM_NOTE;
+  const commandDescription =
+    BashExecutionToolSchema.properties.command.description.replace(
+      STATELESS_BASH_PARAM_NOTE,
+      note
+    );
+  return {
+    ...BashExecutionToolSchema,
+    properties: {
+      ...BashExecutionToolSchema.properties,
+      command: {
+        ...BashExecutionToolSchema.properties.command,
+        description: commandDescription,
+      },
+    },
+  } as typeof BashExecutionToolSchema;
 }
 
 export const BashExecutionToolName = Constants.BASH_TOOL;
@@ -117,15 +174,32 @@ function createBashExecutionTool(
 ): DynamicStructuredTool {
   return tool(
     async (rawInput, config) => {
-      const { authHeaders, ...executionParams } = params ?? {};
-      const { command, ...rest } = rawInput as {
+      /* `statefulSessions` is prompt-only — keep it out of the wire body. */
+      const {
+        authHeaders,
+        statefulSessions: _statefulSessions,
+        ...executionParams
+      } = params ?? {};
+      void _statefulSessions;
+      /* Drop any model-supplied `runtime_session_hint` from the raw args: the
+       * hint must only come from ToolNode's injected `_runtime_session_hint`
+       * (below), never from the tool call itself. */
+      const {
+        command,
+        runtime_session_hint: _ignoredModelHint,
+        ...rest
+      } = rawInput as {
         command: string;
+        runtime_session_hint?: unknown;
         args?: string[];
       };
-      const { session_id, _injected_files } = (config.toolCall ?? {}) as {
-        session_id?: string;
-        _injected_files?: t.CodeEnvFile[];
-      };
+      void _ignoredModelHint;
+      const { session_id, _injected_files, _runtime_session_hint } =
+        (config.toolCall ?? {}) as {
+          session_id?: string;
+          _injected_files?: t.CodeEnvFile[];
+          _runtime_session_hint?: string;
+        };
 
       const postData: Record<string, unknown> = {
         lang: 'bash',
@@ -134,6 +208,13 @@ function createBashExecutionTool(
         ...executionParams,
       };
 
+      if (
+        typeof _runtime_session_hint === 'string' &&
+        _runtime_session_hint !== ''
+      ) {
+        postData.runtime_session_hint = _runtime_session_hint;
+      }
+
       /* See `CodeExecutor.ts` for the rationale — `/files/<session_id>`
        * HTTP fallback was removed because codeapi's sessionAuth requires
        * kind/id query params unavailable at this point. */
@@ -187,12 +268,24 @@ function createBashExecutionTool(
           command
         );
         const hasFiles = result.files != null && result.files.length > 0;
+        const runtimeEcho =
+          result.runtime_session_id != null
+            ? {
+              runtime_session_id: result.runtime_session_id,
+              runtime_status: result.runtime_status,
+            }
+            : {};
         return [
           appendCodeSessionFileSummary(outputWithReminder, result.files),
           (hasFiles
-            ? { session_id: result.session_id, files: result.files }
+            ? {
+              session_id: result.session_id,
+              files: result.files,
+              ...runtimeEcho,
+            }
             : {
               session_id: result.session_id,
+              ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,
         ];
       } catch (error) {
@@ -200,15 +293,15 @@ function createBashExecutionTool(
           (error as Error | undefined)?.message ?? '',
           command
         );
-        throw new Error(
-          `Execution error:\n\n${messageWithReminder}`
-        );
+        throw new Error(`Execution error:\n\n${messageWithReminder}`);
       }
     },
     {
       name: BashExecutionToolName,
-      description: BashExecutionToolDescription,
-      schema: BashExecutionToolSchema,
+      description: buildBashExecutionToolDescription({
+        statefulSessions: params?.statefulSessions,
+      }),
+      schema: buildBashExecutionToolSchema(params ?? undefined),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

package/src/tools/BashProgrammaticToolCalling.ts

@@ -304,8 +304,15 @@ export function createBashProgrammaticToolCallingTool(
         Partial<t.ProgrammaticCache> & {
           session_id?: string;
           _injected_files?: t.CodeEnvFile[];
+          _runtime_session_hint?: string;
         };
-      const { toolMap, toolDefs, session_id, _injected_files } = toolCall;
+      const {
+        toolMap,
+        toolDefs,
+        session_id,
+        _injected_files,
+        _runtime_session_hint,
+      } = toolCall;
 
       if (toolMap == null || toolMap.size === 0) {
         throw new Error(
@@ -351,6 +358,15 @@ 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. */
+        const runtimeSessionHint =
+          typeof _runtime_session_hint === 'string' &&
+          _runtime_session_hint !== ''
+            ? _runtime_session_hint
+            : undefined;
+
         let response = await makeRequest(
           EXEC_ENDPOINT,
           {
@@ -360,6 +376,9 @@ export function createBashProgrammaticToolCallingTool(
             session_id,
             timeout,
             ...(files && files.length > 0 ? { files } : {}),
+            ...(runtimeSessionHint != null
+              ? { runtime_session_hint: runtimeSessionHint }
+              : {}),
           },
           proxy,
           initParams.authHeaders