@librechat/agents 3.3.13 → 3.4.0

package/src/llm/vertexai/streamSmoothing.test.ts

@@ -0,0 +1,109 @@
+import { expect, test, describe, jest } from '@jest/globals';
+import { HumanMessage } from '@langchain/core/messages';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+import { ChatVertexAI } from './index';
+
+describe('Vertex stream smoothing', () => {
+  function textOutput(text: string): Record<string, unknown> {
+    return {
+      candidates: [
+        {
+          content: { role: 'model', parts: [{ text }] },
+          index: 0,
+        },
+      ],
+    };
+  }
+
+  async function runStream(
+    outputs: Record<string, unknown>[],
+    modelFields: Record<string, unknown> = {}
+  ): Promise<{
+    yielded: ChatGenerationChunk[];
+    dispatchedTokens: string[];
+  }> {
+    const model = new ChatVertexAI({
+      model: 'gemini-2.5-flash',
+      authOptions: {
+        projectId: 'test-project',
+        credentials: { client_email: 'test@test', private_key: 'test' },
+      },
+      ...modelFields,
+    });
+
+    let index = 0;
+    const fakeStream = {
+      get streamDone(): boolean {
+        return index > outputs.length;
+      },
+      async nextChunk(): Promise<unknown> {
+        const output = index < outputs.length ? outputs[index] : null;
+        index += 1;
+        return output;
+      },
+    };
+    (
+      model as unknown as {
+        streamedConnection: { request: unknown };
+      }
+    ).streamedConnection.request = jest.fn(async () => ({ data: fakeStream }));
+
+    const dispatchedTokens: string[] = [];
+    const runManager = {
+      handleCustomEvent: jest.fn(async () => undefined),
+      handleLLMNewToken: jest.fn(async (token: string) => {
+        dispatchedTokens.push(token);
+      }),
+    } as unknown as CallbackManagerForLLMRun;
+
+    const yielded: ChatGenerationChunk[] = [];
+    for await (const chunk of model._streamResponseChunks(
+      [new HumanMessage('hi')],
+      {} as Parameters<ChatVertexAI['_streamResponseChunks']>[1],
+      runManager
+    )) {
+      yielded.push(chunk);
+    }
+    return { yielded, dispatchedTokens };
+  }
+
+  test('splits large text outputs at stream boundaries with pacing', async () => {
+    const { yielded, dispatchedTokens } = await runStream(
+      [textOutput('alpha beta gamma')],
+      { _lc_stream_delay: 1 }
+    );
+
+    const texts = yielded.map((chunk) => chunk.text).filter(Boolean);
+    expect(texts).toEqual(['alpha ', 'beta ', 'gamma']);
+    expect(dispatchedTokens.filter(Boolean)).toEqual([
+      'alpha ',
+      'beta ',
+      'gamma',
+    ]);
+  });
+
+  test('passes chunks through unsplit when smoothing is disabled', async () => {
+    const { yielded } = await runStream([textOutput('alpha beta gamma')], {
+      _lc_stream_delay: 0,
+    });
+
+    expect(yielded.map((chunk) => chunk.text).filter(Boolean)).toEqual([
+      'alpha beta gamma',
+    ]);
+  });
+
+  test('defaults to 25ms adaptive smoothing with 0 disabling', () => {
+    const base = {
+      model: 'gemini-2.5-flash',
+      authOptions: {
+        projectId: 'test-project',
+        credentials: { client_email: 'test@test', private_key: 'test' },
+      },
+    };
+    expect(new ChatVertexAI(base)._lc_stream_delay).toBe(25);
+    expect(
+      new ChatVertexAI({ ...base, _lc_stream_delay: 0 })._lc_stream_delay
+    ).toBe(0);
+  });
+});

package/src/specs/subagent.test.ts

@@ -21,6 +21,7 @@ import * as providers from '@/llm/providers';
 import { Run } from '@/run';
 
 const CHILD_RESPONSE = 'Research result: Paris is the capital of France.';
