@librechat/agents 3.2.51 → 3.2.53

package/src/tools/ToolNode.ts

@@ -19,8 +19,12 @@ import type {
   RunnableConfig,
   RunnableToolLike,
 } from '@langchain/core/runnables';
+import type {
+  ToolRuntime,
+  StructuredToolInterface,
+} from '@langchain/core/tools';
 import type { BaseMessage, AIMessage } from '@langchain/core/messages';
-import type { StructuredToolInterface } from '@langchain/core/tools';
+import type { LangGraphRunnableConfig } from '@langchain/langgraph';
 import type {
   ToolOutputResolveView,
   PreResolvedArgsMap,
@@ -65,7 +69,7 @@ import { executeHooks } from '@/hooks';
  * batch-scoped value the method needs so the signature stays at
  * three positional parameters even as new context fields are added.
  */
-type RunToolBatchContext = {
+type RunToolBatchContext<T = unknown> = {
   /** Position of this call within the parent ToolNode batch. */
   batchIndex?: number;
   /** Batch turn shared across every call in the batch. */
@@ -104,6 +108,13 @@ type RunToolBatchContext = {
    * contract for hosts relying on it for policy / recovery guidance.
    */
   additionalContextsSink?: string[];
+  /**
+   * Graph state the ToolNode was invoked with, threaded from `run()`
+   * so `tool.invoke` can forward it as langgraph 1.4's `runtime.state`
+   * (the deprecation-free replacement for `getCurrentTaskInput()`,
+   * which relies on `node:async_hooks` and is browser-incompatible).
+   */
+  runInput?: T;
 };
 
 const TOOL_NODE_RUN_NAME = 'tool_batch';
@@ -798,7 +809,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   protected async runTool(
     call: ToolCall,
     config: RunnableConfig,
-    batchContext: RunToolBatchContext = {}
+    batchContext: RunToolBatchContext<T> = {}
   ): Promise<BaseMessage | Command> {
     const {
       batchIndex,
@@ -806,6 +817,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       batchScopeId,
       resolvedArgsByCallId,
       preBatchSnapshot,
+      runInput,
     } = batchContext;
     const tool = this.toolMap.get(call.name);
     const registry = this.toolOutputRegistry;
@@ -980,7 +992,27 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         }
       }
 
-      const output = await tool.invoke(invokeParams, config);
+      /**
+       * Forward the graph state as langgraph 1.4's `runtime.state` so
+       * tools can read it off their second argument instead of the
+       * deprecated `getCurrentTaskInput()` (which relies on
+       * `node:async_hooks` and is browser-incompatible). Shape mirrors
+       * langgraph's prebuilt ToolNode runtime exactly.
+       */
+      const lgConfig = config as LangGraphRunnableConfig;
+      const runtime: ToolRuntime<T> = {
+        ...config,
+        state: runInput as ToolRuntime<T>['state'],
+        toolCallId: call.id ?? '',
+        config,
+        context: lgConfig.context as ToolRuntime<T>['context'],
+        store: (lgConfig.store ?? null) as ToolRuntime<T>['store'],
+        writer:
+          lgConfig.writer ??
+          (config.configurable?.writer as ToolRuntime<T>['writer']) ??
+          null,
+      };
+      const output = await tool.invoke(invokeParams, runtime);
       if (isCommand(output)) {
         return output;
       }
@@ -1192,7 +1224,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private async runDirectToolWithLifecycleHooks(
     call: ToolCall,
     config: RunnableConfig,
-    batchContext: RunToolBatchContext = {}
+    batchContext: RunToolBatchContext<T> = {}
   ): Promise<BaseMessage | Command> {
     const runId = (config.configurable?.run_id as string | undefined) ?? '';
     const hookRegistry = this.hookRegistry;
@@ -3162,6 +3194,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       // branch, so direct tools dispatched via Send (a supported
       // input shape) still silently dropped hook context.
       const directAdditionalContexts: string[] = [];
+      // Mirror langgraph's prebuilt ToolNode: the Send-input state is
+      // the input minus the `lg_tool_call` envelope key.
+      const { lg_tool_call: _sendToolCall, ...sendState } = input;
       const sendOutput = await this.runDirectToolWithLifecycleHooks(
         input.lg_tool_call,
         config,
@@ -3171,6 +3206,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           batchScopeId,
           resolvedArgsByCallId,
           additionalContextsSink: directAdditionalContexts,
+          runInput: sendState as T,
         }
       );
       outputs =
@@ -3343,6 +3379,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
                   resolvedArgsByCallId,
                   preBatchSnapshot,
                   additionalContextsSink: directAdditionalContexts,
+                  runInput: input as T,
                 })
               )
             )
