@librechat/agents 3.2.58 → 3.2.60

package/src/specs/tool-error-resume.test.ts

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+import { HumanMessage } from '@langchain/core/messages';
+import { MemorySaver, Command } from '@langchain/langgraph';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { GraphEvents, Providers } from '@/common';
+import { FakeChatModel } from '@/llm/fake';
+import { askUserQuestion } from '@/hitl';
+import { StandardGraph } from '@/graphs';
+import { Run } from '@/run';
+
+/**
+ * Regression: a DIRECT (graphTools) tool that fails schema validation during
+ * the RESUME pass of an interrupted batch.
+ *
+ * LangGraph re-executes the whole interrupted batch on resume, and a
+ * fast-failing sibling (e.g. a zod reject) errors BEFORE the rebuilt graph
+ * has registered run steps for the replayed calls. `handleToolCallErrorStatic`
+ * used to throw (`No config provided`) in that state, which surfaced as a
+ * scary `Error in errorHandler` log on every such resume — the error itself
+ * was already handled (the model receives the error ToolMessage either way).
+ * It now reports `false` (nothing dispatched) so the ToolNode can decide, and
+ * the client-facing contract stays: the error completion event dispatches
+ * exactly ONCE, on the pass where the call's run step is live (the first
+ * pass), never zero times and never twice.
+ */
+const askTool = tool(
+  async (input) => {
+    const { answer } = askUserQuestion(input as { question: string });
+    return answer;
+  },
+  {
+    name: 'ask_user_question',
+    description:
+      'Ask the user a clarifying question and wait for their answer.',
+    schema: z.object({ question: z.string() }),
+  }
+);
+
+const strictTool = tool(
+  async ({ items }: { items: string[] }) => `got ${items.length}`,
+  {
+    name: 'strict_tool',
+    // Array cap mirrors the field repro: an ask_user_question sibling whose
+    // `options` array exceeded the 12-option schema cap.
+    description: 'A tool with a strict array-cap schema.',
+    schema: z.object({ items: z.array(z.string()).max(1) }),
+  }
+);
+
+describe('Direct tool schema error across interrupt/resume', () => {
+  jest.setTimeout(30000);
+
+  const threadConfig: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    streamMode: string;
+  } = {
+    configurable: { thread_id: 'tool-error-resume-thread' },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  const completedToolEvents: Array<{ name?: string; output?: string }> = [];
+  const customHandlers = {
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (_event: GraphEvents, data: t.StreamEventData): void => {
+        const result = (data as { result?: t.ToolCompleteEvent }).result;
+        if (result?.type === 'tool_call') {
+          completedToolEvents.push({
+            name: result.tool_call.name,
+            output: result.tool_call.output,
+          });
+        }
+      },
+    },
+  };
+
+  async function buildRun(
+    saver: MemorySaver,
+    runId: string
+  ): Promise<Run<t.IState>> {
+    const run = await Run.create<t.IState>({
+      runId,
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'resume-error-agent',
+            provider: Providers.OPENAI,
+            clientOptions: {
+              model: 'gpt-4o-mini',
+              streaming: true,
+              streamUsage: false,
+            },
+            instructions: 'You are a helpful assistant.',
+            maxContextTokens: 8000,
+            /** Non-empty toolDefinitions flips the ToolNode to event dispatch —
+             *  the production shape — while graphTools ride the direct path. */
+            toolDefinitions: [
+              { name: 'dummy_event_tool', description: 'host tool' },
+            ],
+            graphTools: [askTool, strictTool],
+          },
+        ],
+        compileOptions: { checkpointer: saver },
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers,
+      eagerEventToolExecution: {
+        enabled: true,
+        excludeToolNames: ['ask_user_question', 'strict_tool'],
+      },
+    });
+    run.Graph!.overrideModel = new FakeChatModel({
+      responses: ['calling tools', 'done after resume'],
+      toolCalls: [
+        {
+          name: 'ask_user_question',
+          args: { question: 'pick one' },
+          id: 'call_ask_1',
+          type: 'tool_call',
+        },
+        {
+          name: 'strict_tool',
+          args: { items: ['a', 'b', 'c'] },
+          id: 'call_strict_1',
+          type: 'tool_call',
+        },
+      ],
+    });
+    return run;
+  }
+
+  test('error completion dispatches exactly once; resume-pass handler reports false instead of throwing', async () => {
+    const saver = new MemorySaver();
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const staticSpy = jest.spyOn(StandardGraph, 'handleToolCallErrorStatic');
+
+    try {
+      /** Pass 1: the strict tool rejects its args while the ask tool
+       *  interrupts — the run pauses AND the schema error completes. */
+      const run1 = await buildRun(saver, 'run-pass-1');
+      await run1.processStream(
+        { messages: [new HumanMessage('go')] },
+        threadConfig
+      );
+
+      const strictCompletions = completedToolEvents.filter(
+        (e) =>
+          e.name === 'strict_tool' &&
+          e.output?.includes('Error processing tool') === true
+      );
+      expect(strictCompletions).toHaveLength(1);
+      // Stable LangChain wrapper text (version-independent), proving the
+      // completion carried the schema-validation failure.
+      expect(strictCompletions[0].output).toContain(
+        'did not match expected schema'
+      );
+
+      /** Pass 2: fresh instance (host restart shape), resume with the
+       *  answer. The batch re-executes; the strict tool fails again before
+       *  any run step is registered on the rebuilt graph. */
+      const run2 = await buildRun(saver, 'run-pass-2');
+      await run2.processStream(
+        new Command({ resume: { answer: 'blue' } }) as unknown as t.IState,
+        threadConfig
+      );
+
+      /** The handler reported "not dispatched" (no run step yet) rather than
+       *  throwing — so nothing was logged and no duplicate completion event
+       *  reached the client. */
+      const resumeResults = await Promise.all(
+        staticSpy.mock.results.map((r) => r.value as Promise<boolean>)
+      );
+      expect(resumeResults).toContain(false);
+      const handlerFailures = errorSpy.mock.calls.filter((args) =>
+        String(args[0]).includes('Error in errorHandler')
+      );
+      expect(handlerFailures).toHaveLength(0);
+      expect(
+        completedToolEvents.filter(
+          (e) =>
+            e.name === 'strict_tool' &&
+            e.output?.includes('Error processing tool') === true
+        )
+      ).toHaveLength(1);
+    } finally {
+      errorSpy.mockRestore();
+      staticSpy.mockRestore();
+    }
+  });
+});

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

