@librechat/agents 3.2.61 → 3.2.63

package/src/llm/openai/managedRequests.test.ts

@@ -0,0 +1,182 @@
+import OpenAI from 'openai';
+
+import {
+  addChatCacheBreakpoints,
+  addResponseCacheBreakpoints,
+  shouldIncludeEncryptedReasoning,
+} from './index';
+
+describe('managed GPT-5.6 request fields', () => {
+  it('places cache breakpoints after instructions and the prior history prefix', () => {
+    const messages = addChatCacheBreakpoints([
+      { role: 'system', content: 'Stable instructions.' },
+      { role: 'user', content: 'First question.' },
+      { role: 'assistant', content: 'First answer.' },
+      { role: 'user', content: 'Current question.' },
+    ]);
+
+    expect(messages[0]).toMatchObject({
+      content: [
+        {
+          type: 'text',
+          text: 'Stable instructions.',
+          prompt_cache_breakpoint: { mode: 'explicit' },
+        },
+      ],
+    });
+    expect(messages[2]).toMatchObject({
+      content: [
+        {
+          type: 'text',
+          text: 'First answer.',
+          prompt_cache_breakpoint: { mode: 'explicit' },
+        },
+      ],
+    });
+    expect(JSON.stringify(messages[1])).not.toContain(
+      'prompt_cache_breakpoint'
+    );
+    expect(JSON.stringify(messages[3])).not.toContain(
+      'prompt_cache_breakpoint'
+    );
+  });
+
+  it('uses supported Responses content blocks for the same stable prefixes', () => {
+    const input = [
+      {
+        type: 'message',
+        role: 'developer',
+        content: [{ type: 'input_text', text: 'Stable instructions.' }],
+      },
+      {
+        type: 'message',
+        role: 'user',
+        content: [{ type: 'input_text', text: 'Prior question.' }],
+      },
+      {
+        type: 'message',
+        role: 'user',
+        content: [{ type: 'input_text', text: 'Current question.' }],
+      },
+    ] as unknown as OpenAI.Responses.ResponseInput;
+    const result = addResponseCacheBreakpoints(input);
+
+    expect(result).toMatchObject([
+      {
+        content: [
+          {
+            prompt_cache_breakpoint: { mode: 'explicit' },
+          },
+        ],
+      },
+      {
+        content: [
+          {
+            prompt_cache_breakpoint: { mode: 'explicit' },
+          },
+        ],
+      },
+      {
+        content: [{ type: 'input_text', text: 'Current question.' }],
+      },
+    ]);
+  });
+
+  it('does not mark replayed assistant output blocks as breakpoints', () => {
+    const input = [
+      {
+        type: 'message',
+        role: 'developer',
+        content: [{ type: 'input_text', text: 'Stable instructions.' }],
+      },
+      {
+        type: 'message',
+        role: 'user',
+        content: [{ type: 'input_text', text: 'First question.' }],
+      },
+      {
+        type: 'message',
+        role: 'assistant',
+        content: [{ type: 'output_text', text: 'Prior answer.' }],
+      },
+      {
+        type: 'message',
+        role: 'user',
+        content: [{ type: 'input_text', text: 'Current question.' }],
+      },
+    ] as unknown as OpenAI.Responses.ResponseInput;
+    const result = addResponseCacheBreakpoints(input) as unknown as Array<{
+      content: Array<Record<string, unknown>>;
+    }>;
+
+    // output_text is rejected with a 400 by OpenAI, so it must stay unmarked;
+    // the stable prefix falls back to the prior user input message.
+    expect(result[2].content[0]).not.toHaveProperty('prompt_cache_breakpoint');
+    expect(result[1].content[0]).toHaveProperty('prompt_cache_breakpoint');
+    expect(result[0].content[0]).toHaveProperty('prompt_cache_breakpoint');
+  });
+
+  it('marks string-content Responses messages by wrapping them in input_text', () => {
+    const input = [
+      { type: 'message', role: 'system', content: 'Stable system prompt.' },
+      { type: 'message', role: 'user', content: 'Prior turn.' },
+      { type: 'message', role: 'user', content: 'Current question.' },
+    ] as unknown as OpenAI.Responses.ResponseInput;
+    const result = addResponseCacheBreakpoints(input) as unknown as Array<{
+      content: unknown;
+    }>;
+
+    expect(result[0].content).toEqual([
+      {
+        type: 'input_text',
+        text: 'Stable system prompt.',
+        prompt_cache_breakpoint: { mode: 'explicit' },
+      },
+    ]);
+  });
+
+  it('does not rewrite assistant string content as input_text', () => {
+    const input = [
+      { type: 'message', role: 'system', content: 'Stable system prompt.' },
+      { type: 'message', role: 'user', content: 'First question.' },
+      { type: 'message', role: 'assistant', content: 'Prior answer.' },
+      { type: 'message', role: 'user', content: 'Current question.' },
+    ] as unknown as OpenAI.Responses.ResponseInput;
+    const result = addResponseCacheBreakpoints(input) as unknown as Array<{
+      content: unknown;
+    }>;
+
+    // input_text under role:assistant is rejected with a 400, so assistant
+    // string content must stay a string and the breakpoint falls back to the
+    // prior user turn.
+    expect(result[2].content).toBe('Prior answer.');
+    expect(result[1].content).toEqual([
+      {
+        type: 'input_text',
+        text: 'First question.',
+        prompt_cache_breakpoint: { mode: 'explicit' },
+      },
+    ]);
+  });
+
+  it('requests encrypted reasoning whenever persisted or stateless replay may be needed', () => {
+    expect(shouldIncludeEncryptedReasoning('gpt-5.6', {})).toBe(true);
+    expect(
+      shouldIncludeEncryptedReasoning('gpt-5.6', {
+        reasoning: { context: 'all_turns' },
+      })
+    ).toBe(true);
+    expect(
+      shouldIncludeEncryptedReasoning('gpt-5.6', {
+        reasoning: { context: 'current_turn' },
+      })
+    ).toBe(false);
+    expect(
+      shouldIncludeEncryptedReasoning('gpt-5.6', {
+        store: false,
+        reasoning: { context: 'current_turn' },
+      })
+    ).toBe(true);
+    expect(shouldIncludeEncryptedReasoning('gpt-5.5', {})).toBe(false);
+  });
+});