@@ -3407,6 +3444,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               resolvedArgsByCallId,
               preBatchSnapshot,
               additionalContextsSink: directAdditionalContexts,
+              runInput: input as T,
             })
           )
         );

package/src/tools/__tests__/ToolNode.runtimeState.test.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+import { describe, it, expect } from '@jest/globals';
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ToolRuntime } from '@langchain/core/tools';
+import { ToolNode } from '../ToolNode';
+
+type CapturedRuntime = {
+  state: unknown;
+  toolCallId: string;
+  toolCallIdFromConfig: string | undefined;
+};
+
+/**
+ * Tool that records the langgraph runtime it received as its second
+ * argument. Proves our forked ToolNode forwards `runtime.state` (the
+ * deprecation-free replacement for `getCurrentTaskInput()`).
+ */
+function createRuntimeProbeTool(captured: CapturedRuntime[]) {
+  return tool(
+    async (_input, runtime: ToolRuntime) => {
+      captured.push({
+        state: runtime.state,
+        toolCallId: runtime.toolCallId,
+        toolCallIdFromConfig: runtime.toolCall?.id,
+      });
+      return 'ok';
+    },
+    {
+      name: 'probe_runtime',
+      description: 'Records the runtime forwarded by the ToolNode',
+      schema: z.object({ value: z.string() }),
+    }
+  );
+}
+
+function aiMessageWithProbeCall(callId: string): AIMessage {
+  return new AIMessage({
+    content: '',
+    tool_calls: [
+      {
+        id: callId,
+        name: 'probe_runtime',
+        args: { value: 'hello' },
+      },
+    ],
+  });
+}
+
+describe('ToolNode runtime.state forwarding (langgraph 1.4)', () => {
+  it('forwards the message-state input as runtime.state', async () => {
+    const captured: CapturedRuntime[] = [];
+    const toolNode = new ToolNode({
+      tools: [createRuntimeProbeTool(captured)],
+    });
+
+    const messages: BaseMessage[] = [
+      new HumanMessage('start'),
+      aiMessageWithProbeCall('call_1'),
+    ];
+    const input = { messages };
+
+    await toolNode.invoke(input);
+
+    expect(captured).toHaveLength(1);
+    /* state is the exact run input object the ToolNode was invoked with */
+    expect(captured[0].state).toBe(input);
+    expect((captured[0].state as { messages: BaseMessage[] }).messages).toBe(
+      messages
+    );
+    /* toolCallId and the langchain-extracted toolCall both resolve */
+    expect(captured[0].toolCallId).toBe('call_1');
+    expect(captured[0].toolCallIdFromConfig).toBe('call_1');
+  });
+
+  it('forwards the array-shaped input as runtime.state', async () => {
+    const captured: CapturedRuntime[] = [];
+    const toolNode = new ToolNode({
+      tools: [createRuntimeProbeTool(captured)],
+    });
+
+    const input: BaseMessage[] = [
+      new HumanMessage('start'),
+      aiMessageWithProbeCall('call_2'),
+    ];
+
+    await toolNode.invoke(input);
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0].state).toBe(input);
+    expect(captured[0].toolCallId).toBe('call_2');
+  });
+
+  it('forwards the de-enveloped state for Send-shaped input', async () => {
+    const captured: CapturedRuntime[] = [];
+    const toolNode = new ToolNode({
+      tools: [createRuntimeProbeTool(captured)],
+    });
+
+    const sidecar = { tenant: 'acme' };
+    await toolNode.invoke({
+      lg_tool_call: {
+        id: 'call_3',
+        name: 'probe_runtime',
+        args: { value: 'hi' },
+        type: 'tool_call',
+      },
+      ...sidecar,
+    });
+
+    expect(captured).toHaveLength(1);
+    /* The `lg_tool_call` envelope key is stripped, the rest is state */
+    expect(captured[0].state).toEqual(sidecar);
+    expect(
+      (captured[0].state as Record<string, unknown>).lg_tool_call
+    ).toBeUndefined();
+    expect(captured[0].toolCallId).toBe('call_3');
+  });
+});

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

@@ -761,6 +761,221 @@ describe('Run integration — HITL fallback checkpointer + resume', () => {
     expect(run.Graph?.compileOptions?.checkpointer).toBe(hostCheckpointer);
   });
 
