@librechat/agents 3.2.58 → 3.2.60

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":";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;;;;;;;AAiBA,SAAgB,0BACd,eACA,UACoB;CACpB,MAAM,UAAU,eAAe;CAC/B,IAAI,SAAS,qBAAqB,MAChC;CAEF,MAAM,WAAW,QAAQ;CACzB,IAAI,YAAY,QAAQ,aAAa,IACnC,OAAO;CAET,OAAO,YAAY,QAAQ,aAAa,KAAK,WAAW,KAAA;AAC1D;AAQA,SAAgB,8BAA8B,MAKL;CACvC,MAAM,sBAAsB,KAAK,uBAAuB;CACxD,MAAM,WAQD,CAAC;CAEN,KAAK,MAAM,YAAY,KAAK,WAAW;EACrC,IAAI,SAAS,MAAM,QAAQ,SAAS,OAAO,MAAM,SAAS,SAAS,IACjE;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,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;GAC7B,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,IACE,SAAS,sBAAsB,QAC/B,SAAS,uBAAuB,IAEhC,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"}

package/dist/types/graphs/Graph.d.ts

@@ -82,6 +82,14 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
      */
     eagerEventToolExecution: t.EagerEventToolExecutionConfig | undefined;
     codeSessionToolNames: string[] | undefined;
+    /**
+     * Run-scoped names of tools whose in-process body may raise a LangGraph
+     * `interrupt()` (e.g. `ask_user_question`). Threaded from
+     * `RunConfig.interruptingToolNames` into every ToolNode this graph
+     * compiles so a mid-batch interrupt cannot double-execute non-idempotent
+     * siblings on resume. See {@link t.ToolNodeOptions.interruptingToolNames}.
+     */
+    interruptingToolNames: string[] | undefined;
     eagerEventToolExecutions: Map<string, t.EagerEventToolExecution>;
     eagerEventToolUsageCount: Map<string, number>;
     private eagerEventToolUsageCountsByAgentId;
@@ -253,14 +261,24 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     dispatchRunStep(stepKey: string, stepDetails: t.StepDetails, metadata?: Record<string, unknown>): Promise<string>;
     /**
      * Static version of handleToolCallError to avoid creating strong references
-     * that prevent garbage collection
+     * that prevent garbage collection.
+     *
+     * Returns whether the error completion event was actually dispatched. A
+     * tool can error before this graph instance has a run step for the call —
+     * on a resume pass the interrupted batch re-executes IMMEDIATELY on graph
+     * re-entry, before any step replay has registered `toolCallStepIds` (a
+     * fast-failing tool, e.g. a schema-validation reject, loses that race).
+     * That is a caller-recoverable condition, not an invariant violation: the
+     * ToolNode falls back to its normal completion dispatch for the error
+     * ToolMessage when this returns `false`, so throwing here would only
+     * replace a recoverable miss with a lost completion event and a scary log.
      */