package/src/llm/openai/streamMetadata.spec.ts

@@ -0,0 +1,86 @@
+import { expect, test, describe } from '@jest/globals';
+import { AIMessageChunk } from '@langchain/core/messages';
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { SeenScalarMetadata } from './streamMetadata';
+import { dropRepeatedScalarMetadata } from './streamMetadata';
+
+function chunkWithGenerationInfo(
+  generationInfo: Record<string, unknown>
+): ChatGenerationChunk {
+  return new ChatGenerationChunk({
+    text: '',
+    message: new AIMessageChunk({ content: '' }),
+    generationInfo,
+  });
+}
+
+describe('dropRepeatedScalarMetadata', () => {
+  test('drops a scalar repeated within the same completion (keep-first)', () => {
+    const seen: SeenScalarMetadata = new Map();
+    const first = chunkWithGenerationInfo({
+      completion: 0,
+      finish_reason: 'stop',
+      model_name: 'm',
+    });
+    const second = chunkWithGenerationInfo({
+      completion: 0,
+      finish_reason: 'stop',
+      model_name: 'm',
+    });
+
+    dropRepeatedScalarMetadata(first, seen);
+    dropRepeatedScalarMetadata(second, seen);
+
+    expect(first.generationInfo?.finish_reason).toBe('stop');
+    expect(second.generationInfo?.finish_reason).toBeUndefined();
+    expect(second.generationInfo?.model_name).toBeUndefined();
+  });
+
+  test('keeps a scalar that repeats across different completion indices', () => {
+    const seen: SeenScalarMetadata = new Map();
+    const choice0 = chunkWithGenerationInfo({
+      completion: 0,
+      finish_reason: 'stop',
+      model_name: 'm',
+    });
+    const choice1 = chunkWithGenerationInfo({
+      completion: 1,
+      finish_reason: 'stop',
+      model_name: 'm',
+    });
+
+    dropRepeatedScalarMetadata(choice0, seen);
+    dropRepeatedScalarMetadata(choice1, seen);
+
+    // each completion keeps its own finish metadata (n > 1 aggregates per choice)
+    expect(choice0.generationInfo?.finish_reason).toBe('stop');
+    expect(choice1.generationInfo?.finish_reason).toBe('stop');
+  });
+
+  test('clones before deleting so a shared metadata object is not mutated', () => {
+    const seen: SeenScalarMetadata = new Map();
+    // Simulate ChatDeepSeek splitting one raw chunk into pieces that share the
+    // same generationInfo object.
+    const shared = { completion: 0, finish_reason: 'stop', model_name: 'm' };
+    const first = new ChatGenerationChunk({
+      text: '',
+      message: new AIMessageChunk({ content: 'a' }),
+      generationInfo: shared,
+    });
+    const second = new ChatGenerationChunk({
+      text: '',
+      message: new AIMessageChunk({ content: 'b' }),
+      generationInfo: shared,
+    });
+
+    dropRepeatedScalarMetadata(first, seen);
+    dropRepeatedScalarMetadata(second, seen);
+
+    // the already-emitted first piece (and the shared object) keep finish_reason
+    expect(first.generationInfo?.finish_reason).toBe('stop');
+    expect(shared.finish_reason).toBe('stop');
+    // the repeat piece got its own cleaned copy
+    expect(second.generationInfo?.finish_reason).toBeUndefined();
+    expect(second.generationInfo).not.toBe(first.generationInfo);
+  });
+});

