@librechat/agents 3.3.0 → 3.3.2

package/src/stream.ts

@@ -1813,9 +1813,22 @@ hasToolCallChunks: ${hasToolCallChunks}
 }
 
 export function createContentAggregator(): t.ContentAggregatorResult {
+  type ToolStepContentState = {
+    indices: Set<number>;
+    chunkIndices: Map<number, number>;
+    unclaimedIndices: Set<number>;
+    unboundIndices: Set<number>;
+    callIdsByIndex: Map<number, string>;
+  };
+
   const contentParts: Array<t.MessageContentComplex | undefined> = [];
   const stepMap = new Map<string, t.RunStep>();
-  const toolCallIdMap = new Map<string, string>();
+  const toolCallContentIndexMap = new Map<string, number>();
+  const sourceContentIndexMap = new Map<number, number>();
+  const toolStepContentMap = new Map<string, ToolStepContentState>();
+  let indexedContentLength = 0;
+  /** Physical append cursor; event/chunk indices are correlation keys, not array offsets. */
+  let nextContentIndex = 0;
   // Track agentId and groupId for each content index (applied to content parts)
   const contentMetaMap = new Map<
     number,
@@ -1829,6 +1842,137 @@ export function createContentAggregator(): t.ContentAggregatorResult {
     }
     return Array.isArray(content) ? content[0] : content;
   };