-    static handleToolCallErrorStatic(graph: StandardGraph, data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<void>;
+    static handleToolCallErrorStatic(graph: StandardGraph, data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<boolean>;
     /**
      * Instance method that delegates to the static method
      * Kept for backward compatibility
      */
-    handleToolCallError(data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<void>;
+    handleToolCallError(data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<boolean>;
     dispatchRunStepDelta(id: string, delta: t.ToolCallDelta, metadata?: Record<string, unknown>): Promise<void>;
     dispatchMessageDelta(id: string, delta: t.MessageDelta, metadata?: Record<string, unknown>): Promise<void>;
     dispatchReasoningDelta: (stepId: string, delta: t.ReasoningDelta, metadata?: Record<string, unknown>) => Promise<void>;

package/dist/types/run.d.ts

@@ -14,6 +14,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private toolOutputReferences?;
     private eagerEventToolExecution?;
     private codeSessionToolNames?;
+    private interruptingToolNames?;
     private toolExecution?;
     private subagentUsageSink?;
     private indexTokenCountMap?;

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

@@ -67,6 +67,13 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private agentLangfuse?;
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
+    /**
+     * Tool call ids whose `errorHandler` did NOT dispatch the error completion
+     * event (it returned `false` or threw). The output loop must dispatch the
+     * completion for these itself — skipping them there would strand the
+     * client's tool-call part without a terminal event.
+     */
+    private undispatchedToolErrors;
     private toolUsageCount;
     /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
     private toolCallTurns;
@@ -108,6 +115,21 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private executingAgentId?;
     /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
     private directToolNames?;
+    /**
+     * Tool names whose in-process body may raise a LangGraph `interrupt()`
+     * mid-execution (e.g. `ask_user_question`). Used only to REORDER within
+     * the direct group: a tool named here that is *already* direct (a real
+     * in-process graphTool — the only kind whose body can reach
+     * `interrupt()`) is scheduled ahead of its non-interrupting direct
+     * siblings, so a mid-body interrupt unwinds the ToolNode before a
+     * non-idempotent sibling executes and LangGraph's resume-time batch
+     * re-execution can't double it. This set is deliberately NOT folded
+     * into direct classification: a name that resolves to a schema-only
+     * event stub (an inherited `toolDefinition` with no executable
+     * instance) stays event-dispatched — forcing it direct would invoke
+     * the stub, which throws. See {@link t.ToolNodeOptions.interruptingToolNames}.
+     */
+    private interruptingToolNames?;
     /**
      * File checkpointer extracted from the local coding tool bundle when
      * `toolExecution.local.fileCheckpointing === true`. Exposed via
@@ -147,7 +169,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, executingAgentId, directToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, }: t.ToolNodeConstructorParams);
+    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, executingAgentId, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     /**
      * Returns the run-scoped tool output registry, or `undefined` when
@@ -314,6 +336,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
@@ -382,6 +407,40 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * The original role is preserved in additional_kwargs for downstream consumers.
      */
     private convertInjectedMessages;
+    /**
+     * Execute a group of direct (in-process) tool calls with interrupt-safe
+     * ordering, returning outputs aligned 1:1 with `directCalls`.
+     *
+     * Fast path (the common case): when no call in the group is in
+     * `interruptingToolNames`, this is a single `Promise.all` — byte-for-byte
+     * the prior behavior, so ordinary batches are unaffected.
+     *
+     * Interrupt-safe path: when the group contains an interrupting tool (e.g.
+     * `ask_user_question`, whose body raises a LangGraph `interrupt()` to
+     * collect a human answer), the interrupting calls run as their own awaited
+     * group **first**; only after they all settle without interrupting do the
+     * remaining (potentially non-idempotent) siblings run. If an interrupting
+     * call throws a `GraphInterrupt`, the `await` below rejects and unwinds the
+     * whole ToolNode *before* any non-interrupting sibling has started — so a
+     * sibling with real side effects (send_email, billing) never executes on
+     * the first pass. On the resume pass LangGraph re-runs the batch from the
+     * top; the interrupting tool resolves with the host's answer instead of
+     * throwing, and the siblings execute for the FIRST time, exactly once.
+     *
+     * Without this ordering, a flat `Promise.all` starts every sibling
+     * concurrently, so a non-idempotent sibling can complete its side effect
+     * before the interrupt unwinds and then run a SECOND time on resume — the
+     * duplicate side effect this method exists to prevent. Interrupting tools
+     * are expected to be side-effect-free (they only suspend), so running them
+     * as a group and re-running them on resume is harmless.
+     *
+     * `batchIndices[i]` is `directCalls[i]`'s position within the parent
+     * ToolNode batch (used for `{{tool<i>turn<n>}}` registration); it is
+     * preserved regardless of execution order. `baseContext` carries the
+     * batch-scoped fields every call shares; `batchIndex` is filled in
+     * per-call here.
+     */
+    private runDirectBatchInterruptSafe;
     /**
      * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
      * Injected messages are placed AFTER ToolMessages to respect provider

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/hitl.d.ts

@@ -134,6 +134,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;
 }
 /**
  * Structured payload the SDK passes to `interrupt()` when an agent (or
@@ -157,9 +164,10 @@ export type HumanInterruptPayload = ToolApprovalInterruptPayload | AskUserQuesti
 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;
 }
@@ -257,6 +265,44 @@ export declare function isAskUserQuestionInterrupt(payload: unknown): payload is
  * 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/dist/types/types/run.d.ts

@@ -179,6 +179,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/dist/types/types/tools.d.ts

@@ -82,7 +82,15 @@ export type ToolNodeOptions = {
     handleToolErrors?: boolean;
     loadRuntimeTools?: ToolRefGenerator;
     toolCallStepIds?: Map<string, string>;
-    errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<void>;
+    /**
+     * 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<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 */
@@ -98,6 +106,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;
     /**
@@ -278,6 +314,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 +371,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 +433,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 +954,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 +986,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 +1090,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 +1103,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 +1153,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.60",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",