package/src/llm/openai/streamMetadata.ts

@@ -0,0 +1,95 @@
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+
+/**
+ * `@langchain/openai` stamps these scalar fields together onto every chunk
+ * whose `choice.finish_reason` is set. Providers that emit `finish_reason` on
+ * more than one streamed chunk (e.g. OpenRouter) otherwise make core's
+ * `_mergeDicts` concatenate them into `stopstop` / duplicated model names — in
+ * both the aggregated graph message and the Langfuse trace. Core keeps
+ * `id`/`name`/`model_provider` last but not these, so keep the first occurrence
+ * and drop later repeats at the source, before either aggregation runs.
+ */
+const REPEATED_SCALAR_METADATA_FIELDS = [
+  'model_name',
+  'finish_reason',
+  'service_tier',
+  'system_fingerprint',
+] as const;
+
+/** Per-completion-index set of scalar fields already emitted this stream. */
+export type SeenScalarMetadata = Map<number, Set<string>>;
+
+function completionIndex(
+  generationInfo: Record<string, unknown> | undefined
+): number {
+  const completion = generationInfo?.completion;
+  return typeof completion === 'number' ? completion : 0;
+}
+
+/**
+ * Strip scalar `response_metadata`/`generationInfo` fields that have already
+ * appeared on an earlier chunk of the same completion (tracked in `seen`),
+ * keeping the first occurrence so the aggregated message still carries the
+ * value once. Scoped per completion index so multi-choice (`n > 1`) responses,
+ * which `_generate` aggregates separately, keep each choice's own metadata.
+ *
+ * Deletes from a shallow clone rather than in place: providers such as
+ * `ChatDeepSeek` split one raw chunk into several synthetic pieces that share
+ * the same `response_metadata`/`generationInfo` objects, so mutating in place
+ * would strip fields from sibling chunks that were already emitted.
+ */
+export function dropRepeatedScalarMetadata(
+  chunk: ChatGenerationChunk,
+  seen: SeenScalarMetadata
+): void {
+  const generationInfo = chunk.generationInfo as
+    | Record<string, unknown>
+    | undefined;
+  const responseMetadata = chunk.message.response_metadata as Record<
+    string,
+    unknown
+  >;
+
+  const index = completionIndex(generationInfo);
+  let seenFields = seen.get(index);
+  if (seenFields == null) {
+    seenFields = new Set<string>();
+    seen.set(index, seenFields);
+  }
+
+  const dropFromGenerationInfo: string[] = [];
+  const dropFromResponseMetadata: string[] = [];
+  for (const field of REPEATED_SCALAR_METADATA_FIELDS) {
+    const inGenerationInfo =
+      generationInfo != null && generationInfo[field] != null;
+    const inResponseMetadata = responseMetadata[field] != null;
+    if (!inGenerationInfo && !inResponseMetadata) {
+      continue;
+    }
+    if (!seenFields.has(field)) {
+      seenFields.add(field);
+      continue;
+    }
+    if (inGenerationInfo) {
+      dropFromGenerationInfo.push(field);
+    }
+    if (inResponseMetadata) {
+      dropFromResponseMetadata.push(field);
+    }
+  }
+
+  if (dropFromGenerationInfo.length > 0 && generationInfo != null) {
+    const cloned = { ...generationInfo };
+    for (const field of dropFromGenerationInfo) {
+      delete cloned[field];
+    }
+    chunk.generationInfo = cloned;
+  }
+  if (dropFromResponseMetadata.length > 0) {
+    const cloned = { ...responseMetadata };
+    for (const field of dropFromResponseMetadata) {
+      delete cloned[field];
+    }
+    chunk.message.response_metadata = cloned;
+  }
+}

