@librechat/agents 3.4.0 → 3.4.2

package/src/messages/format.ts

@@ -339,6 +339,7 @@ interface FormatAssistantMessageOptions {
   preserveUnpairedServerToolUses?: boolean;
   preserveReasoningContent?: boolean;
   provider?: Providers;
+  sourceMessageId?: string;
 }
 
 interface FormatAgentMessagesOptions {
@@ -514,6 +515,16 @@ function formatAssistantMessage(
     | RoleBearingMessage<ToolMessage>
     | RoleBearingMessage<HumanMessage>
   > = [];
+  const appendFormattedMessage = (
+    formattedMessage: (typeof formattedMessages)[number]
+  ): void => {
+    stampSourceMessageIdentity(
+      formattedMessage,
+      options?.sourceMessageId,
+      formattedMessages.length
+    );
+    formattedMessages.push(formattedMessage);
+  };
   let currentContent: MessageContentComplex[] = [];
   let lastAIMessage: RoleBearingMessage<AIMessage> | null = null;
   let hasReasoning = false;
@@ -634,7 +645,7 @@ function formatAssistantMessage(
           ) {
             currentContent.push(part);
             lastAIMessage = createAIMessage(toLangChainContent(currentContent));
-            formattedMessages.push(lastAIMessage);
+            appendFormattedMessage(lastAIMessage);
             currentContent = [];
             continue;
           }
@@ -646,13 +657,13 @@ function formatAssistantMessage(
           }, '');
           content = `${content}\n${getTextContent(part)}`.trim();
           lastAIMessage = createAIMessage(content);
-          formattedMessages.push(lastAIMessage);
+          appendFormattedMessage(lastAIMessage);
           currentContent = [];
           continue;
         }
         // Create a new AIMessage with this text and prepare for tool calls
         lastAIMessage = createAIMessage(getTextContent(part));
