@librechat/agents 3.2.54 → 3.2.56

package/dist/types/llm/truncation.d.ts

@@ -0,0 +1,45 @@
+import type { AIMessageChunk, BaseMessage } from '@langchain/core/messages';
+import { Providers } from '@/common';
+/**
+ * Normalized truncation reasons across providers. Providers disagree on the
+ * key and the value: Anthropic/Bedrock use `max_tokens`, OpenAI uses `length`,
+ * Google uses `MAX_TOKENS`.
+ */
+export type TruncationStopReason = 'max_tokens' | 'length';
+/**
+ * Reads the truncation stop reason off a message, covering every provider
+ * shape we stream:
+ * - `response_metadata.stopReason` (Bedrock Converse, non-streaming)
+ * - `response_metadata.messageStop.stopReason` (Bedrock Converse streaming)
+ * - `response_metadata.stop_reason` (Anthropic, non-streaming)
+ * - `additional_kwargs.stop_reason` (Anthropic streaming `message_delta`)
+ * - `response_metadata.finish_reason` (OpenAI chat-completions / compatible)
+ * - `response_metadata.incomplete_details.reason` (OpenAI Responses API)
+ * - `response_metadata.finishReason` (Google)
+ *
+ * Returns the normalized reason when the model stopped because it hit the
+ * output token ceiling, otherwise `null`.
+ */
+export declare function getTruncationStopReason(message: Pick<BaseMessage, 'response_metadata' | 'additional_kwargs'> | undefined | null): TruncationStopReason | null;
+/**
+ * Error raised when a model turn is cut off by the output token limit while it
+ * was still emitting a tool call. The arguments are necessarily incomplete, so
+ * executing or re-prompting the call would loop on a malformed request. Failing
+ * fast with this surfaces an actionable message to the caller instead.
+ */
+export declare class OutputTruncationError extends Error {
+    readonly stopReason: TruncationStopReason;
+    readonly toolCallNames: string[];
+    constructor(stopReason: TruncationStopReason, toolCallNames: string[]);
+}
+/**
+ * Throws {@link OutputTruncationError} when `message` was truncated by the
+ * output token limit AND still carries a tool call. For providers that stream
+ * tool arguments incrementally (Anthropic, Bedrock, OpenAI), a tool call
+ * emitted under truncation has incomplete arguments — the tool-use block is the
+ * last thing the model streams — so letting it through makes the agent loop on a
+ * malformed call. No-ops for normal completions, truncated plain-text turns, and
+ * providers that deliver complete tool calls atomically (Google/Vertex), where
+ * `MAX_TOKENS` does not imply the arguments were cut off.
+ */
+export declare function assertNotTruncatedToolCall(message: AIMessageChunk | BaseMessage | undefined | null, provider?: Providers): void;

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