package/src/llm/openai/streamMetadataDedup.spec.ts

@@ -0,0 +1,166 @@
+import { concat } from '@langchain/core/utils/stream';
+import { expect, test, describe } from '@jest/globals';
+import { HumanMessage, AIMessageChunk } from '@langchain/core/messages';
+import type {
+  NewTokenIndices,
+  HandleLLMNewTokenCallbackFields,
+} from '@langchain/core/callbacks/base';
+import type { LLMResult } from '@langchain/core/outputs';
+import type { OpenAIClient } from '@langchain/openai';
+import { ChatOpenAI } from './index';
+
+/**
+ * Regression for duplicated stream `response_metadata` (issue #14086).
+ *
+ * Providers that emit `finish_reason` on more than one streamed chunk (e.g.
+ * OpenRouter / `openai/gpt-chat-latest`) made LangChain core's `_mergeDicts`
+ * concatenate the scalar fields it stamps alongside finish_reason — producing
+ * `finish_reason: "stopstop"` and duplicated `model_name`. That corruption
+ * appeared in BOTH aggregations: core's `_streamIterator` (feeds `handleLLMEnd`
+ * / the Langfuse GENERATION observation) and any host-side `concat` of the
+ * yielded chunks (the graph message / trace output). Both are exercised here.
+ */
+
+type RawChunk = OpenAIClient.Chat.Completions.ChatCompletionChunk;
+
+const MODEL = 'openai/gpt-chat-latest-20260505';
+
+function stubStream(model: ChatOpenAI, chunks: RawChunk[]): void {
+  (
+    model as unknown as {
+      completions: {
+        completionWithRetry: (
+          request: unknown
+        ) => Promise<AsyncIterable<RawChunk>>;
+      };
+    }
+  ).completions.completionWithRetry = async (): Promise<
+    AsyncIterable<RawChunk>
+  > => ({
+    async *[Symbol.asyncIterator](): AsyncGenerator<RawChunk> {
+      for (const chunk of chunks) {
+        yield chunk;
+      }
+    },
+  });
+}
+
+function rawChunk(
+  delta: Record<string, unknown>,
+  finishReason: 'stop' | null,
+  extra: Partial<RawChunk> = {}
+): RawChunk {
+  return {
+    id: 'chatcmpl-1',
+    object: 'chat.completion.chunk',
+    created: 1,
+    model: MODEL,
+    choices: [
+      {
+        index: 0,
+        delta,
+        finish_reason: finishReason,
+        logprobs: null,
+      },
+    ],
+    ...extra,
+  } as unknown as RawChunk;
+}
+
+async function collect(model: ChatOpenAI): Promise<{
+  coreEnd?: AIMessageChunk;
+  hostConcat?: AIMessageChunk;
+  tokenFinishReasons: unknown[];
+}> {
+  let coreEnd: AIMessageChunk | undefined;
+  const tokenFinishReasons: unknown[] = [];
+  const stream = await model.stream([new HumanMessage('hi')], {
+    callbacks: [
+      {
+        handleLLMEnd(output: LLMResult): void {
+          const generation = output.generations?.[0]?.[0] as
+            | { message?: AIMessageChunk }
+            | undefined;
+          coreEnd = generation?.message;
+        },
+        handleLLMNewToken(
+          _token: string,
+          _idx: NewTokenIndices,
+          _runId: string,
+          _parentRunId?: string,
+          _tags?: string[],
+          fields?: HandleLLMNewTokenCallbackFields
+        ): void {
+          // At emit time the scalars still live in `generationInfo` (core
+          // folds them into `response_metadata` only after it receives the
+          // chunk), so read the surface a token-callback consumer sees here.
+          const chunk = fields?.chunk as
+            | {
+                generationInfo?: Record<string, unknown>;
+                message?: AIMessageChunk;
+              }
+            | undefined;
+          const finishReason =
+            chunk?.generationInfo?.finish_reason ??
+            chunk?.message?.response_metadata?.finish_reason;
+          if (finishReason != null) {
+            tokenFinishReasons.push(finishReason);
+          }
+        },
+      },
+    ],
+  });
+  let hostConcat: AIMessageChunk | undefined;
+  for await (const chunk of stream) {
+    hostConcat = hostConcat == null ? chunk : concat(hostConcat, chunk);
+  }
+  return { coreEnd, hostConcat, tokenFinishReasons };
+}
+
+describe('streamed response_metadata scalar de-duplication', () => {
+  test('collapses repeated finish_reason / model_name across two finish chunks', async () => {
+    const model = new ChatOpenAI({ model: MODEL, apiKey: 'test-key' });
+    stubStream(model, [
+      rawChunk({ role: 'assistant', content: 'Hi' }, 'stop'),
+      rawChunk({ content: '' }, 'stop', {
+        service_tier: 'default',
+      } as Partial<RawChunk>),
+    ]);
+
+    const { coreEnd, hostConcat, tokenFinishReasons } = await collect(model);
+
+    for (const meta of [
+      coreEnd?.response_metadata,
+      hostConcat?.response_metadata,
+    ]) {
+      expect(meta?.finish_reason).toBe('stop');
+      expect(meta?.model_name).toBe(MODEL);
+      // keep-first still preserves a field that only appears on the 2nd chunk
+      expect(meta?.service_tier).toBe('default');
+    }
+    // token callbacks observe the same de-duplicated chunks (finish_reason
+    // stays on the first finish chunk only, never re-emitted on the repeat)
+    expect(tokenFinishReasons).toEqual(['stop']);
+  });
+
+  test('leaves a conformant single-finish stream untouched', async () => {
+    const model = new ChatOpenAI({ model: MODEL, apiKey: 'test-key' });
+    stubStream(model, [
+      rawChunk({ role: 'assistant', content: 'Hi' }, null),
+      rawChunk({ content: '' }, 'stop', {
+        system_fingerprint: 'fp_1',
+      } as Partial<RawChunk>),
+    ]);
+
+    const { coreEnd, hostConcat } = await collect(model);
+
+    for (const meta of [
+      coreEnd?.response_metadata,
+      hostConcat?.response_metadata,
+    ]) {
+      expect(meta?.finish_reason).toBe('stop');
+      expect(meta?.model_name).toBe(MODEL);
+      expect(meta?.system_fingerprint).toBe('fp_1');
+    }
+  });
+});

