@librechat/agents 3.2.46 → 3.2.52

package/src/llm/openrouter/index.ts

@@ -161,9 +161,7 @@ export class ChatOpenRouter extends ChatOpenAI {
     return 'LibreChatOpenRouter';
   }
 
-  // @ts-expect-error - OpenRouter reasoning extends OpenAI Reasoning with additional
-  // effort levels ('xhigh' | 'none' | 'minimal') not in ReasoningEffort.
-  // The parent's generic conditional return type cannot be widened in an override.
+  // OpenRouter widens OpenAI reasoning with extra effort levels ('xhigh' | 'none' | 'minimal').
   override invocationParams(
     options?: this['ParsedCallOptions'],
     extra?: InvocationParamsExtra

package/src/llm/vertexai/inherited-stream-events.spec.ts

@@ -0,0 +1,271 @@
+// Inherited stream-events specs for the LibreChat Vertex fork, ported from two
+// upstream @langchain/google-common@2.2.0 suites:
+//
+//   1. utils/tests/stream_events.test.ts  (the original prompt references it as
+//      google-common_stream_events.test.ts) — unit tests for the pure converter
+//      `convertGoogleGeminiStream`, which turns Gemini-style stream responses
+//      into LangChain `ChatModelStreamEvent`s. Our fork's `ChatVertexAI` does
+//      not re-implement this converter; it is re-exported from
+//      `@langchain/google-common` and exercised verbatim here as a pure unit.
+//
+//   2. chat_models/tests/chat_models_stream_events.test.ts (the prompt references
+//      it as google-common_chat_models_stream_events.test.ts) — tests
+//      `ChatGoogle.streamEvents()`. Upstream drove a `TestChatGoogle` helper whose
+//      `authOptions.resultFile` replayed recorded mock JSON and asserted via
+//      vitest custom matchers (`toHaveStreamText` / `toHaveStreamReasoning` /
+//      `toHaveStreamToolCalls`). Those fixture files and matchers are not
+//      available in this repo, so each case is routed through OUR fork:
+//      `new ChatVertexAI({...})` (which extends ChatGoogle and inherits the
+//      native `_streamChatModelEvents` path) with the google transport mocked at
+//      the `streamedConnection.request` boundary — it returns `{ data: <json
+//      stream> }`, the exact shape `_streamChatModelEvents` consumes. The matchers
+//      are re-expressed against the public `ChatModelStream` sub-streams
+//      (`.text` / `.reasoning` / `.toolCalls`) that those matchers wrap.
+//
+// All cases are deterministic and run against a mocked transport — no live
+// Vertex access. vitest -> jest, `zod/v3` -> n/a (no zod here).
+
+import { describe, it, test, expect } from '@jest/globals';
+import { convertGoogleGeminiStream } from '@langchain/google-common';
+import { ChatModelStream } from '@langchain/core/language_models/stream';
+import type { BaseChatModelCallOptions } from '@langchain/core/language_models/chat_models';
+import type { ChatModelStreamEvent } from '@langchain/core/language_models/event';
+import { ChatVertexAI } from '@/llm/vertexai';
+
+type GeminiChunk = Record<string, unknown>;
+
+// --- Converter unit-test harness (upstream source 1) -----------------------
+
+async function* asAsyncIterable(
+  chunks: GeminiChunk[]
+): AsyncGenerator<GeminiChunk> {
+  for (const chunk of chunks) {
+    yield chunk;
+  }
+}
+
+async function collectEvents(
+  chunks: GeminiChunk[]
+): Promise<ChatModelStreamEvent[]> {
+  const out: ChatModelStreamEvent[] = [];
+  for await (const event of convertGoogleGeminiStream(
+    asAsyncIterable(chunks)
+  )) {
+    out.push(event);
+  }
+  return out;
+}
+
+// --- Class streamEvents harness (upstream source 2, routed through fork) ----
+
+interface MockJsonStream {
+  readonly streamDone: boolean;
+  nextChunk(): Promise<GeminiChunk | null>;
+}
+
+function makeJsonStream(chunks: GeminiChunk[]): MockJsonStream {
+  let i = 0;
+  return {
+    get streamDone(): boolean {
+      return i >= chunks.length;
+    },
+    async nextChunk(): Promise<GeminiChunk | null> {
+      if (i >= chunks.length) return null;
+      const chunk = chunks[i];
+      i += 1;
+      return chunk;
+    },
+  };
+}
+
+interface StreamedConnectionModel {
+  streamedConnection: {
+    request: () => Promise<{ data: MockJsonStream }>;
+  };
+  _streamChatModelEvents: (
+    messages: unknown[],
+    options: BaseChatModelCallOptions
+  ) => AsyncGenerator<ChatModelStreamEvent>;
+}
+
+function createStreamModel(chunks: GeminiChunk[]): ChatVertexAI {
+  const model = new ChatVertexAI({
+    model: 'gemini-2.0-flash',
+    authOptions: {
+      credentials: { client_email: 'test@example.com', private_key: 'test' },
+      projectId: 'test-project',
+    },
+  } as ConstructorParameters<typeof ChatVertexAI>[0]);
+  (model as unknown as StreamedConnectionModel).streamedConnection.request =
+    async () => ({ data: makeJsonStream(chunks) });
+  return model;
+}
+
+function streamEvents(
+  model: ChatVertexAI,
+  options: BaseChatModelCallOptions = {} as BaseChatModelCallOptions
+): AsyncGenerator<ChatModelStreamEvent> {
+  return (model as unknown as StreamedConnectionModel)._streamChatModelEvents(
+    [],
+    options
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Source 1: convertGoogleGeminiStream (pure converter, re-exported from
+// @langchain/google-common and inherited unchanged by the fork)
+// ---------------------------------------------------------------------------
+
+describe('convertGoogleGeminiStream (inherited from @langchain/google-common)', () => {
+  test('text-only streaming', async () => {
+    const events = await collectEvents([
+      { candidates: [{ content: { parts: [{ text: 'Hello' }] } }] },
+      { candidates: [{ content: { parts: [{ text: ' world' }] } }] },
+    ]);
+
+    const textDeltas = events.filter(
+      (e) =>
+        e.event === 'content-block-delta' &&
+        (e as { delta: { type: string } }).delta.type === 'text-delta'
+    );
+    expect(textDeltas).toHaveLength(2);
+
+    expect(
+      events.find((e) => e.event === 'content-block-finish')
+    ).toMatchObject({
+      content: { text: 'Hello world' },
+    });
+  });
+
+  test('maps Gemini finish reasons', async () => {
+    const lengthEvents = await collectEvents([
+      {
+        candidates: [
+          {
+            content: { parts: [{ text: 'Hello' }] },
+            finishReason: 'MAX_TOKENS',
+          },
+        ],
+      },
+    ]);
+    const lengthFinish = lengthEvents.find((e) => e.event === 'message-finish');
+    expect(lengthFinish).toMatchObject({ reason: 'length' });
+
+    const filterEvents = await collectEvents([
+      {
+        candidates: [
+          {
+            content: { parts: [{ text: 'Hello' }] },
+            finishReason: 'SAFETY',
+          },
+        ],
+      },
+    ]);
+    const filterFinish = filterEvents.find((e) => e.event === 'message-finish');
+    expect(filterFinish).toMatchObject({ reason: 'content_filter' });
+  });
+
+  test('thinking parts map to reasoning', async () => {
+    const events = await collectEvents([
+      {
+        candidates: [
+          {
+            content: { parts: [{ text: 'Let me think', thought: true }] },
+          },
+        ],
+      },
+    ]);
+
+    expect(
+      events.find(
+        (e) =>
+          e.event === 'content-block-finish' &&
+          (e as { content: { type: string } }).content.type === 'reasoning'
+      )
+    ).toMatchObject({
+      content: { reasoning: 'Let me think' },
+    });
+  });
+
+  test('usage snapshots', async () => {
+    const events = await collectEvents([
+      {
+        usageMetadata: {
+          promptTokenCount: 10,
+          candidatesTokenCount: 4,
+          totalTokenCount: 14,
+        },
+        candidates: [{ content: { parts: [{ text: 'Hi' }] } }],
+      },
+    ]);
+
+    expect(events.filter((e) => e.event === 'usage').length).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Source 2: ChatGoogle.streamEvents — inherited native streamEvents path on
+// the fork (ChatVertexAI does not override _streamChatModelEvents). Re-expressed
+// against the public ChatModelStream sub-streams that the upstream vitest
+// matchers wrapped.
+// ---------------------------------------------------------------------------
+
+describe('ChatVertexAI.streamEvents (inherited native path)', () => {
+  test('streams text', async () => {
+    const model = createStreamModel([
+      { candidates: [{ content: { parts: [{ text: 'Hello' }] } }] },
+      {
+        candidates: [
+          { content: { parts: [{ text: ' world' }] }, finishReason: 'STOP' },
+        ],
+      },
+    ]);
+    const stream = new ChatModelStream(streamEvents(model));
+    expect(await stream.text).toBe('Hello world');
+  });
+
+  test('streams reasoning', async () => {
+    const model = createStreamModel([
+      {
+        candidates: [
+          {
+            content: { parts: [{ text: 'Let me reason...', thought: true }] },
+            finishReason: 'STOP',
+          },
+        ],
+      },
+    ]);
+    const stream = new ChatModelStream(streamEvents(model));
+    expect(await stream.reasoning).toBe('Let me reason...');
+  });
+
+  test('streams tool calls', async () => {
+    const model = createStreamModel([
+      {
+        candidates: [
+          {
+            content: {
+              parts: [
+                {
+                  functionCall: {
+                    name: 'web_search',
+                    args: { query: 'weather' },
+                  },
+                },
+              ],
+            },
+            finishReason: 'STOP',
+          },
+        ],
+      },
+    ]);
+    const stream = new ChatModelStream(streamEvents(model));
+    const calls = await stream.toolCalls;
+    expect(calls).toEqual([
+      expect.objectContaining({
+        name: 'web_search',
+        args: { query: 'weather' },
+      }),
+    ]);
+  });
+});

package/src/run.ts

@@ -667,7 +667,7 @@ export class Run<_T extends t.BaseGraphState> {
     const graph = this.Graph;
 
     /**
-     * `Command` inputs (currently only `Command({ resume })`) are
+     * `Command` inputs (`Command({ resume, update?, goto? })`) are
      * resume-mode invocations: LangGraph rebuilds graph state from the
      * checkpointer, so we skip RunStart / UserPromptSubmit hooks (no
      * new prompt to evaluate) and read run-state from the Graph wrapper
@@ -1139,13 +1139,31 @@ export class Run<_T extends t.BaseGraphState> {
     return cp == null ? 0 : cp.rewind();
   }
 
+  /**
+   * Resume an interrupted run. `commandOptions` forwards langgraph 1.4.5
+   * `Command` fields applied together with `resume` in one superstep:
+   * - `update`: channel updates committed at the resume point. On a *rebuilt*
+   *   Run (new instance + durable checkpointer), `update.messages` are the first
+   *   write the fresh wrapper sees, so they seed the `getRunMessages()` /
+   *   `returnContent` baseline and are excluded from them (still committed to the
+   *   checkpoint). Hosts that rebuild + inject messages should persist them
+   *   directly or read from `getState`. Unreachable without a durable checkpointer.
+   * - `goto`: a *dynamic* edge that does not cancel static `addEdge` routes. On
+   *   the built-in standard graph the fixed `toolNode -> agentNode/END` edge still
+   *   fires, so `goto` adds rather than replaces (e.g. `goto: END` will not stop a
+   *   tool-node resume). Intended for custom, Command-routed graphs.
+   */
   async resume<TResume = t.ToolApprovalDecision[] | t.ToolApprovalDecisionMap>(
     resumeValue: TResume,
     callerConfig: Partial<RunnableConfig> & {
       version: 'v1' | 'v2';
       run_id?: string;
     },
-    streamOptions?: t.EventStreamOptions
+    streamOptions?: t.EventStreamOptions,
+    commandOptions?: Pick<
+      ConstructorParameters<typeof Command>[0],
+      'update' | 'goto'
+    >
   ): Promise<MessageContentComplex[] | undefined> {
     const interruptId = this._interrupt?.interruptId;
     const scopedResume =
@@ -1155,8 +1173,18 @@ export class Run<_T extends t.BaseGraphState> {
         ? { [interruptId]: resumeValue }
         : resumeValue;
     const resumeConfig = await this.resolveInterruptResumeConfig(callerConfig);
+    // langgraph 1.4.5 applies resume + state update + reroute in one superstep
+    // (single checkpoint). `update`/`goto` are omitted unless the caller sets them.
     return this.processStream(
-      new Command({ resume: scopedResume }),
+      new Command({
+        resume: scopedResume,
+        ...(commandOptions?.update !== undefined
+          ? { update: commandOptions.update }
+          : {}),
+        ...(commandOptions?.goto !== undefined
+          ? { goto: commandOptions.goto }
+          : {}),
+      }),
       resumeConfig,
       streamOptions
     );

package/src/scripts/handoff-test.ts

@@ -10,10 +10,10 @@ import {
   MessagesAnnotation,
   Command,
   START,
-  getCurrentTaskInput,
   END,
 } from '@langchain/langgraph';
 import { ToolMessage } from '@langchain/core/messages';
+import type { ToolRuntime } from '@langchain/core/tools';
 
 interface CreateHandoffToolParams {
   agentName: string;
@@ -28,16 +28,15 @@ const createHandoffTool = ({
   const toolDescription = description || `Ask agent '${agentName}' for help`;
 
   const handoffTool = tool(
-    async (_, config) => {
+    async (_, runtime: ToolRuntime) => {
       const toolMessage = new ToolMessage({
         content: `Successfully transferred to ${agentName}`,
         name: toolName,
-        tool_call_id: config.toolCall.id,
+        tool_call_id: runtime.toolCallId,
       });
 
-      // inject the current agent state
-      const state =
-        getCurrentTaskInput() as (typeof MessagesAnnotation)['State'];
+      // inject the current agent state via langgraph 1.4 `runtime.state`
+      const state = runtime.state as (typeof MessagesAnnotation)['State'];
       return new Command({
         goto: agentName,
         update: { messages: state.messages.concat(toolMessage) },

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');
+  });
+});