@@ -31,6 +31,16 @@ export type EagerEventToolExecutionConfig = {
      * ToolMessages so provider message ordering is preserved.
      */
     enabled?: boolean;
+    /**
+     * Tool names that must never be started eagerly. Eager execution
+     * speculates on tool args before the model turn commits, so
+     * side-effecting tools (e.g. file writes) should opt out: a
+     * speculative write can land even if the turn is superseded, and a
+     * later arg revision would otherwise trip the "changed after eager
+     * execution" guard. Excluded calls fall through to normal ToolNode
+     * execution with final args.
+     */
+    excludeToolNames?: string[];
 };
 export type EagerEventToolExecutionOutcome = {
     results: ToolExecuteResult[];

package/package.json

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

package/src/__tests__/stream.eagerEventExecution.test.ts

@@ -4726,4 +4726,104 @@ describe('ChatModelStreamHandler eager event tool execution', () => {
     expect(toolExecuteCalls).toHaveLength(0);
     expect(graph.eagerEventToolExecutions.size).toBe(0);
   });
+
+  it('does not prestart tools listed in excludeToolNames', async () => {
+    const graph = createGraph({
+      eagerEventToolExecution: {
+        enabled: true,
+        excludeToolNames: ['create_file'],
+      },
+    });
+    const toolExecuteCalls: t.ToolExecuteBatchRequest[] = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        const batch = data as t.ToolExecuteBatchRequest;
+        toolExecuteCalls.push(batch);
+        batch.resolve([
+          { toolCallId: 'call_file', status: 'success', content: 'ok' },
+        ]);
+      });
+
+    await new ChatModelStreamHandler().handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_calls: [
+            {
+              id: 'call_file',
+              name: 'create_file',
+              args: { path: '/mnt/data/x.py', content: 'print(1)' },
+            },
+          ],
+          response_metadata: finalToolCallResponseMetadata,
+        } as unknown as t.StreamChunk,
+      },
+      { langgraph_node: 'agent' },
+      graph
+    );
+
+    // Excluded: no eager execution started; the call falls through to ToolNode.
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(graph.eagerEventToolExecutions.has('call_file')).toBe(false);
+  });
+
+  it('keeps the direct-tool batch guard when an excluded tool is also direct', async () => {
+    // edit_file is both a direct graph tool AND excluded from eager. A mixed
+    // batch with a direct tool must suppress eager for the whole batch, so the
+    // sibling event tool must NOT prestart — excluding edit_file must not hide
+    // it from the batch-level direct-tool guard.
+    const graph = createGraph({
+      eagerEventToolExecution: {
+        enabled: true,
+        excludeToolNames: ['edit_file'],
+      },
+      getAgentContext: jest.fn(() => ({
+        provider: Providers.ANTHROPIC,
+        reasoningKey: 'reasoning',
+        toolDefinitions: [{ name: 'weather' }, { name: 'edit_file' }],
+        graphTools: [{ name: 'edit_file' }],
+        agentId: 'agent_1',
+      })) as unknown as StandardGraph['getAgentContext'],
+    });
+    const toolExecuteCalls: t.ToolExecuteBatchRequest[] = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        toolExecuteCalls.push(data as t.ToolExecuteBatchRequest);
+        (data as t.ToolExecuteBatchRequest).resolve([]);
+      });
+
+    await new ChatModelStreamHandler().handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_calls: [
+            { id: 'call_weather', name: 'weather', args: { city: 'NYC' } },
+            {
+              id: 'call_edit',
+              name: 'edit_file',
+              args: { path: '/mnt/data/x.py' },
+            },
+          ],
+          response_metadata: finalToolCallResponseMetadata,
+        } as unknown as t.StreamChunk,
+      },
+      { langgraph_node: 'agent' },
+      graph
+    );
+
+    // Direct tool in batch suppresses eager for the whole batch.
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(graph.eagerEventToolExecutions.has('call_weather')).toBe(false);
+    expect(graph.eagerEventToolExecutions.has('call_edit')).toBe(false);
+  });
 });

package/src/llm/invoke.ts

@@ -6,6 +6,7 @@ import type { BaseMessage } from '@langchain/core/messages';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type * as t from '@/types';
 import { annotateMessagesForLLM } from '@/tools/toolOutputReferences';
+import { assertNotTruncatedToolCall } from '@/llm/truncation';
 import { Constants, GraphEvents, Providers } from '@/common';
 import { manualToolStreamProviders } from '@/llm/providers';
 import { modifyDeltaProperties } from '@/messages';
@@ -297,6 +298,7 @@ export async function attemptInvoke(
       );
     }
 
+    assertNotTruncatedToolCall(finalChunk, provider);
     return { messages: [finalChunk as AIMessageChunk] };
   }
 
@@ -306,6 +308,7 @@ export async function attemptInvoke(
       (tool_call: ToolCall) => !!tool_call.name
     );
   }
+  assertNotTruncatedToolCall(finalMessage, provider);
   return { messages: [finalMessage] };
 }
 