package/src/llm/openrouter/index.ts

@@ -6,7 +6,9 @@ import type {
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { BaseMessage } from '@langchain/core/messages';
+import type { SeenScalarMetadata } from '@/llm/openai/streamMetadata';
 import type { PromptCacheTtl } from '@/messages/cache';
+import { dropRepeatedScalarMetadata } from '@/llm/openai/streamMetadata';
 import { ChatOpenAI, emitStreamChunkCallback } from '@/llm/openai';
 
 export type OpenRouterReasoningEffort =
@@ -240,8 +242,11 @@ export class ChatOpenRouter extends ChatOpenAI {
       string,
       OpenRouterReasoningEncryptedDetail
     >();
+    // Consume the raw (un-deduped) stream so `finish_reason` survives as the
+    // reasoning-flush signal below; de-duplicate after that, before emitting.
+    const seenScalarMetadata: SeenScalarMetadata = new Map();
 
-    for await (const generationChunk of super._streamResponseChunks(
+    for await (const generationChunk of super._streamRawResponseChunks(
       messages,
       options,
       undefined
@@ -290,12 +295,11 @@ export class ChatOpenRouter extends ChatOpenAI {
         } else {
           delete generationChunk.message.additional_kwargs.reasoning_details;
         }
-        await emitStreamChunkCallback(generationChunk, runManager);
-        yield generationChunk;
-        continue;
+      } else {
+        delete generationChunk.message.additional_kwargs.reasoning_details;
       }
 
-      delete generationChunk.message.additional_kwargs.reasoning_details;
+      dropRepeatedScalarMetadata(generationChunk, seenScalarMetadata);
       await emitStreamChunkCallback(generationChunk, runManager);
       yield generationChunk;
     }