+const OVERRIDDEN_CHILD_RESPONSE = 'Deterministic child override result.';
 
 const callerConfig: Partial<RunnableConfig> & {
   version: 'v1' | 'v2';
@@ -226,6 +227,49 @@ describe('Subagent Integration', () => {
     expect(subagentTool).toBeDefined();
   });
 
+  it('only applies an explicitly configured subagent model override', async () => {
+    const invokeSubagent = async (
+      overrideSubagents: boolean
+    ): Promise<string> => {
+      const run = await Run.create<t.IState>({
+        runId: `subagent-model-override-${overrideSubagents}-${Date.now()}`,
+        graphConfig: {
+          type: 'standard',
+          agents: [createParentAgent()],
+        },
+        returnContent: true,
+        skipCleanup: true,
+      });
+      const graph = run.Graph as StandardGraph;
+      const model = new FakeListChatModel({
+        responses: [OVERRIDDEN_CHILD_RESPONSE],
+      });
+      graph.overrideModel = model;
+      if (overrideSubagents) {
+        graph.setSubagentModelOverride(model);
+      }
+
+      const context = graph.agentContexts.get('parent');
+      const subagentTool = (context?.graphTools as t.GenericTool[]).find(
+        (tool) => 'name' in tool && tool.name === Constants.SUBAGENT
+      );
+      expect(subagentTool).toBeDefined();
+
+      return String(
+        await subagentTool!.invoke(
+          {
+            description: 'What is the capital of France?',
+            subagent_type: 'researcher',
+          },
+          callerConfig
+        )
+      );
+    };
+
+    await expect(invokeSubagent(false)).resolves.toBe(CHILD_RESPONSE);
+    await expect(invokeSubagent(true)).resolves.toBe(OVERRIDDEN_CHILD_RESPONSE);
+  });
+
   it('inherits eager event-tool settings into self-spawn child graphs', async () => {
     const originalCreateWorkflow = StandardGraph.prototype.createWorkflow;
     const observedChildGraphs: Array<{

package/src/specs/tokens.test.ts

@@ -13,6 +13,7 @@ import {
   estimateImageBlockTokens,
   estimateDocumentBlockTokens,
   estimateTimedMediaBlockTokens,
+  UnsafeTokenMeasurementError,
 } from '@/utils/tokens';
 
 /** Builds a minimal PNG data URI whose IHDR encodes the given dimensions. */
@@ -71,6 +72,32 @@ describe('createTokenCounter with different encodings', () => {
     expect(count).toBeGreaterThan(0);
   });
 
+  test('claude correction keeps proxy-backed tool history safely measurable', async () => {
+    let getCalls = 0;
+    const args = new Proxy(
+      { query: 'select * from reports' },
+      {
+        get(target, property, receiver) {
+          getCalls++;
+          return Reflect.get(target, property, receiver);
+        },
+      }
+    );
+    const message = {
+      content: '',
+      tool_calls: [{ id: 'proxy-call', name: 'query', args }],
+      getType: () => 'ai',
+    } as unknown as AIMessage;
+    const counter = await createTokenCounter('claude');
+
+    const count = counter(message);
+
+    expect(Number.isSafeInteger(count)).toBe(true);
+    expect(count).toBeGreaterThan(0);
+    expect(count).toBeLessThan(1_000);
+    expect(getCalls).toBe(0);
+  });
+
   test('o200k_base encoding produces valid token counts', async () => {
     const counter = await createTokenCounter('o200k_base');
     const msg = new HumanMessage('Hello, world!');
@@ -110,6 +137,22 @@ describe('getTokenCountForMessage', () => {
     expect(count).toBe(600_003);
   });
 
+  test.each([
+    -1,
+    1.5,
+    Number.MAX_SAFE_INTEGER,
+    Number.MAX_SAFE_INTEGER + 1,
+    Number.POSITIVE_INFINITY,
+    Number.NaN,
+  ])('rejects an unsafe tokenizer result of %s', (unsafeCount) => {
+    expect(() =>
+      getTokenCountForMessage(
+        new HumanMessage('unsafe count'),
+        () => unsafeCount
+      )
+    ).toThrow(UnsafeTokenMeasurementError);
+  });
+
   test('bounds direct string tool args before tokenization and charges omitted characters', () => {
     const callbackLengths: number[] = [];
     const args = 'x'.repeat(300_000);
@@ -153,10 +196,13 @@ describe('getTokenCountForMessage', () => {
     );
 
     expect(Math.max(...callbackLengths)).toBeLessThanOrEqual(200_000);
-    expect(count).toBeGreaterThan(payload.length);
+    // A traversal-work sentinel is unknown size, not real context usage.
+    // The provider-input projection will compact the value before invoke.
+    expect(count).toBeGreaterThan(0);
+    expect(count).toBeLessThan(Number.MAX_SAFE_INTEGER);
   });
 
-  test('fails closed when prototype traps throw', () => {
+  test('counts an opaque proxy argument as its bounded provider-safe placeholder', () => {
     let prototypeCalls = 0;
     const args = new Proxy(
       { safe: true },
@@ -171,11 +217,11 @@ describe('getTokenCountForMessage', () => {
     expect(hasUnsafeStructuredSerialization(args)).toBe(true);
     expect(
       getTokenCountForMessage(messageWithToolArgs(args), (text) => text.length)
-    ).toBe(Number.MAX_SAFE_INTEGER);
+    ).toBeLessThan(Number.MAX_SAFE_INTEGER);
     expect(prototypeCalls).toBeLessThanOrEqual(2);
   });
 
-  test('fails closed without recursing through self-referential prototype proxies', () => {
+  test('does not recurse through self-referential prototype proxies', () => {
     let prototypeCalls = 0;
     const args: Record<string, unknown> = new Proxy<Record<string, unknown>>(
       {},
@@ -190,11 +236,11 @@ describe('getTokenCountForMessage', () => {
     expect(hasUnsafeStructuredSerialization(args)).toBe(true);
     expect(
       getTokenCountForMessage(messageWithToolArgs(args), (text) => text.length)
-    ).toBe(Number.MAX_SAFE_INTEGER);
+    ).toBeLessThan(Number.MAX_SAFE_INTEGER);
     expect(prototypeCalls).toBeLessThanOrEqual(2);
   });
 
-  test('fails closed when descriptor and own-key proxy traps throw', () => {
+  test('uses bounded placeholders when descriptor and own-key proxy traps throw', () => {
     const descriptorProxy = new Proxy(
       {},
       {
@@ -219,11 +265,11 @@ describe('getTokenCountForMessage', () => {
           messageWithToolArgs(args),
           (text) => text.length
         )
-      ).toBe(Number.MAX_SAFE_INTEGER);
+      ).toBeLessThan(Number.MAX_SAFE_INTEGER);
     }
   });
 
-  test('fails closed on get traps and revoked proxies without invoking them', () => {
+  test('does not invoke get traps or revoked proxies while measuring arguments', () => {
     let getCalls = 0;
     const getProxy = new Proxy(
       {},
@@ -250,12 +296,12 @@ describe('getTokenCountForMessage', () => {
           messageWithToolArgs(args),
           (text) => text.length
         )
-      ).toBe(Number.MAX_SAFE_INTEGER);
+      ).toBeLessThan(Number.MAX_SAFE_INTEGER);
     }
     expect(getCalls).toBe(0);
   });
 
-  test('fails closed on proxied content blocks without invoking their traps', () => {
+  test('reports a typed terminal error for a proxied content block', () => {
     let getCalls = 0;
     const contentBlock = new Proxy(
       { type: 'text', text: 'safe' },
@@ -271,12 +317,88 @@ describe('getTokenCountForMessage', () => {
       getType: () => 'tool',
     } as unknown as ToolMessage;
 
-    expect(getTokenCountForMessage(message, (text) => text.length)).toBe(
-      Number.MAX_SAFE_INTEGER
+    expect(() => getTokenCountForMessage(message, (text) => text.length)).toThrow(
+      UnsafeTokenMeasurementError
     );
+    try {
+      getTokenCountForMessage(message, (text) => text.length);
+    } catch (error) {
+      expect(JSON.parse((error as Error).message)).toEqual({
+        type: 'unsafe_token_measurement',
+        reason: 'content_proxy',
+        path: 'content[0]',
+      });
+    }
     expect(getCalls).toBe(0);
   });
 
+  test('reports typed errors for unsafe message and metadata branches', () => {
+    let getterCalls = 0;
+    const messageProxy = new Proxy(new HumanMessage('secret payload'), {
+      get() {
+        getterCalls++;
+        throw new Error('message read denied');
+      },
+    });
+    const metadataProxy = new Proxy(
+      {},
+      {
+        get() {
+          getterCalls++;
+          throw new Error('metadata read denied');
+        },
+      }
+    );
+    const accessorMetadata = {};
+    Object.defineProperty(accessorMetadata, 'type', {
+      get() {
+        getterCalls++;
+        return 'computer_call_output';
+      },
+    });
+    const cases = [
+      {
+        message: messageProxy,
+        reason: 'message_proxy',
+        path: 'message',
+      },
+      {
+        message: {
+          content: '',
+          additional_kwargs: metadataProxy,
+          getType: () => 'tool',
+        } as unknown as ToolMessage,
+        reason: 'metadata_proxy',
+        path: 'additional_kwargs',
+      },
+      {
+        message: {
+          content: '',
+          additional_kwargs: accessorMetadata,
+          getType: () => 'tool',
+        } as unknown as ToolMessage,
+        reason: 'metadata_accessor',
+        path: 'additional_kwargs.type',
+      },
+    ];
+
+    for (const testCase of cases) {
+      try {
+        getTokenCountForMessage(testCase.message, (text) => text.length);
+        throw new Error('Expected token measurement to fail');
+      } catch (error) {
+        expect(error).toBeInstanceOf(UnsafeTokenMeasurementError);
+        expect(JSON.parse((error as Error).message)).toEqual({
+          type: 'unsafe_token_measurement',
+          reason: testCase.reason,
+          path: testCase.path,
+        });
+        expect((error as Error).message).not.toContain('secret payload');
+      }
+    }
+    expect(getterCalls).toBe(0);
+  });
+
   test('detects inherited accessors without invoking them', () => {
     let accessorCalls = 0;
     const prototype = {};
@@ -292,10 +414,32 @@ describe('getTokenCountForMessage', () => {
     expect(hasUnsafeStructuredSerialization(args)).toBe(true);
     expect(
       getTokenCountForMessage(messageWithToolArgs(args), (text) => text.length)
-    ).toBe(Number.MAX_SAFE_INTEGER);
+    ).toBeLessThan(Number.MAX_SAFE_INTEGER);
     expect(accessorCalls).toBe(0);
   });
 
+  test('counts safely serializable proxy tool-call history without invoking getters', () => {
+    let getCalls = 0;
+    const args = new Proxy(
+      { query: 'select * from reports' },
+      {
+        get(target, property, receiver) {
+          getCalls++;
+          return Reflect.get(target, property, receiver);
+        },
+      }
+    );
+
+    const count = getTokenCountForMessage(
+      messageWithToolArgs(args),
+      (text) => text.length
+    );
+
+    expect(count).toBeGreaterThan(0);
+    expect(count).toBeLessThan(Number.MAX_SAFE_INTEGER);
+    expect(getCalls).toBe(0);
+  });
+
   test('counts tool_calls-only names and arguments', () => {
     const message = new AIMessage({
       content: '',
@@ -334,7 +478,8 @@ describe('getTokenCountForMessage', () => {
 
     const count = getTokenCountForMessage(message, (text) => text.length);
 
-    expect(count).toBeGreaterThanOrEqual(Number.MAX_SAFE_INTEGER);
+    expect(count).toBeLessThan(Number.MAX_SAFE_INTEGER);
+    expect(count).toBeGreaterThan(0);
     expect(toJSONCalls).toBe(0);
   });
 

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

@@ -67,6 +67,50 @@ describe('filterSubagentResult', () => {
     expect(filterSubagentResult(messages)).toBe('First part.\nSecond part.');
   });
 
+  it('prefers final text_delta blocks over earlier AI text', () => {
+    const messages: BaseMessage[] = [
+      new AIMessage({
+        content: [
+          { type: 'text', text: 'Let me search.' },
+          { type: 'tool_use', id: 'call_1', name: 'search', input: {} },
+        ],
+      }),
+      new ToolMessage({ content: 'result', tool_call_id: 'call_1' }),
+      new AIMessage({
+        content: [
+          { type: 'text_delta', index: 0, text: 'Streamed ' },
+          { type: 'text_delta', index: 0, text: 'result.' },
+        ],
+      }),
+    ];
+    expect(filterSubagentResult(messages)).toBe('Streamed result.');
+  });
+
+  it('keeps annotation-only text blocks within a text_delta sequence', () => {
+    const messages: BaseMessage[] = [
+      new AIMessage({
+        content: [
+          { type: 'text_delta', index: 0, text: 'Cited ' },
+          { type: 'text', index: 0, citations: [{ url: 'source' }] },
+          { type: 'text_delta', index: 0, text: 'answer.' },
+        ],
+      }),
+    ];
+    expect(filterSubagentResult(messages)).toBe('Cited answer.');
+  });
+
+  it('separates text_delta blocks with different indexes', () => {
+    const messages: BaseMessage[] = [
+      new AIMessage({
+        content: [
+          { type: 'text_delta', index: 0, text: 'First.' },
+          { type: 'text_delta', index: 1, text: 'Second.' },
+        ],
+      }),
+    ];
+    expect(filterSubagentResult(messages)).toBe('First.\nSecond.');
+  });
+
   it('strips tool_use blocks from array content', () => {
     const messages: BaseMessage[] = [
       new AIMessage({
@@ -470,7 +514,10 @@ describe('SubagentExecutor', () => {
         }) as unknown as StandardGraph,
     });
     await expect(
-      executor.execute({ description: 'Do something', subagentType: 'researcher' })
+      executor.execute({
+        description: 'Do something',
+        subagentType: 'researcher',
+      })
     ).rejects.toBeInstanceOf(StreamLimitExceededError);
   });
 

package/src/tools/subagent/SubagentExecutor.ts

@@ -27,17 +27,24 @@ import type { AggregatedHookResult, HookRegistry } from '@/hooks';
 import type { AgentContext } from '@/agents/AgentContext';
 import type { StandardGraph } from '@/graphs/Graph';
 import type { HandlerRegistry } from '@/events';
-import { Constants, GraphEvents, Callback, StepTypes } from '@/common';
 import {
   StreamLimitExceededError,
   RUN_BREAKER_SCOPE_CONFIG_KEY,
 } from '@/llm/streamLimits';
+import {
+  ContentTypes,
+  Constants,
+  GraphEvents,
+  Callback,
+  StepTypes,
+} from '@/common';
 import { executeHooks } from '@/hooks';
 
 const DEFAULT_MAX_TURNS = 25;
 const RECURSION_MULTIPLIER = 3;
 const ERROR_MESSAGE_MAX_CHARS = 200;
 const MAX_PENDING_SUBAGENT_UPDATES = 64;
+const TEXT_DELTA_CONTENT_TYPE = `${ContentTypes.TEXT}_delta`;
 
 const HOOK_FALLBACK: AggregatedHookResult = Object.freeze({
   additionalContexts: [] as string[],
@@ -119,7 +126,10 @@ type SanitizedStepCompleted =
     };
 
 type SanitizedProcessedToolCall = Partial<
-  Pick<ProcessedToolCall, 'args' | 'id' | 'name' | 'output' | 'progress' | 'outcome'>
+  Pick<
+    ProcessedToolCall,
+    'args' | 'id' | 'name' | 'output' | 'progress' | 'outcome'
+  >
 >;
 
 type SanitizedRunStepCompleted = {
@@ -1401,6 +1411,9 @@ export function summarizeEvent(eventName: string, data: unknown): string {
  * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
  * continues to earlier AIMessages so partial progress is salvaged — this
  * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
+ * Consecutive streamed text-delta blocks with the same provider index are
+ * coalesced without adding whitespace. Annotation-only text blocks are
+ * ignored; complete text blocks and distinct delta indexes remain separated.
  * Returns "Task completed" only when no AIMessage in the history contains
  * any text.
  */
@@ -1422,13 +1435,64 @@ export function filterSubagentResult(messages: BaseMessage[]): string {
     }
 
     const textParts: string[] = [];
+    let textDeltaParts: string[] = [];
+    let textDeltaIndex: string | number | undefined;
+    const flushTextDeltaParts = (): void => {
+      if (textDeltaParts.length === 0) {
+        return;
+      }
+      textParts.push(textDeltaParts.join(''));
+      textDeltaParts = [];
+      textDeltaIndex = undefined;
+    };
     for (const block of content) {
       if (typeof block === 'string') {
-        textParts.push(block);
-      } else if ('type' in block && block.type === 'text' && 'text' in block) {
-        textParts.push(block.text as string);
+        flushTextDeltaParts();
+        if (block !== '') {
+          textParts.push(block);
+        }
+        continue;
+      }
+
+      const type =
+        'type' in block && typeof block.type === 'string' ? block.type : '';
+      const isTextDelta = type === TEXT_DELTA_CONTENT_TYPE;
+      const isText = type === ContentTypes.TEXT || isTextDelta;
+      const text =
+        isText && 'text' in block && typeof block.text === 'string'
+          ? block.text
+          : '';
+      if (isTextDelta) {
+        if (text === '') {
+          continue;
+        }
+        const index =
+          'index' in block &&
+          (typeof block.index === 'string' || typeof block.index === 'number')
+            ? block.index
+            : undefined;
+        if (
+          textDeltaIndex != null &&
+          index != null &&
+          index !== textDeltaIndex
+        ) {
+          flushTextDeltaParts();
+        }
+        textDeltaIndex ??= index;
+        textDeltaParts.push(text);
+        continue;
+      }
+
+      if (type === ContentTypes.TEXT && text === '') {
+        continue;
+      }
+
+      flushTextDeltaParts();
+      if (text !== '') {
+        textParts.push(text);
       }
     }
+    flushTextDeltaParts();
 
     if (textParts.length > 0) {
       return textParts.join('\n');