package/src/tools/CodeExecutor.ts

@@ -149,6 +149,64 @@ Usage:
 - NEVER use this tool to execute malicious code.
 `.trim();
 
+/**
+ * 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 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 const StatefulCodeExecutionToolDescription = `
+Runs code and returns stdout/stderr output from a session-based execution environment, similar to a long-running command-line session.
+
+${STATEFUL_ENV_NOTE}
+
+Usage:
+- No network access available.
+- Generated files are automatically delivered; **DO NOT** provide download links.
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
+- NEVER use this tool to execute malicious code.
+`.trim();
+
+export function buildCodeExecutionToolDescription(opts?: {
+  statefulSessions?: boolean;
+}): string {
+  return opts?.statefulSessions === true
+    ? StatefulCodeExecutionToolDescription
+    : CodeExecutionToolDescription;
+}
+
+const STATELESS_CODE_PARAM_NOTE =
+  'The environment is stateless; variables and imports don\'t persist between executions.';
+const STATEFUL_CODE_PARAM_NOTE =
+  'Executions in this conversation usually share one runtime: variables and imports from prior successful calls are typically still defined, but the runtime may reset between calls. Rebuild state on NameError/ImportError; persist anything important to /mnt/data.';
+
+export function buildCodeExecutionToolSchema(opts?: {
+  statefulSessions?: boolean;
+}): typeof CodeExecutionToolSchema {
+  const note =
+    opts?.statefulSessions === true
+      ? STATEFUL_CODE_PARAM_NOTE
+      : STATELESS_CODE_PARAM_NOTE;
+  const codeDescription =
+    CodeExecutionToolSchema.properties.code.description.replace(
+      STATELESS_CODE_PARAM_NOTE,
+      note
+    );
+  return {
+    ...CodeExecutionToolSchema,
+    properties: {
+      ...CodeExecutionToolSchema.properties,
+      code: {
+        ...CodeExecutionToolSchema.properties.code,
+        description: codeDescription,
+      },
+    },
+  } as typeof CodeExecutionToolSchema;
+}
+
 export const CodeExecutionToolName = Constants.EXECUTE_CODE;
 
 export const CodeExecutionToolDefinition = {
@@ -162,21 +220,42 @@ function createCodeExecutionTool(
 ): DynamicStructuredTool {
   return tool(
     async (rawInput, config) => {
-      const { authHeaders, ...executionParams } = params ?? {};
-      const { lang, code, ...rest } = rawInput as {
+      /* `statefulSessions` is a prompt-only flag (drives the description);
+       * 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 is host-controlled and must only ever come from ToolNode's
+       * injected `_runtime_session_hint` (below). Spreading `...rest` into
+       * postData would otherwise let a tool call opt itself into / pick a
+       * stateful runtime even when statefulSessions is off. */
+      const {
+        lang,
+        code,
+        runtime_session_hint: _ignoredModelHint,
+        ...rest
+      } = rawInput as {
         lang: SupportedLanguage;
         code: string;
+        runtime_session_hint?: unknown;
         args?: string[];
       };
+      void _ignoredModelHint;
       /**
        * Extract session context from config.toolCall (injected by ToolNode).
        * - session_id: associates with the previous run.
        * - _injected_files: File refs to pass directly (avoids /files endpoint race condition).
        */
-      const { session_id, _injected_files } = (config.toolCall ?? {}) as {
-        session_id?: string;
-        _injected_files?: t.CodeEnvFile[];
-      };
+      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,
@@ -185,6 +264,16 @@ function createCodeExecutionTool(
         ...executionParams,
       };
 
+      /* Stateful sessions: forward the hint so the Code API can route this
+       * execution to a warm per-session runtime. Additive — stateless
+       * servers ignore the unknown field. */
+      if (
+        typeof _runtime_session_hint === 'string' &&
+        _runtime_session_hint !== ''
+      ) {
+        postData.runtime_session_hint = _runtime_session_hint;
+      }
+
       /* File injection: `_injected_files` from ToolNode (set when host
        * primes a CodeSessionContext) or `params.files` from tool
        * factory (set by hosts that pre-resolve at construction time).
@@ -242,12 +331,27 @@ function createCodeExecutionTool(
           code
         );
         const hasFiles = result.files != null && result.files.length > 0;
+        /* Echo the durable runtime session (stateful backends only) so hosts
+         * can surface a "session active / was reset" signal later. Additive:
+         * absent on stateless servers. */
+        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) {
@@ -260,8 +364,8 @@ function createCodeExecutionTool(
     },
     {
       name: CodeExecutionToolName,
-      description: CodeExecutionToolDescription,
-      schema: CodeExecutionToolSchema,
+      description: buildCodeExecutionToolDescription(params ?? undefined),
+      schema: buildCodeExecutionToolSchema(params ?? undefined),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

package/src/tools/ProgrammaticToolCalling.ts

@@ -830,6 +830,12 @@ export function formatCompletedResponse(
     {
       session_id: response.session_id,
       files: response.files,
+      ...(response.runtime_session_id != null
+        ? {
+          runtime_session_id: response.runtime_session_id,
+          runtime_status: response.runtime_status,
+        }
+        : {}),
     } satisfies t.ProgrammaticExecutionArtifact,
   ];
 }
@@ -878,8 +884,15 @@ export function createProgrammaticToolCallingTool(
         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(
@@ -928,6 +941,16 @@ export function createProgrammaticToolCallingTool(
           );
         }
 
+        /* Stateful sessions: hint rides the INITIAL request only; the server
+         * binds continuation round-trips to the same runtime via the
+         * continuation_token. Additive — ignored by stateless servers. PTC
+         * keeps its stateless prompt in v1; only the wire hint plumbs here. */
+        const runtimeSessionHint =
+          typeof _runtime_session_hint === 'string' &&
+          _runtime_session_hint !== ''
+            ? _runtime_session_hint
+            : undefined;
+
         let response = await makeRequest(
           EXEC_ENDPOINT,
           {
@@ -936,6 +959,9 @@ export function createProgrammaticToolCallingTool(
             session_id,
             timeout,
             ...(files && files.length > 0 ? { files } : {}),
+            ...(runtimeSessionHint != null
+              ? { runtime_session_hint: runtimeSessionHint }
+              : {}),
           },
           proxy,
           initParams.authHeaders