package/src/llm/truncation.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it } from '@jest/globals';
+import { AIMessage, AIMessageChunk } from '@langchain/core/messages';
+import {
+  OutputTruncationError,
+  assertNotTruncatedToolCall,
+  getTruncationStopReason,
+} from '@/llm/truncation';
+import { Providers } from '@/common';
+
+describe('getTruncationStopReason', () => {
+  it('returns null when there is no response metadata', () => {
+    expect(getTruncationStopReason(new AIMessage('hi'))).toBeNull();
+    expect(getTruncationStopReason(undefined)).toBeNull();
+  });
+
+  it('detects Bedrock Converse streaming shape (messageStop.stopReason)', () => {
+    const message = new AIMessageChunk({
+      content: '',
+      response_metadata: { messageStop: { stopReason: 'max_tokens' } },
+    });
+    expect(getTruncationStopReason(message)).toBe('max_tokens');
+  });
+
+  it('detects Bedrock Converse non-streaming shape (stopReason)', () => {
+    const message = new AIMessage({
+      content: '',
+      response_metadata: { stopReason: 'max_tokens' },
+    });
+    expect(getTruncationStopReason(message)).toBe('max_tokens');
+  });
+
+  it('detects Anthropic shape (stop_reason)', () => {
+    const message = new AIMessage({
+      content: '',
+      response_metadata: { stop_reason: 'max_tokens' },
+    });
+    expect(getTruncationStopReason(message)).toBe('max_tokens');
+  });
+
+  it('detects OpenAI shape (finish_reason: length)', () => {
+    const message = new AIMessage({
+      content: '',
+      response_metadata: { finish_reason: 'length' },
+    });
+    expect(getTruncationStopReason(message)).toBe('length');
+  });
+
+  it('detects Google shape (finishReason: MAX_TOKENS, case-insensitive)', () => {
+    const message = new AIMessage({
+      content: '',
+      response_metadata: { finishReason: 'MAX_TOKENS' },
+    });
+    expect(getTruncationStopReason(message)).toBe('max_tokens');
+  });
+
+  it('detects Anthropic streaming shape (additional_kwargs.stop_reason)', () => {
+    const message = new AIMessageChunk({
+      content: '',
+      additional_kwargs: { stop_reason: 'max_tokens' },
+      response_metadata: { model_provider: 'anthropic' },
+    });
+    expect(getTruncationStopReason(message)).toBe('max_tokens');
+  });
+
+  it('detects OpenAI Responses shape (incomplete_details.reason)', () => {
+    const message = new AIMessage({
+      content: '',
+      response_metadata: {
+        status: 'incomplete',
+        incomplete_details: { reason: 'max_output_tokens' },
+      },
+    });
+    expect(getTruncationStopReason(message)).toBe('max_tokens');
+  });
+
+  it('returns null for a non-token incomplete reason (content_filter)', () => {
+    const message = new AIMessage({
+      content: '',
+      response_metadata: {
+        status: 'incomplete',
+        incomplete_details: { reason: 'content_filter' },
+      },
+    });
+    expect(getTruncationStopReason(message)).toBeNull();
+  });
+
+  it('returns null for normal stop reasons', () => {
+    expect(
+      getTruncationStopReason(
+        new AIMessage({
+          content: 'x',
+          response_metadata: { stopReason: 'end_turn' },
+        })
+      )
+    ).toBeNull();
+    expect(
+      getTruncationStopReason(
+        new AIMessage({
+          content: 'x',
+          response_metadata: { finish_reason: 'stop' },
+        })
+      )
+    ).toBeNull();
+    expect(
+      getTruncationStopReason(
+        new AIMessage({
+          content: 'x',
+          response_metadata: { stopReason: 'tool_use' },
+        })
+      )
+    ).toBeNull();
+  });
+});
+
+describe('assertNotTruncatedToolCall', () => {
+  it('no-ops for a normal completion', () => {
+    expect(() =>
+      assertNotTruncatedToolCall(
+        new AIMessage({
+          content: 'done',
+          response_metadata: { stopReason: 'end_turn' },
+        })
+      )
+    ).not.toThrow();
+  });
+
+  it('no-ops for a truncated plain-text turn (no tool calls)', () => {
+    expect(() =>
+      assertNotTruncatedToolCall(
+        new AIMessage({
+          content: 'partial...',
+          response_metadata: { stopReason: 'max_tokens' },
+        })
+      )
+    ).not.toThrow();
+  });
+
+  it('no-ops for a complete tool call (normal stop reason)', () => {
+    const message = new AIMessage({
+      content: '',
+      tool_calls: [
+        { id: '1', name: 'create_file', args: { path: 'a', content: 'b' } },
+      ],
+      response_metadata: { stopReason: 'tool_use' },
+    });
+    expect(() => assertNotTruncatedToolCall(message)).not.toThrow();
+  });
+
+  it('throws when a tool call is present and the turn was truncated', () => {
+    const message = new AIMessage({
+      content: '',
+      tool_calls: [{ id: '1', name: 'create_file', args: { path: 'a' } }],
+      response_metadata: { messageStop: { stopReason: 'max_tokens' } },
+    });
+    expect(() => assertNotTruncatedToolCall(message)).toThrow(
+      OutputTruncationError
+    );
+    try {
+      assertNotTruncatedToolCall(message);
+    } catch (err) {
+      expect(err).toBeInstanceOf(OutputTruncationError);
+      expect((err as OutputTruncationError).stopReason).toBe('max_tokens');
+      expect((err as OutputTruncationError).toolCallNames).toContain(
+        'create_file'
+      );
+      expect((err as OutputTruncationError).message).toMatch(
+        /max output tokens/i
+      );
+    }
+  });
+
+  it('throws when only incomplete tool_call_chunks survived truncation', () => {
+    const message = new AIMessageChunk({
+      content: '',
+      tool_call_chunks: [
+        {
+          name: 'create_file',
+          args: '{"path":"a"',
+          index: 0,
+          type: 'tool_call_chunk',
+        },
+      ],
+      response_metadata: { messageStop: { stopReason: 'max_tokens' } },
+    });
+    expect(() => assertNotTruncatedToolCall(message)).toThrow(
+      OutputTruncationError
+    );
+  });
+
+  it('still throws for a streaming-arg provider (Anthropic)', () => {
+    const message = new AIMessage({
+      content: '',
+      tool_calls: [{ id: '1', name: 'create_file', args: { path: 'a' } }],
+      response_metadata: { stop_reason: 'max_tokens' },
+    });
+    expect(() =>
+      assertNotTruncatedToolCall(message, Providers.ANTHROPIC)
+    ).toThrow(OutputTruncationError);
+  });
+
+  it('throws for an Anthropic streaming tool call truncated via additional_kwargs', () => {
+    const message = new AIMessageChunk({
+      content: '',
+      tool_calls: [{ id: '1', name: 'create_file', args: { path: 'a' } }],
+      additional_kwargs: { stop_reason: 'max_tokens' },
+      response_metadata: { model_provider: 'anthropic' },
+    });
+    expect(() =>
+      assertNotTruncatedToolCall(message, Providers.ANTHROPIC)
+    ).toThrow(OutputTruncationError);
+  });
+
+  it('throws for an OpenAI Responses tool call truncated via incomplete_details', () => {
+    const message = new AIMessage({
+      content: '',
+      tool_calls: [{ id: '1', name: 'create_file', args: { path: 'a' } }],
+      response_metadata: {
+        status: 'incomplete',
+        incomplete_details: { reason: 'max_output_tokens' },
+      },
+    });
+    expect(() => assertNotTruncatedToolCall(message, Providers.OPENAI)).toThrow(
+      OutputTruncationError
+    );
+  });
+
+  it('does not throw for providers that deliver complete tool calls (Google/Vertex)', () => {
+    const message = new AIMessage({
+      content: '',
+      tool_calls: [
+        { id: '1', name: 'create_file', args: { path: 'a', content: 'b' } },
+      ],
+      response_metadata: { finishReason: 'MAX_TOKENS' },
+    });
+    expect(() =>
+      assertNotTruncatedToolCall(message, Providers.GOOGLE)
+    ).not.toThrow();
+    expect(() =>
+      assertNotTruncatedToolCall(message, Providers.VERTEXAI)
+    ).not.toThrow();
+  });
+});