-        formattedMessages.push(lastAIMessage);
+        appendFormattedMessage(lastAIMessage);
       } else if (part.type === ContentTypes.TOOL_CALL) {
         // Skip malformed tool call entries without tool_call property
         if (part.tool_call == null) {
@@ -711,7 +722,7 @@ function formatAssistantMessage(
         if (!lastAIMessage) {
           // "Heal" the payload by creating an AIMessage to precede the tool call
           lastAIMessage = createAIMessage('');
-          formattedMessages.push(lastAIMessage);
+          appendFormattedMessage(lastAIMessage);
         } else {
           attachPendingReasoningContent(lastAIMessage);
         }
@@ -749,7 +760,7 @@ function formatAssistantMessage(
           lastAIMessage.tool_calls.push(tool_call as ToolCall);
         }
 
-        formattedMessages.push(
+        appendFormattedMessage(
           withMessageRole(
             new ToolMessage({
               tool_call_id: tool_call.id ?? '',
@@ -788,14 +799,14 @@ function formatAssistantMessage(
             currentContent.some((content) => content.type !== ContentTypes.TEXT)
           ) {
             lastAIMessage = createAIMessage(toLangChainContent(currentContent));
-            formattedMessages.push(lastAIMessage);
+            appendFormattedMessage(lastAIMessage);
           } else {
             const flushed = currentContent
               .reduce((acc, curr) => `${acc}${getTextContent(curr)}\n`, '')
               .trim();
             if (flushed.length > 0) {
               lastAIMessage = createAIMessage(flushed);
-              formattedMessages.push(lastAIMessage);
+              appendFormattedMessage(lastAIMessage);
             }
           }
           currentContent = [];
@@ -808,7 +819,7 @@ function formatAssistantMessage(
            * assistant reasoning silently vanishes on replay.
            */
           lastAIMessage = createAIMessage('');
-          formattedMessages.push(lastAIMessage);
+          appendFormattedMessage(lastAIMessage);
         }
         const steerPart = part as {
           steer?: string;
@@ -818,7 +829,7 @@ function formatAssistantMessage(
           Array.isArray(steerPart.media) && steerPart.media.length > 0
             ? toLangChainContent(steerPart.media)
             : (steerPart.steer ?? '');
-        formattedMessages.push(
+        appendFormattedMessage(
           withMessageRole(
             new HumanMessage({
               content: steerContent as MessageContent,
@@ -856,7 +867,7 @@ function formatAssistantMessage(
     let content = '';
     for (const part of currentContent) {
       if (part.type !== ContentTypes.TEXT) {
-        formattedMessages.push(
+        appendFormattedMessage(
           createAIMessage(toLangChainContent(currentContent))
         );
         return formattedMessages;
@@ -866,10 +877,10 @@ function formatAssistantMessage(
     content = content.trim();
 
     if (content) {
-      formattedMessages.push(createAIMessage(content));
+      appendFormattedMessage(createAIMessage(content));
     }
   } else if (currentContent.length > 0) {
-    formattedMessages.push(createAIMessage(toLangChainContent(currentContent)));
+    appendFormattedMessage(createAIMessage(toLangChainContent(currentContent)));
   }
 
   return formattedMessages;
@@ -886,6 +897,29 @@ function getSourceMessageId(message: Partial<TMessage>): string | undefined {
   return normalized.length > 0 ? normalized : undefined;
 }
 
+/**
+ * Keeps the first formatted message backward-compatible with its persisted
+ * source id and preserves source correlation on every derived message.
+ * Derived ids remain unset so the reducer can assign collision-free identities
+ * during its existing pass. This also prevents invented provider-shaped ids
+ * from leaking into provider request payloads.
+ */
+function stampSourceMessageIdentity(
+  message: RoleBearingMessage<BaseMessage>,
+  sourceMessageId: string | undefined,
+  derivedIndex = 0
+): void {
+  if (sourceMessageId == null) {
+    return;
+  }
+  message.additional_kwargs.sourceMessageId = sourceMessageId;
+  if (derivedIndex !== 0) {
+    return;
+  }
+  message.id = sourceMessageId;
+  message.lc_kwargs.id = sourceMessageId;
+}
+
 /**
  * Labels all agent content for parallel patterns (fan-out/fan-in)
  * Groups consecutive content by agent and wraps with clear labels
@@ -1565,9 +1599,7 @@ export const formatAgentMessages = (
         | RoleBearingMessage<HumanMessage>
         | RoleBearingMessage<AIMessage>
         | RoleBearingMessage<SystemMessage>;
-      if (sourceMessageId != null && sourceMessageId !== '') {
-        formattedMessage.id = sourceMessageId;
-      }
+      stampSourceMessageIdentity(formattedMessage, sourceMessageId);
       flushSteerAnchor(formattedMessage);
       messages.push(formattedMessage);
 
@@ -1746,12 +1778,8 @@ export const formatAgentMessages = (
         options?.preserveReasoningContent ??
         options?.provider === Providers.DEEPSEEK,
       provider: options?.provider,
+      sourceMessageId,
     });
-    if (sourceMessageId != null && sourceMessageId !== '') {
-      for (const formattedMessage of formattedMessages) {
-        formattedMessage.id = sourceMessageId;
-      }
-    }
     /**
      * A steer that ends an assistant message leaves the replay on a
      * `HumanMessage`. The next payload message is itself a user turn, so the
@@ -1775,12 +1803,12 @@ export const formatAgentMessages = (
      * the model may simply never answer. So the intent is recorded and flushed
      * only when a message actually follows.
      *
-     * Pushed AFTER the id stamping above, deliberately. `messagesStateReducer`
-     * treats a repeated id as replace-in-place, so an anchor carrying the
-     * shared `sourceMessageId` would overwrite the steer it exists to protect.
-     * Left unstamped, it reaches the reducer with a null id and is assigned a
-     * fresh one. `endsWithSteerMessage` reads only `additional_kwargs.source`,
-     * so the deferral cannot change which messages get anchored.
+     * Pushed AFTER source identity stamping above, deliberately. The anchor is
+     * synthetic rather than derived from the persisted assistant entry, so it
+     * must not claim that entry's source metadata. Left unstamped, it reaches
+     * the reducer with a null id and is assigned a fresh one.
+     * `endsWithSteerMessage` reads only `additional_kwargs.source`, so the
+     * deferral cannot change which messages get anchored.
      */
     /**
      * Guarded on emission: an assistant entry whose blocks all filtered away

package/src/messages/formatAgentMessages.reducer.test.ts

@@ -0,0 +1,162 @@
+import { convertMessagesToResponsesInput } from '@langchain/openai';
+import { Annotation, END, START, StateGraph } from '@langchain/langgraph';
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { messagesStateReducer } from './reducer';
+import { formatAgentMessages } from './format';
+import { ContentTypes } from '@/common';
+
+const formatToolTurn = () =>
+  formatAgentMessages([
+    {
+      role: 'assistant',
+      messageId: 'msg_assistant_1',
+      content: [
+        {
+          type: ContentTypes.TEXT,
+          [ContentTypes.TEXT]: 'Running tool',
+          tool_call_ids: ['tool_1'],
+        },
+        {
+          type: ContentTypes.TOOL_CALL,
+          tool_call: {
+            id: 'tool_1',
+            name: 'search',
+            args: '{"query":"hello"}',
+            output: 'world',
+          },
+        },
+      ],
+    },
+  ]).messages;
+
+describe('formatAgentMessages reducer compatibility', () => {
+  it('does not expose derived message ids as OpenAI Responses item ids', () => {
+    const messages = formatAgentMessages([
+      {
+        role: 'assistant',
+        messageId: 'msg_provider_1',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Running tool',
+            tool_call_ids: ['tool_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'tool_1',
+              name: 'search',
+              args: '{"query":"hello"}',
+              output: 'world',
+            },
+          },
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Finished',
+          },
+        ],
+      },
+    ]).messages;
+    const input = convertMessagesToResponsesInput({
+      messages,
+      zdrEnabled: false,
+      model: 'gpt-5.6',
+    });
+
+    expect(
+      input
+        .filter((item) => item.type === 'message')
+        .map((item) => ('id' in item ? item.id : undefined))
+    ).toEqual(['msg_provider_1', undefined]);
+  });
+
+  it('does not let a later source id replace a derived message', () => {
+    const messages = formatAgentMessages([
+      {
+        role: 'assistant',
+        messageId: 'a',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Running tool',
+            tool_call_ids: ['tool_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'tool_1',
+              name: 'search',
+              args: '{"query":"hello"}',
+              output: 'world',
+            },
+          },
+        ],
+      },
+      {
+        role: 'user',
+        messageId: 'a:derived:1',
+        content: 'Continue',
+      },
+    ]).messages;
+
+    const merged = messagesStateReducer([], messages);
+
+    expect(merged).toHaveLength(3);
+    expect(merged[0]).toBeInstanceOf(AIMessage);
+    expect(merged[1]).toBeInstanceOf(ToolMessage);
+    expect(merged[2]).toBeInstanceOf(HumanMessage);
+  });
+
+  it('lets the reducer identify derived messages while retaining source correlation', () => {
+    const messages = formatToolTurn();
+
+    expect(messages).toHaveLength(2);
+    expect(messages[0]).toBeInstanceOf(AIMessage);
+    expect(messages[1]).toBeInstanceOf(ToolMessage);
+    expect(messages.map((message) => message.id)).toEqual([
+      'msg_assistant_1',
+      undefined,
+    ]);
+    expect(messages.map((message) => message.lc_kwargs.id)).toEqual([
+      'msg_assistant_1',
+      undefined,
+    ]);
+    expect(
+      messages.map((message) => message.additional_kwargs.sourceMessageId)
+    ).toEqual(['msg_assistant_1', 'msg_assistant_1']);
+
+    const merged = messagesStateReducer([], messages);
+    expect(merged).toHaveLength(2);
+    expect(merged[0]).toBeInstanceOf(AIMessage);
+    expect(merged[1]).toBeInstanceOf(ToolMessage);
+    expect(merged[0].id).toBe('msg_assistant_1');
+    expect(merged[1].id).toEqual(expect.any(String));
+    expect(merged[1].id).not.toBe(merged[0].id);
+  });
+
+  it('preserves the tool-call pair through a StateGraph input write', async () => {
+    const State = Annotation.Root({
+      messages: Annotation<BaseMessage[]>({
+        reducer: messagesStateReducer,
+        default: () => [],
+      }),
+    });
+    let observedMessages: BaseMessage[] = [];
+    const graph = new StateGraph(State)
+      .addNode('capture', (state) => {
+        observedMessages = state.messages;
+        return {};
+      })
+      .addEdge(START, 'capture')
+      .addEdge('capture', END)
+      .compile();
+
+    await graph.invoke({ messages: formatToolTurn() });
+
+    expect(observedMessages).toHaveLength(2);
+    expect(observedMessages[0]).toBeInstanceOf(AIMessage);
+    expect((observedMessages[0] as AIMessage).tool_calls).toHaveLength(1);
+    expect(observedMessages[1]).toBeInstanceOf(ToolMessage);
+  });
+});

package/src/messages/formatAgentMessages.steer.test.ts

@@ -370,12 +370,9 @@ describe('formatAgentMessages trailing-steer anchor', () => {
     expect(following.content).toEqual([{ type: 'text', text: 'Next turn' }]);
   });
 
-  /**
-   * `messagesStateReducer` treats a repeated id as replace-in-place, so an
-   * anchor stamped with the shared `sourceMessageId` would overwrite the very
-   * steer it exists to protect. It must reach the reducer unstamped.
-   */
-  it('does not stamp the anchor with the shared source message id', () => {
+  /** The synthetic anchor is not derived from the persisted assistant entry,
+   *  so it must not inherit that entry's source identity metadata. */
+  it('does not stamp the anchor with the source message identity', () => {
     const payload: TPayload = [
       { role: 'user', content: 'Original request' },
       {
@@ -395,13 +392,20 @@ describe('formatAgentMessages trailing-steer anchor', () => {
       (message) => message.additional_kwargs.source === 'steer'
     );
     expect(steerIndex).toBeGreaterThan(0);
-    expect(messages[steerIndex].id).toBe('assistant_1');
+    expect(messages[steerIndex].id).toBeUndefined();
     expect(messages[steerIndex - 1].id).toBe('assistant_1');
+    expect(messages[steerIndex].additional_kwargs.sourceMessageId).toBe(
+      'assistant_1'
+    );
+    expect(messages[steerIndex - 1].additional_kwargs.sourceMessageId).toBe(
+      'assistant_1'
+    );
 
     const anchor = messages[steerIndex + 1];
     expect(anchor).toBeInstanceOf(AIMessage);
     expect(anchor.content).not.toBe('');
     expect(anchor.id).not.toBe('assistant_1');
+    expect(anchor.additional_kwargs.sourceMessageId).toBeUndefined();
   });
 
   /**
@@ -469,9 +473,7 @@ describe('formatAgentMessages trailing-steer anchor', () => {
     const last = messages[messages.length - 1];
     expect(last.additional_kwargs.source).toBe('steer');
     expect(
-      messages.some(
-        (m) => m instanceof AIMessage && m.content === '_'
-      )
+      messages.some((m) => m instanceof AIMessage && m.content === '_')
     ).toBe(false);
   });
 
@@ -536,7 +538,10 @@ describe('formatAgentMessages trailing-steer anchor', () => {
       {
         role: 'assistant',
         content: [
-          { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Doing the other thing.' },
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Doing the other thing.',
+          },
         ],
       },
     ];

package/src/messages/formatAgentMessages.test.ts

@@ -76,7 +76,7 @@ describe('formatAgentMessages', () => {
     expect(Object.keys(result.messages[1])).not.toContain('role');
   });
 
-  it('preserves source messageId on formatted messages', () => {
+  it('preserves source messageId correlation with unique formatted ids', () => {
     const payload: TPayload = [
       {
         role: 'assistant',
@@ -112,8 +112,13 @@ describe('formatAgentMessages', () => {
       'user',
     ]);
     expect(result.messages[0].id).toBe('msg_assistant_1');
-    expect(result.messages[1].id).toBe('msg_assistant_1');
+    expect(result.messages[1].id).toBeUndefined();
     expect(result.messages[2].id).toBe('msg_user_1');
+    expect(
+      result.messages.map(
+        (message) => message.additional_kwargs.sourceMessageId
+      )
+    ).toEqual(['msg_assistant_1', 'msg_assistant_1', 'msg_user_1']);
   });
 
   it('should handle system messages', () => {