+  const indexContentPart = (
+    index: number,
+    contentPart?: t.MessageContentComplex
+  ): void => {
+    if (contentPart == null) {
+      return;
+    }
+    if (contentPart.type === ContentTypes.TOOL_CALL) {
+      const toolCallId = contentPart.tool_call.id;
+      if (toolCallId != null && toolCallId !== '') {
+        toolCallContentIndexMap.set(toolCallId, index);
+      }
+    }
+    const hasAgentId =
+      contentPart.agentId != null && contentPart.agentId !== '';
+    const hasGroupId = contentPart.groupId != null;
+    if (hasAgentId || hasGroupId) {
+      const existingMeta = contentMetaMap.get(index) ?? {};
+      if (hasAgentId) {
+        existingMeta.agentId = contentPart.agentId;
+      }
+      if (hasGroupId) {
+        existingMeta.groupId = contentPart.groupId;
+      }
+      contentMetaMap.set(index, existingMeta);
+    }
+  };
+  const syncSeededContent = (): void => {
+    /** Hosts can seed pre-pause content after creating the aggregator. */
+    for (
+      let index = indexedContentLength;
+      index < contentParts.length;
+      index++
+    ) {
+      indexContentPart(index, contentParts[index]);
+    }
+    indexedContentLength = contentParts.length;
+    nextContentIndex = Math.max(nextContentIndex, contentParts.length);
+  };
+  const getToolCallContentIndex = (
+    toolCallId: string | undefined
+  ): number | undefined => {
+    if (toolCallId == null || toolCallId === '') {
+      return undefined;
+    }
+    syncSeededContent();
+    return toolCallContentIndexMap.get(toolCallId);
+  };
+  const allocateContentIndex = (minimumIndex = 0): number => {
+    syncSeededContent();
+    const contentIndex = Math.max(nextContentIndex, minimumIndex);
+    nextContentIndex = contentIndex + 1;
+    return contentIndex;
+  };
+  const resolveSourceContentIndex = (sourceIndex: number): number => {
+    const existingIndex = sourceContentIndexMap.get(sourceIndex);
+    if (existingIndex != null) {
+      return existingIndex;
+    }
+    const contentIndex = allocateContentIndex(sourceIndex);
+    sourceContentIndexMap.set(sourceIndex, contentIndex);
+    return contentIndex;
+  };
+  const createToolStepContentState = (
+    contentIndex: number
+  ): ToolStepContentState => ({
+    indices: new Set<number>([contentIndex]),
+    chunkIndices: new Map<number, number>(),
+    unclaimedIndices: new Set<number>([contentIndex]),
+    unboundIndices: new Set<number>([contentIndex]),
+    callIdsByIndex: new Map<number, string>(),
+  });
+  const registerToolContentIndex = (
+    state: ToolStepContentState,
+    contentIndex: number,
+    toolCallId?: string
+  ): void => {
+    if (!state.indices.has(contentIndex)) {
+      state.indices.add(contentIndex);
+      state.unclaimedIndices.add(contentIndex);
+      state.unboundIndices.add(contentIndex);
+    }
+    if (toolCallId != null && toolCallId !== '') {
+      const existingToolCallId = state.callIdsByIndex.get(contentIndex);
+      if (
+        existingToolCallId != null &&
+        existingToolCallId !== toolCallId &&
+        toolCallContentIndexMap.get(existingToolCallId) === contentIndex
+      ) {
+        toolCallContentIndexMap.delete(existingToolCallId);
+      }
+      toolCallContentIndexMap.set(toolCallId, contentIndex);
+      state.callIdsByIndex.set(contentIndex, toolCallId);
+      state.unboundIndices.delete(contentIndex);
+    }
+  };
+  const takeFirstIndex = (indices: Set<number>): number | undefined => {
+    const contentIndex = indices.values().next().value;
+    if (contentIndex != null) {
+      indices.delete(contentIndex);
+    }
+    return contentIndex;
+  };
+  const setContentMeta = (index: number, runStep: t.RunStep): void => {
+    const hasAgentId = runStep.agentId != null && runStep.agentId !== '';
+    const hasGroupId = runStep.groupId != null;
+    if (!hasAgentId && !hasGroupId) {
+      return;
+    }
+    const existingMeta = contentMetaMap.get(index) ?? {};
+    if (hasAgentId) {
+      existingMeta.agentId = runStep.agentId;
+    }
+    if (hasGroupId) {
+      existingMeta.groupId = runStep.groupId;
+    }
+    contentMetaMap.set(index, existingMeta);
+  };
+  const applyContentMetadata = (index: number): void => {
+    const contentPart = contentParts[index];
+    if (contentPart == null) {
+      return;
+    }
+    const meta = contentMetaMap.get(index);
+    if (meta?.agentId != null) {
+      contentPart.agentId = meta.agentId;
+    }
+    if (meta?.groupId != null) {
+      contentPart.groupId = meta.groupId;
+    }
+  };
 
   const updateContent = (
     index: number,
@@ -1964,6 +2108,15 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       const name =
         getNonEmptyValue([incomingName, existingContent?.tool_call?.name]) ??
         '';
+      const existingToolCallId = existingContent?.tool_call?.id;
+      if (
+        existingToolCallId != null &&
+        existingToolCallId !== '' &&
+        existingToolCallId !== id &&
+        toolCallContentIndexMap.get(existingToolCallId) === index
+      ) {
+        toolCallContentIndexMap.delete(existingToolCallId);
+      }
 
       const newToolCall: ToolCall & t.PartMetadata = {
         id,
@@ -1991,18 +2144,14 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         type: ContentTypes.TOOL_CALL,
         tool_call: newToolCall,
       };
+      indexContentPart(index, contentParts[index]);
+      indexedContentLength = Math.max(indexedContentLength, index + 1);
     }
 
     // Apply agentId (for MultiAgentGraph) and groupId (for parallel execution) to content parts
     // - agentId present → MultiAgentGraph (show agent labels)
     // - groupId present → parallel execution (render columns)
