@librechat/agents 3.2.1 → 3.2.21

package/src/llm/custom-chat-models.smoke.test.ts

@@ -135,6 +135,22 @@ type OpenRouterReasoningStreamChoice = Omit<
 > & {
   delta: OpenRouterReasoningStreamDelta;
 };
+type OpenAICompatibleReasoningStreamDelta =
+  OpenAIClient.Chat.Completions.ChatCompletionChunk.Choice.Delta & {
+    reasoning?: string;
+    reasoning_details?: Array<{
+      type: 'reasoning.text';
+      text?: string;
+      format?: string;
+      index?: number;
+    }>;
+  };
+type OpenAICompatibleReasoningStreamChoice = Omit<
+  OpenAIClient.Chat.Completions.ChatCompletionChunk.Choice,
+  'delta'
+> & {
+  delta: OpenAICompatibleReasoningStreamDelta;
+};
 type PromptTokensDetailsWithCacheWrite = NonNullable<
   OpenAIClient.Completions.CompletionUsage['prompt_tokens_details']
 > & {
@@ -472,6 +488,104 @@ describe('custom chat model class smoke tests', () => {
     );
   });
 
+  it('preserves OpenAI-compatible reasoning deltas during OpenAI streaming', async () => {
+    const model = new ChatOpenAI({
+      model: 'openai/gpt-oss-120b',
+      apiKey: 'test-key',
+      streaming: true,
+    });
+    const completions = (model as unknown as StreamingCompletionBackedModel)
+      .completions;
+    const createChunk = (
+      choice: OpenAICompatibleReasoningStreamChoice
+    ): OpenAIClient.Chat.Completions.ChatCompletionChunk => ({
+      id: 'chatcmpl-openai-compatible-reasoning',
+      object: 'chat.completion.chunk',
+      created: 0,
+      model: 'openai/gpt-oss-120b',
+      choices: [choice],
+    });
+
+    async function* streamChunks(): AsyncGenerator<OpenAIClient.Chat.Completions.ChatCompletionChunk> {
+      yield createChunk({
+        index: 0,
+        delta: {
+          role: 'assistant',
+          content: '',
+        },
+        finish_reason: null,
+      });
+      yield createChunk({
+        index: 0,
+        delta: {
+          reasoning: 'Think ',
+          reasoning_details: [
+            {
+              type: 'reasoning.text',
+              text: 'Think ',
+              format: 'text',
+              index: 0,
+            },
+          ],
+        },
+        finish_reason: null,
+      });
+      yield createChunk({
+        index: 0,
+        delta: {
+          reasoning: 'hard',
+          reasoning_details: [
+            {
+              type: 'reasoning.text',
+              text: 'hard',
+              format: 'text',
+              index: 0,
+            },
+          ],
+        },
+        finish_reason: null,
+      });
+      yield createChunk({
+        index: 0,
+        delta: { content: 'answer' },
+        finish_reason: 'stop',
+      });
+    }
+
+    completions.completionWithRetry = async (): Promise<
+      AsyncIterable<OpenAIClient.Chat.Completions.ChatCompletionChunk>
+    > => streamChunks();
+
+    const chunks: AIMessageChunk[] = [];
+    const stream = await model.stream([new HumanMessage('think')]);
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    expect(
+      chunks
+        .map((chunk) => chunk.additional_kwargs.reasoning_content)
+        .filter((reasoningContent) => reasoningContent != null)
+    ).toEqual(['Think ', 'hard']);
+    expect(chunks[1].additional_kwargs.reasoning_details).toEqual([
+      {
+        type: 'reasoning.text',
+        text: 'Think ',
+        format: 'text',
+        index: 0,
+      },
+    ]);
+    expect(chunks[2].additional_kwargs.reasoning_details).toEqual([
+      {
+        type: 'reasoning.text',
+        text: 'hard',
+        format: 'text',
+        index: 0,
+      },
+    ]);
+    expect(chunks.at(-1)?.content).toBe('answer');
+  });
+
   it('skips custom OpenAI-compatible SSE events during Azure streaming', async () => {
     await expectCustomSSEEventsSkipped(
       new AzureChatOpenAI({

package/src/run.ts

@@ -1,5 +1,8 @@
 // src/run.ts
-import { initializeLangfuseTracing } from './instrumentation';
+import {
+  initializeLangfuseTracing,
+  runWithTraceIdSeed,
+} from './instrumentation';
 import { PromptTemplate } from '@langchain/core/prompts';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';
@@ -552,9 +555,7 @@ export class Run<_T extends t.BaseGraphState> {
   }
 
   private shouldClearHookSession(streamThrew: boolean): boolean {
-    return (
-      this._interrupt == null || this._haltedReason != null || streamThrew
-    );
+    return this._interrupt == null || this._haltedReason != null || streamThrew;
   }
 
   private isAwaitingResume(streamThrew: boolean): boolean {
@@ -584,9 +585,7 @@ export class Run<_T extends t.BaseGraphState> {
   private getStreamToolOutputTracingLangfuseConfig(
     graph: StandardGraph | MultiAgentGraph
   ): t.LangfuseConfig | undefined {
-    const toolOutputTracingConfigs = Array.from(
-      graph.agentContexts.values()
-    )
+    const toolOutputTracingConfigs = Array.from(graph.agentContexts.values())
       .map((context) => {
         return resolveLangfuseConfig(this.langfuse, context.langfuse)
           ?.toolOutputTracing;
@@ -906,10 +905,19 @@ export class Run<_T extends t.BaseGraphState> {
     };
 
     try {
-      await withLangfuseToolOutputTracingConfig(
-        streamLangfuseConfig,
-        consumeStream,
-        this.getStreamToolOutputTracingLangfuseConfig(graph)
+      // When opted in, seed the root trace id from this run's id so feedback /
+      // other external signals can be attached to the trace later without a
+      // lookup (see SeededTraceIdGenerator in ./instrumentation).
+      await runWithTraceIdSeed(
+        streamLangfuseConfig?.deterministicTraceId === true
+          ? this.id
+          : undefined,
+        () =>
+          withLangfuseToolOutputTracingConfig(
+            streamLangfuseConfig,
+            consumeStream,
+            this.getStreamToolOutputTracingLangfuseConfig(graph)
+          )
       );
     } catch (err) {
       streamThrew = true;

package/src/specs/deterministic-trace-id.test.ts

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto';
+import {
+  initializeLangfuseTracing,
+  runWithTraceIdSeed,
+} from '@/instrumentation';
+
+const langfuse = {
+  publicKey: 'pk-lf-test',
+  secretKey: 'sk-lf-test',
+  baseUrl: 'http://localhost:3999',
+};
+
+/** sha256(seed) → first 32 hex chars; what `@langfuse/tracing` `createTraceId` produces. */
+const expectedTraceId = (seed: string): string =>
+  createHash('sha256').update(seed, 'utf8').digest('hex').slice(0, 32);
+
+describe('deterministic Langfuse trace ids', () => {
+  it('derives the root trace id from the seed when run inside runWithTraceIdSeed', () => {
+    const provider = initializeLangfuseTracing(langfuse);
+    expect(provider).toBeDefined();
+    const tracer = provider!.getTracer('deterministic-trace-id-test');
+
+    const seed = 'response-message-id-1234';
+    let traceId: string | undefined;
+    runWithTraceIdSeed(seed, () => {
+      const span = tracer.startSpan('AgentRun');
+      traceId = span.spanContext().traceId;
+      span.end();
+    });
+
+    expect(traceId).toBe(expectedTraceId(seed));
+  });
+
+  it('falls back to a random trace id when no seed is active', () => {
+    const provider = initializeLangfuseTracing(langfuse);
+    const tracer = provider!.getTracer('deterministic-trace-id-test');
+
+    const span = tracer.startSpan('AgentRun');
+    const traceId = span.spanContext().traceId;
+    span.end();
+
+    expect(traceId).toMatch(/^[0-9a-f]{32}$/);
+    expect(traceId).not.toBe(expectedTraceId('response-message-id-1234'));
+  });
+
+  it('runWithTraceIdSeed is a passthrough when the seed is undefined', () => {
+    const sentinel = {};
+    expect(runWithTraceIdSeed(undefined, () => sentinel)).toBe(sentinel);
+  });
+});

package/src/types/graph.ts

@@ -445,6 +445,14 @@ export interface LangfuseConfig {
   baseUrl?: string;
   toolNodeTracing?: LangfuseToolNodeTracingConfig;
   toolOutputTracing?: LangfuseToolOutputTracingConfig;
+  /**
+   * When true, derive the run's root Langfuse trace id deterministically from
+   * its `runId` (`sha256(runId)` → 32 hex chars, matching `@langfuse/tracing`
+   * `createTraceId`) instead of a random id. This lets external systems attach
+   * scores or observations to the trace afterwards by regenerating the same id
+   * from the run/message id, without a trace lookup. Default: random ids.
+   */
+  deterministicTraceId?: boolean;
 }
 
 export interface AgentInputs {