package/src/llm/truncation.ts

@@ -0,0 +1,178 @@
+import type { AIMessageChunk, BaseMessage } from '@langchain/core/messages';
+import { Providers } from '@/common';
+
+/**
+ * Providers whose adapters deliver tool calls as complete, atomic objects
+ * rather than streamed argument deltas. Google/Vertex (GenAI) emit each
+ * `functionCall` whole and seal it on arrival, so a `MAX_TOKENS` finish does
+ * NOT imply the arguments were cut off — the truncation guard must skip them.
+ */
+const ATOMIC_TOOL_CALL_ARG_PROVIDERS = new Set<Providers>([
+  Providers.GOOGLE,
+  Providers.VERTEXAI,
+]);
+
+/**
+ * Normalized truncation reasons across providers. Providers disagree on the
+ * key and the value: Anthropic/Bedrock use `max_tokens`, OpenAI uses `length`,
+ * Google uses `MAX_TOKENS`.
+ */
+export type TruncationStopReason = 'max_tokens' | 'length';
+
+const MAX_TOKEN_VALUES = new Set([
+  'max_tokens',
+  'max_token',
+  'maxtokens',
+  'max_output_tokens',
+]);
+const LENGTH_VALUES = new Set(['length']);
+
+function normalizeStopValue(value: unknown): TruncationStopReason | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (MAX_TOKEN_VALUES.has(normalized)) {
+    return 'max_tokens';
+  }
+  if (LENGTH_VALUES.has(normalized)) {
+    return 'length';
+  }
+  return null;
+}
+
+/**
+ * Reads the truncation stop reason off a message, covering every provider
+ * shape we stream:
+ * - `response_metadata.stopReason` (Bedrock Converse, non-streaming)
+ * - `response_metadata.messageStop.stopReason` (Bedrock Converse streaming)
+ * - `response_metadata.stop_reason` (Anthropic, non-streaming)
+ * - `additional_kwargs.stop_reason` (Anthropic streaming `message_delta`)
+ * - `response_metadata.finish_reason` (OpenAI chat-completions / compatible)
+ * - `response_metadata.incomplete_details.reason` (OpenAI Responses API)
+ * - `response_metadata.finishReason` (Google)
+ *
+ * Returns the normalized reason when the model stopped because it hit the
+ * output token ceiling, otherwise `null`.
+ */
+export function getTruncationStopReason(
+  message:
+    | Pick<BaseMessage, 'response_metadata' | 'additional_kwargs'>
+    | undefined
+    | null
+): TruncationStopReason | null {
+  const meta = message?.response_metadata as
+    | Record<string, unknown>
+    | undefined;
+  const additionalKwargs = message?.additional_kwargs as
+    | Record<string, unknown>
+    | undefined;
+  if (meta == null && additionalKwargs == null) {
+    return null;
+  }
+
+  const messageStop = meta?.messageStop as { stopReason?: unknown } | undefined;
+  const incompleteDetails = meta?.incomplete_details as
+    | { reason?: unknown }
+    | undefined;
+  const candidates: unknown[] = [
+    meta?.stopReason,
+    meta?.stop_reason,
+    meta?.finish_reason,
+    meta?.finishReason,
+    messageStop?.stopReason,
+    incompleteDetails?.reason,
+    additionalKwargs?.stop_reason,
+  ];
+
+  for (const candidate of candidates) {
+    const normalized = normalizeStopValue(candidate);
+    if (normalized != null) {
+      return normalized;
+    }
+  }
+  return null;
+}
+
+function hasOpenToolCall(message: AIMessageChunk | BaseMessage): boolean {
+  const m = message as AIMessageChunk & {
+    tool_calls?: unknown[];
+    tool_call_chunks?: unknown[];
+    invalid_tool_calls?: unknown[];
+  };
+  return (
+    (m.tool_calls?.length ?? 0) > 0 ||
+    (m.tool_call_chunks?.length ?? 0) > 0 ||
+    (m.invalid_tool_calls?.length ?? 0) > 0
+  );
+}
+
+/**
+ * Error raised when a model turn is cut off by the output token limit while it
+ * was still emitting a tool call. The arguments are necessarily incomplete, so
+ * executing or re-prompting the call would loop on a malformed request. Failing
+ * fast with this surfaces an actionable message to the caller instead.
+ */
+export class OutputTruncationError extends Error {
+  readonly stopReason: TruncationStopReason;
+  readonly toolCallNames: string[];
+
+  constructor(stopReason: TruncationStopReason, toolCallNames: string[]) {
+    const named =
+      toolCallNames.length > 0
+        ? ` (tool call: ${toolCallNames.join(', ')})`
+        : '';
+    super(
+      'The model response was truncated at the maximum output token limit before ' +
+        `the tool call arguments were complete${named}. Increase the model's max ` +
+        'output tokens, or have the model produce smaller arguments — for large ' +
+        'files, write a lean main file and move bulky content into separate files.'
+    );
+    this.name = 'OutputTruncationError';
+    this.stopReason = stopReason;
+    this.toolCallNames = toolCallNames;
+  }
+}
+
+function collectToolCallNames(message: AIMessageChunk | BaseMessage): string[] {
+  const m = message as AIMessageChunk & {
+    tool_calls?: Array<{ name?: string }>;
+    tool_call_chunks?: Array<{ name?: string }>;
+    invalid_tool_calls?: Array<{ name?: string }>;
+  };
+  const names = [
+    ...(m.tool_calls ?? []),
+    ...(m.tool_call_chunks ?? []),
+    ...(m.invalid_tool_calls ?? []),
+  ]
+    .map((tc) => tc.name)
+    .filter((name): name is string => typeof name === 'string' && name !== '');
+  return [...new Set(names)];
+}
+
+/**
+ * Throws {@link OutputTruncationError} when `message` was truncated by the
+ * output token limit AND still carries a tool call. For providers that stream
+ * tool arguments incrementally (Anthropic, Bedrock, OpenAI), a tool call
+ * emitted under truncation has incomplete arguments — the tool-use block is the
+ * last thing the model streams — so letting it through makes the agent loop on a
+ * malformed call. No-ops for normal completions, truncated plain-text turns, and
+ * providers that deliver complete tool calls atomically (Google/Vertex), where
+ * `MAX_TOKENS` does not imply the arguments were cut off.
+ */
+export function assertNotTruncatedToolCall(
+  message: AIMessageChunk | BaseMessage | undefined | null,
+  provider?: Providers
+): void {
+  if (message == null) {
+    return;
+  }
+  if (provider != null && ATOMIC_TOOL_CALL_ARG_PROVIDERS.has(provider)) {
+    return;
+  }
+  const stopReason = getTruncationStopReason(message);
+  if (stopReason == null || !hasOpenToolCall(message)) {
+    return;
+  }
+  throw new OutputTruncationError(stopReason, collectToolCallNames(message));
+}