-    const meta = contentMetaMap.get(index);
-    if (meta?.agentId != null) {
-      (contentParts[index] as t.MessageContentComplex).agentId = meta.agentId;
-    }
-    if (meta?.groupId != null) {
-      (contentParts[index] as t.MessageContentComplex).groupId = meta.groupId;
-    }
+    applyContentMetadata(index);
   };
 
   const aggregateContent = ({
@@ -2046,53 +2195,78 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       // concatenate in updateContent.  This event carries only the correct
       // final text from the last stage.
       contentParts[runStep.index] = summary;
+      applyContentMetadata(runStep.index);
       return;
     }
 
     if (event === GraphEvents.ON_RUN_STEP) {
-      const runStep = data as t.RunStep;
-      stepMap.set(runStep.id, runStep);
-
-      // Track agentId (MultiAgentGraph) and groupId (parallel execution) separately
-      // - agentId: present for all MultiAgentGraph runs (enables agent labels in UI)
-      // - groupId: present only for parallel execution (enables column rendering)
-      const hasAgentId = runStep.agentId != null && runStep.agentId !== '';
-      const hasGroupId = runStep.groupId != null;
-      if (hasAgentId || hasGroupId) {
-        const existingMeta = contentMetaMap.get(runStep.index) ?? {};
-        if (hasAgentId) {
-          existingMeta.agentId = runStep.agentId;
-        }
-        if (hasGroupId) {
-          existingMeta.groupId = runStep.groupId;
+      const incomingRunStep = data as t.RunStep;
+      const toolCalls =
+        incomingRunStep.stepDetails.type === StepTypes.TOOL_CALLS
+          ? (incomingRunStep.stepDetails.tool_calls as ToolCall[] | undefined)
+          : undefined;
+      syncSeededContent();
+      let runStepIndex: number;
+      const toolCallIndices: number[] = [];
+      if (toolCalls && toolCalls.length > 0) {
+        for (let index = 0; index < toolCalls.length; index++) {
+          const toolCallId = toolCalls[index].id;
+          let contentIndex = getToolCallContentIndex(toolCallId);
+          if (contentIndex == null) {
+            contentIndex =
+              index === 0
+                ? resolveSourceContentIndex(incomingRunStep.index)
+                : allocateContentIndex();
+          } else if (index === 0) {
+            sourceContentIndexMap.set(incomingRunStep.index, contentIndex);
+          }
+          toolCallIndices.push(contentIndex);
         }
-        contentMetaMap.set(runStep.index, existingMeta);
+        runStepIndex = toolCallIndices[0];
+      } else {
+        runStepIndex = resolveSourceContentIndex(incomingRunStep.index);
       }
+      const runStep =
+        runStepIndex !== incomingRunStep.index
+          ? { ...incomingRunStep, index: runStepIndex }
+          : incomingRunStep;
+      stepMap.set(runStep.id, runStep);
+
+      setContentMeta(runStep.index, runStep);
 
       if (runStep.summary != null) {
         updateContent(runStep.index, runStep.summary);
       }
 
-      if (
-        runStep.stepDetails.type === StepTypes.TOOL_CALLS &&
-        runStep.stepDetails.tool_calls
-      ) {
-        (runStep.stepDetails.tool_calls as ToolCall[]).forEach((toolCall) => {
-          const toolCallId = toolCall.id ?? '';
-          if ('id' in toolCall && toolCallId) {
-            toolCallIdMap.set(runStep.id, toolCallId);
-          }
-          const contentPart: t.MessageContentComplex = {
-            type: ContentTypes.TOOL_CALL,
-            tool_call: {
-              args: toolCall.args,
-              name: toolCall.name,
-              id: toolCallId,
-            },
-          };
+      if (runStep.stepDetails.type === StepTypes.TOOL_CALLS) {
+        const toolStepContent =
+          toolStepContentMap.get(runStep.id) ??
+          createToolStepContentState(runStep.index);
+        registerToolContentIndex(toolStepContent, runStep.index);
+        (runStep.stepDetails.tool_calls as ToolCall[] | undefined)?.forEach(
+          (toolCall, toolCallIndex) => {
+            const contentIndex =
+              toolCallIndices[toolCallIndex] ?? runStep.index;
+            const toolCallId = toolCall.id ?? '';
+            registerToolContentIndex(
+              toolStepContent,
+              contentIndex,
+              toolCallId
+            );
+            const contentPart: t.MessageContentComplex = {
+              type: ContentTypes.TOOL_CALL,
+              tool_call: {
+                args: toolCall.args,
+                name: toolCall.name,
+                id: toolCallId,
+              },
+            };
 
-          updateContent(runStep.index, contentPart);
-        });
+            setContentMeta(contentIndex, runStep);
+            updateContent(contentIndex, contentPart);
+          }
+        );
+        toolStepContentMap.set(runStep.id, toolStepContent);
       }
     } else if (event === GraphEvents.ON_MESSAGE_DELTA) {
       const messageDelta = data as t.MessageDeltaEvent;
@@ -2114,7 +2288,16 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       if (!contentPart) {
         return;
       }
-      updateContent(contentPart.agent_update.index, contentPart);
+      const contentIndex = resolveSourceContentIndex(
+        contentPart.agent_update.index
+      );
+      updateContent(contentIndex, {
+        ...contentPart,
+        agent_update: {
+          ...contentPart.agent_update,
+          index: contentIndex,
+        },
+      });
     } else if (event === GraphEvents.ON_REASONING_DELTA) {
       const reasoningDelta = data as t.ReasoningDeltaEvent;
       const runStep = stepMap.get(reasoningDelta.id);
@@ -2139,8 +2322,62 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         runStepDelta.delta.type === StepTypes.TOOL_CALLS &&
         runStepDelta.delta.tool_calls
       ) {
+        const toolStepContent =
+          toolStepContentMap.get(runStepDelta.id) ??
+          createToolStepContentState(runStep.index);
         runStepDelta.delta.tool_calls.forEach((toolCallDelta) => {
-          const toolCallId = toolCallIdMap.get(runStepDelta.id);
+          const chunkIndex =
+            typeof toolCallDelta.index === 'number'
+              ? toolCallDelta.index
+              : undefined;
+          const explicitToolCallId =
+            toolCallDelta.id != null && toolCallDelta.id !== ''
+              ? toolCallDelta.id
+              : undefined;
+          let contentIndex = getToolCallContentIndex(explicitToolCallId);
+          if (contentIndex == null && chunkIndex != null) {
+            contentIndex = toolStepContent.chunkIndices.get(chunkIndex);
+          }
+          const soleContentIndex =
+            toolStepContent.indices.size === 1
+              ? toolStepContent.indices.values().next().value
+              : undefined;
+          if (
+            contentIndex == null &&
+            explicitToolCallId == null &&
+            soleContentIndex != null &&
+            (chunkIndex == null ||
+              toolStepContent.callIdsByIndex.has(soleContentIndex) ||
+              toolStepContent.unclaimedIndices.has(soleContentIndex))
+          ) {
+            contentIndex = soleContentIndex;
+          }
+          if (contentIndex == null) {
+            if (chunkIndex == null && explicitToolCallId == null) {
+              console.warn(
+                'No tool call id or chunk index found for run step delta event'
+              );
+              return;
+            }
+            contentIndex =
+              explicitToolCallId == null
+                ? takeFirstIndex(toolStepContent.unclaimedIndices)
+                : takeFirstIndex(toolStepContent.unboundIndices);
+            contentIndex ??= allocateContentIndex();
+          }
+          registerToolContentIndex(
+            toolStepContent,
+            contentIndex,
+            explicitToolCallId
+          );
+          if (chunkIndex != null) {
+            toolStepContent.chunkIndices.set(chunkIndex, contentIndex);
+            toolStepContent.unclaimedIndices.delete(contentIndex);
+            toolStepContent.unboundIndices.delete(contentIndex);
+          }
+          const toolCallId =
+            explicitToolCallId ??
+            toolStepContent.callIdsByIndex.get(contentIndex);
 
           const contentPart: t.MessageContentComplex = {
             type: ContentTypes.TOOL_CALL,
@@ -2153,8 +2390,10 @@ export function createContentAggregator(): t.ContentAggregatorResult {
             },
           };
 
-          updateContent(runStep.index, contentPart);
+          setContentMeta(contentIndex, runStep);
+          updateContent(contentIndex, contentPart);
         });
+        toolStepContentMap.set(runStepDelta.id, toolStepContent);
       }
     } else if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
       const { result } = data as unknown as {
@@ -2166,19 +2405,44 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       const { id: stepId } = result;
 
       const runStep = stepMap.get(stepId);
-      if (!runStep) {
-        console.warn('No run step or runId found for completed step event');
-        return;
-      }
 
       if (result.type === ContentTypes.SUMMARY && 'summary' in result) {
+        if (!runStep) {
+          console.warn('No run step or runId found for completed step event');
+          return;
+        }
         contentParts[runStep.index] = result.summary as t.MessageContentComplex;
+        applyContentMetadata(runStep.index);
       } else if ('tool_call' in result) {
+        let contentIndex = getToolCallContentIndex(result.tool_call.id);
+        if (contentIndex == null && runStep != null) {
+          const toolStepContent = toolStepContentMap.get(runStep.id);
+          if (toolStepContent?.indices.size === 1) {
+            contentIndex = toolStepContent.indices.values().next().value;
+          } else if (toolStepContent == null) {
+            const declaredToolCalls =
+              runStep.stepDetails.type === StepTypes.TOOL_CALLS
+                ? runStep.stepDetails.tool_calls
+                : undefined;
+            if ((declaredToolCalls?.length ?? 0) <= 1) {
+              contentIndex = runStep.index;
+            }
+          }
+        }
+        if (contentIndex == null) {
+          console.warn(
+            'No run step or tool call found for completed step event'
+          );
+          return;
+        }
+        if (runStep != null) {
+          setContentMeta(contentIndex, runStep);
+        }
         const contentPart: t.MessageContentComplex = {
           type: ContentTypes.TOOL_CALL,
           tool_call: (result as t.ToolEndEvent).tool_call,
         };
-        updateContent(runStep.index, contentPart, true);
+        updateContent(contentIndex, contentPart, true);
       }
     }
   };

package/src/summarization/__tests__/aggregator.test.ts

@@ -125,6 +125,89 @@ describe('createContentAggregator – SUMMARY accumulation', () => {
     expect(part.model).toBe('claude-sonnet-4-5');
   });
 
+  it('preserves agent and parallel-group metadata on summary completion', () => {
+    const { aggregateContent, contentParts } = createContentAggregator();
+
+    const runStep: t.RunStep = {
+      stepIndex: 0,
+      id: 'step_sum_3',
+      type: StepTypes.MESSAGE_CREATION,
+      index: 0,
+      agentId: 'researcher',
+      groupId: 7,
+      stepDetails: {
+        type: StepTypes.MESSAGE_CREATION,
+        message_creation: { message_id: 'step_sum_3' },
+      },
+      summary: {
+        type: ContentTypes.SUMMARY,
+        content: [],
+        tokenCount: 0,
+        provider: 'openai',
+      },
+      usage: null,
+    };
+
+    aggregateContent({
+      event: GraphEvents.ON_RUN_STEP,
+      data: runStep,
+    });
+
+    aggregateContent({
+      event: GraphEvents.ON_RUN_STEP_COMPLETED,
+      data: {
+        result: {
+          id: 'step_sum_3',
+          index: 0,
+          type: ContentTypes.SUMMARY,
+          summary: {
+            type: ContentTypes.SUMMARY,
+            content: [{ type: ContentTypes.TEXT, text: 'Step summary' }],
+            tokenCount: 4,
+            provider: 'openai',
+          },
+        },
+      } as unknown as { result: t.ToolEndEvent },
+    });
+
+    expect(contentParts[0]).toEqual(
+      expect.objectContaining({
+        type: ContentTypes.SUMMARY,
+        content: [{ type: ContentTypes.TEXT, text: 'Step summary' }],
+        agentId: 'researcher',
+        groupId: 7,
+      })
+    );
+
+    aggregateContent({
+      event: GraphEvents.ON_SUMMARIZE_COMPLETE,
+      data: {
+        id: 'step_sum_3',
+        agentId: 'researcher',
+        summary: {
+          type: ContentTypes.SUMMARY,
+          content: [{ type: ContentTypes.TEXT, text: 'Final summary' }],
+          tokenCount: 5,
+          provider: 'openai',
+          boundary: {
+            messageId: 'step_sum_3',
+            contentIndex: 0,
+          },
+        },
+      } as t.SummarizeCompleteEvent,
+    });
+
+    expect(contentParts[0]).toEqual(
+      expect.objectContaining({
+        type: ContentTypes.SUMMARY,
+        content: [{ type: ContentTypes.TEXT, text: 'Final summary' }],
+        tokenCount: 5,
+        agentId: 'researcher',
+        groupId: 7,
+      })
+    );
+  });
+
   it('handles delta when no run step exists', () => {
     const { aggregateContent, contentParts } = createContentAggregator();
 

package/src/summarization/__tests__/node.test.ts

@@ -1303,3 +1303,142 @@ describe('emoji-heavy content does not break summarization', () => {
     expect(result.messages!.length).toBeGreaterThan(0);
   });
 });
+
+describe('createSummarizeNode — overflow recovery', () => {
+  /**
+   * The first recovery compacts deterministically: re-pruning under the
+   * corrected budget drives the pruner's tool-output compression. Spending a
+   * summarization call there would cost money and risk replacing message
+   * content that compression alone can shrink.
+   */
+  it('skips the model call when summarization is not yet escalated', async () => {
+    const modelFactory = jest.spyOn(providers, 'getChatModelClass');
+    const agentContext = createAgentContext();
+    const graph = mockGraph(() => {});
+    const node = createSummarizeNode({ agentContext, graph, generateStepId });
+
+    const result = await node(
+      {
+        messages: [new HumanMessage('Hello'), new HumanMessage('World')],
+        summarizationRequest: {
+          remainingContextTokens: 0,
+          agentId: 'agent_0',
+          reason: 'overflow',
+          allowSummarization: false,
+        },
+      },
+      {} as RunnableConfig
+    );
+
+    expect(modelFactory).not.toHaveBeenCalled();
+    expect(result.summarizationRequest).toBeUndefined();
+    /** State untouched, so the agent node re-prunes and retries. */
+    expect(result.messages).toBeUndefined();
+  });
+
+  it('runs the model call once the recovery escalates', async () => {
+    jest.spyOn(providers, 'getChatModelClass').mockReturnValue(
+      class {
+        constructor() {
+          return mockInvokeModel('Escalated summary');
+        }
+      } as never
+    );
+    const agentContext = createAgentContext();
+    const graph = mockGraph(() => {});
+    const node = createSummarizeNode({ agentContext, graph, generateStepId });
+
+    await node(
+      {
+        messages: [new HumanMessage('Hello'), new HumanMessage('World')],
+        summarizationRequest: {
+          remainingContextTokens: 0,
+          agentId: 'agent_0',
+          reason: 'overflow',
+          allowSummarization: true,
+        },
+      },
+      {} as RunnableConfig
+    );
+
+    expect(agentContext.getSummaryText()).toContain('Escalated summary');
+  });
+
+  /**
+   * The metadata stub describes the history instead of summarizing it, so
+   * committing it removes the head and keeps nothing of what it said. That is
+   * never an acceptable way to paper over an overflow.
+   */
+  it('keeps history when the escalated summarizer falls back to a stub', async () => {
+    jest.spyOn(providers, 'getChatModelClass').mockReturnValue(
+      class {
+        constructor() {
+          return {
+            invoke: (): never => {
+              throw new Error(
+                '400 prompt is too long: 900 tokens > 500 maximum'
+              );
+            },
+            stream: (): never => {
+              throw new Error(
+                '400 prompt is too long: 900 tokens > 500 maximum'
+              );
+            },
+          };
+        }
+      } as never
+    );
+    const agentContext = createAgentContext();
+    const graph = mockGraph(() => {});
+    const node = createSummarizeNode({ agentContext, graph, generateStepId });
+
+    const result = await node(
+      {
+        messages: [new HumanMessage('Hello'), new HumanMessage('World')],
+        summarizationRequest: {
+          remainingContextTokens: 0,
+          agentId: 'agent_0',
+          reason: 'overflow',
+          allowSummarization: true,
+        },
+      },
+      {} as RunnableConfig
+    );
+
+    expect(agentContext.hasSummary()).toBe(false);
+    expect(result.messages).toBeUndefined();
+  });
+
+  it('still commits a stub for a configured trigger, preserving prior behavior', async () => {
+    jest.spyOn(providers, 'getChatModelClass').mockReturnValue(
+      class {
+        constructor() {
+          return {
+            invoke: (): never => {
+              throw new Error('upstream unavailable');
+            },
+            stream: (): never => {
+              throw new Error('upstream unavailable');
+            },
+          };
+        }
+      } as never
+    );
+    const agentContext = createAgentContext();
+    const graph = mockGraph(() => {});
+    const node = createSummarizeNode({ agentContext, graph, generateStepId });
+
+    await node(
+      {
+        messages: [new HumanMessage('Hello'), new HumanMessage('World')],
+        summarizationRequest: {
+          remainingContextTokens: 0,
+          agentId: 'agent_0',
+        },
+      },
+      {} as RunnableConfig
+    );
+
+    expect(agentContext.hasSummary()).toBe(true);
+  });
+});