+  it('processStream defaults durability to "exit" when a checkpointer is active', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'durability-exit-default',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+      },
+      humanInTheLoop: { enabled: true },
+    });
+    expect(run.Graph?.compileOptions?.checkpointer).toBeInstanceOf(MemorySaver);
+
+    const graph = new StateGraph(MessagesAnnotation)
+      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
+      .addEdge(START, 'noop')
+      .addEdge('noop', END)
+      .compile();
+    const spy = jest.spyOn(graph, 'streamEvents');
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    await run.processStream(
+      { messages: [] },
+      { version: 'v2', configurable: { thread_id: 't' } }
+    );
+
+    const streamedConfig = spy.mock.calls[0]?.[1] as
+      | t.RunStreamConfig
+      | undefined;
+    expect(streamedConfig?.durability).toBe('exit');
+  });
+
+  it('processStream respects an explicit caller durability over the checkpointer default', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'durability-explicit-override',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+      },
+      humanInTheLoop: { enabled: true },
+    });
+
+    const graph = new StateGraph(MessagesAnnotation)
+      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
+      .addEdge(START, 'noop')
+      .addEdge('noop', END)
+      .compile();
+    const spy = jest.spyOn(graph, 'streamEvents');
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    await run.processStream(
+      { messages: [] },
+      { version: 'v2', durability: 'sync', configurable: { thread_id: 't' } }
+    );
+
+    const streamedConfig = spy.mock.calls[0]?.[1] as
+      | t.RunStreamConfig
+      | undefined;
+    expect(streamedConfig?.durability).toBe('sync');
+  });
+
+  it('processStream leaves durability unset when no checkpointer is active', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'durability-no-checkpointer',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+      },
+      // humanInTheLoop omitted — no checkpointer installed
+    });
+    expect(run.Graph?.compileOptions?.checkpointer).toBeUndefined();
+
+    const graph = new StateGraph(MessagesAnnotation)
+      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
+      .addEdge(START, 'noop')
+      .addEdge('noop', END)
+      .compile();
+    const spy = jest.spyOn(graph, 'streamEvents');
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    await run.processStream(
+      { messages: [] },
+      { version: 'v2', configurable: { thread_id: 't' } }
+    );
+
+    const streamedConfig = spy.mock.calls[0]?.[1] as
+      | t.RunStreamConfig
+      | undefined;
+    expect(streamedConfig?.durability).toBeUndefined();
+  });
+
+  it('defaults durability to "exit" when HITL installs the fallback checkpointer but caller compileOptions omit it', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'durability-hitl-fallback-compileopts',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+        // Caller compileOptions without a checkpointer: HITL adds a MemorySaver
+        // fallback to the compiled graph, but the constructor restores this raw
+        // metadata (no checkpointer) onto Graph.compileOptions.
+        compileOptions: { interruptBefore: [] },
+      },
+      humanInTheLoop: { enabled: true },
+    });
+    expect(run.Graph?.compileOptions?.checkpointer).toBeUndefined();
+
+    const graph = new StateGraph(MessagesAnnotation)
+      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
+      .addEdge(START, 'noop')
+      .addEdge('noop', END)
+      .compile();
+    const spy = jest.spyOn(graph, 'streamEvents');
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    await run.processStream(
+      { messages: [] },
+      { version: 'v2', configurable: { thread_id: 't' } }
+    );
+
+    const streamedConfig = spy.mock.calls[0]?.[1] as
+      | t.RunStreamConfig
+      | undefined;
+    expect(streamedConfig?.durability).toBe('exit');
+  });
+
+  it('Run.resume forwards update + goto into the resume Command (langgraph 1.4.5)', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'hitl-resume-update-goto',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+      },
+    });
+
+    const spy = jest.spyOn(run, 'processStream').mockResolvedValue(undefined);
+
+    const decision = [{ type: 'approve' as const }];
+    const update = { messages: [new AIMessage('host-edit')] };
+    await run.resume(
+      decision,
+      { version: 'v1', configurable: { thread_id: 't' } },
+      undefined,
+      { update, goto: 'agent' }
+    );
+
+    const cmd = spy.mock.calls[0]?.[0] as Command;
+    expect(cmd).toBeInstanceOf(Command);
+    // No interrupt was captured, so the resume value passes through unscoped.
+    expect(cmd.resume).toEqual(decision);
+    expect(cmd.update).toEqual(update);
+    expect(cmd.goto).toEqual(['agent']); // langgraph normalizes goto to an array
+
+    // Backward-compat: omitting commandOptions leaves update unset, goto empty.
+    await run.resume(decision, {
+      version: 'v1',
+      configurable: { thread_id: 't' },
+    });
+    const cmd2 = spy.mock.calls[1]?.[0] as Command;
+    expect(cmd2.update).toBeUndefined();
+    expect(cmd2.goto).toEqual([]);
+  });
+
   it('re-exports langgraph HITL primitives from the SDK barrel for host use', async () => {
     const indexExports = await import('@/index');
     expect(indexExports.MemorySaver).toBe(MemorySaver);
@@ -903,6 +1118,120 @@ describe('Run integration — HITL fallback checkpointer + resume', () => {
     expect(run.getHaltReason()).toBeUndefined();
   });
 
+  it('Run.resume() forwards `update` so langgraph applies the channel edit through streamEvents', async () => {
+    /** Executing proof (not a spy): interrupt on a tool, resume with an
+     * injected message via `update`, then read the committed checkpoint.
+     * langgraph 1.4.5 maps an INPUT resume Command through `mapCommand`
+     * (pregel/io.js), which applies resume AND update AND goto, so the
+     * injected message must land in the messages channel. */
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data) => {
+        if (event !== 'on_tool_execute') {
+          return;
+        }
+        const request = data as {
+          toolCalls: t.ToolCallRequest[];
+          resolve: (r: t.ToolExecuteResult[]) => void;
+        };
+        request.resolve(
+          request.toolCalls.map((c) => ({
+            toolCallId: c.id,
+            content: 'host-result',
+            status: 'success' as const,
+          }))
+        );
+      });
+
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async (): Promise<PreToolUseHookOutput> => ({
+          decision: 'ask',
+          reason: 'review',
+        }),
+      ],
+    });
+
+    const hexToolCallId = '0123456789abcdef0123456789abcdef';
+    const node = new ToolNode({
+      tools: [createSchemaStub('echo')],
+      eventDrivenMode: true,
+      agentId: 'agent-x',
+      toolCallStepIds: new Map([[hexToolCallId, 'step_1']]),
+      hookRegistry: registry,
+      humanInTheLoop: { enabled: true },
+    });
+
+    const builder = new StateGraph(MessagesAnnotation)
+      .addNode(
+        'agent',
+        (): MessagesUpdate => ({
+          messages: [
+            new AIMessage({
+              content: '',
+              tool_calls: [
+                { id: hexToolCallId, name: 'echo', args: { command: 'x' } },
+              ],
+            }),
+          ],
+        })
+      )
+      .addNode('tools', node)
+      .addEdge(START, 'agent')
+      .addEdge('agent', 'tools')
+      .addEdge('tools', END);
+    const graph = builder.compile({ checkpointer: new MemorySaver() });
+
+    const { Run } = await import('@/run');
+    const { HumanMessage } = await import('@langchain/core/messages');
+    const run = await Run.create<t.IState>({
+      runId: 'run-resume-update',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+      },
+      hooks: registry,
+      humanInTheLoop: { enabled: true },
+    });
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    const callerConfig = {
+      configurable: { thread_id: 'run-resume-update-thread' },
+      version: 'v2' as const,
+    };
+
+    await run.processStream({ messages: [] }, callerConfig);
+    expect(run.getInterrupt()).toBeDefined();
+
+    const injected = new HumanMessage({ content: 'human-injected-on-resume' });
+    await run.resume(
+      { [hexToolCallId]: { type: 'approve' } },
+      callerConfig,
+      undefined,
+      { update: { messages: [injected] } }
+    );
+
+    expect(run.getInterrupt()).toBeUndefined();
+
+    const state = await graph.getState(callerConfig);
+    const contents = (state.values.messages as BaseMessage[]).map(
+      (m) => m.content
+    );
+    /** Proves langgraph honored `update` on the INPUT resume Command. */
+    expect(contents).toContain('human-injected-on-resume');
+    /** Resume itself still completed: the approved tool produced its result. */
+    expect(contents).toContain('host-result');
+  });
+
   it('Run.getHaltReason() reports prompt_denied when UserPromptSubmit denies the prompt', async () => {
     const registry = new HookRegistry();
     registry.register('UserPromptSubmit', {

package/src/types/run.ts

@@ -261,3 +261,22 @@ export type EventStreamOptions = {
   callbacks?: g.ClientCallbacks;
   keepContent?: boolean;
 };
+
+/**
+ * When to persist checkpoints during a run. Mirrors langgraph's option:
+ * `'async'`/`'sync'` checkpoint every superstep; `'exit'` checkpoints only
+ * at the graph's exit/interrupt boundary. Kept as a local union to avoid
+ * coupling to langgraph internals (it is not exported from the root).
+ */
+export type Durability = 'async' | 'sync' | 'exit';
+
+/**
+ * Config accepted by `processStream`/`resume`. Extends `RunnableConfig` with
+ * the stream `version`, an optional `run_id`, and an optional `durability`
+ * override forwarded to langgraph's run options.
+ */
+export type RunStreamConfig = Partial<RunnableConfig> & {
+  version: 'v1' | 'v2';
+  run_id?: string;
+  durability?: Durability;
+};