@librechat/agents 3.4.0 → 3.4.2

package/src/specs/subagent.test.ts

@@ -5,8 +5,8 @@ import {
   AIMessageChunk,
   HumanMessage,
 } from '@langchain/core/messages';
+import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { UsageMetadata } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
 import {
@@ -371,6 +371,8 @@ describe('Subagent Integration', () => {
       }
     );
     const parentUpdateHandler = jest.fn();
+    const rootModelEndHandler = jest.fn();
+    const nestedUsageEvents: t.SubagentUsageEvent[] = [];
     let specialistToolDefinitions: t.LCTool[] | undefined;
     let forwardedToolResults: t.ToolExecuteResult[] | undefined;
 
@@ -409,7 +411,12 @@ describe('Subagent Integration', () => {
               const invokeOptions = options as
                 | { callbacks?: unknown[] }
                 | undefined;
-              const forwarder = (invokeOptions?.callbacks ?? [])[0] as
+              const callbacks = invokeOptions?.callbacks ?? [];
+              const forwarder = callbacks.find(
+                (callback) =>
+                  typeof (callback as { handleCustomEvent?: unknown })
+                    .handleCustomEvent === 'function'
+              ) as
                 | {
                     handleCustomEvent?: (
                       eventName: string,
@@ -418,6 +425,27 @@ describe('Subagent Integration', () => {
                     ) => Promise<void> | void;
                   }
                 | undefined;
+              const usageHandler = callbacks.find(
+                (callback) =>
+                  typeof (callback as { handleLLMEnd?: unknown })
+                    .handleLLMEnd === 'function'
+              ) as
+                | {
+                    handleChatModelStart?: (
+                      llm: unknown,
+                      messages: BaseMessage[][],
+                      runId: string,
+                      parentRunId?: string,
+                      extraParams?: unknown,
+                      tags?: string[],
+                      metadata?: Record<string, unknown>
+                    ) => Promise<void> | void;
+                    handleLLMEnd?: (
+                      output: unknown,
+                      runId: string
+                    ) => Promise<void> | void;
+                  }
+                | undefined;
               if (forwarder?.handleCustomEvent != null) {
                 forwardedToolResults = await new Promise<t.ToolExecuteResult[]>(
                   (resolve, reject) => {
@@ -442,6 +470,38 @@ describe('Subagent Integration', () => {
                   'specialist-run'
                 );
               }
+              await usageHandler?.handleChatModelStart?.(
+                {},
+                [[]],
+                'specialist-model-call',
+                undefined,
+                undefined,
+                undefined,
+                {
+                  agentId: 'specialist',
+                  ls_model_name: 'gpt-4o-mini',
+                }
+              );
+              await usageHandler?.handleLLMEnd?.(
+                {
+                  generations: [
+                    [
+                      {
+                        text: 'specialist done',
+                        message: new AIMessage({
+                          content: 'specialist done',
+                          usage_metadata: {
+                            input_tokens: 5,
+                            output_tokens: 3,
+                            total_tokens: 8,
+                          },
+                        }),
+                      },
+                    ],
+                  ],
+                },
+                'specialist-model-call'
+              );
               return { messages: [new AIMessage('specialist done')] };
             }),
           } as unknown as ReturnType<StandardGraph['createWorkflow']>;
@@ -492,17 +552,22 @@ describe('Subagent Integration', () => {
     };
 
     try {
+      const rootRunId = `nested-event-tools-${Date.now()}`;
       const run = await Run.create<t.IState>({
-        runId: `nested-event-tools-${Date.now()}`,
+        runId: rootRunId,
         graphConfig: { type: 'standard', agents: [rootAgent] },
         customHandlers: {
           [GraphEvents.ON_TOOL_EXECUTE]: { handle: parentToolHandler },
+          [GraphEvents.CHAT_MODEL_END]: { handle: rootModelEndHandler },
           [GraphEvents.ON_SUBAGENT_UPDATE]: {
             handle: parentUpdateHandler,
           },
         },
         returnContent: true,
         skipCleanup: true,
+        subagentUsageSink: (event) => {
+          nestedUsageEvents.push(event);
+        },
       });
       const rootContext = (run.Graph as StandardGraph).agentContexts.get(
         'root'
@@ -530,7 +595,68 @@ describe('Subagent Integration', () => {
         ([, data]) => (data as t.SubagentUpdateEvent).subagentType
       );
       expect(forwardedSubagentTypes).toContain('router');
-      expect(forwardedSubagentTypes).not.toContain('specialist');
+      expect(forwardedSubagentTypes).toContain('specialist');
+      const specialistStepUpdates = parentUpdateHandler.mock.calls.filter(
+        ([, data]) => {
+          const event = data as t.SubagentUpdateEvent;
+          return (
+            event.subagentType === 'specialist' &&
+            (event.data as { id?: string } | undefined)?.id ===
+              'specialist-step'
+          );
+        }
+      );
+      expect(specialistStepUpdates).toHaveLength(1);
+      const routerEvent = parentUpdateHandler.mock.calls
+        .map(([, data]) => data as t.SubagentUpdateEvent)
+        .find((event) => event.subagentType === 'router');
+      const specialistEvent =
+        specialistStepUpdates[0][1] as t.SubagentUpdateEvent;
+      expect(routerEvent).toMatchObject({
+        runId: rootRunId,
+        parentRunId: rootRunId,
+        depth: 1,
+      });
+      expect(routerEvent?.ancestry?.map((entry) => entry.subagentType)).toEqual(
+        ['router']
+      );
+      expect(specialistEvent).toMatchObject({
+        runId: rootRunId,
+        parentRunId: routerEvent?.subagentRunId,
+        depth: 2,
+      });
+      expect(
+        specialistEvent.ancestry?.map((entry) => ({
+          type: entry.subagentType,
+          kind: entry.subagentKind,
+        }))
+      ).toEqual([
+        { type: 'router', kind: 'agent' },
+        { type: 'specialist', kind: 'agent' },
+      ]);
+      expect(nestedUsageEvents).toHaveLength(1);
+      expect(rootModelEndHandler).not.toHaveBeenCalled();
+      expect(nestedUsageEvents[0]).toMatchObject({
+        runId: rootRunId,
+        parentRunId: routerEvent?.subagentRunId,
+        subagentType: 'specialist',
+        subagentAgentId: 'specialist',
+        depth: 2,
+        usage: {
+          input_tokens: 5,
+          output_tokens: 3,
+          total_tokens: 8,
+        },
+      });
+      expect(
+        nestedUsageEvents[0].ancestry?.map((entry) => ({
+          type: entry.subagentType,
+          kind: entry.subagentKind,
+        }))
+      ).toEqual([
+        { type: 'router', kind: 'agent' },
+        { type: 'specialist', kind: 'agent' },
+      ]);
     } finally {
       createWorkflowSpy.mockRestore();
     }

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

@@ -1059,6 +1059,24 @@ describe('recency window — first-turn protection', () => {
       expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm2' });
     });
 
+    it('anchors a derived retained message on its persisted source id', async () => {
+      const summaryBlock = await runCompaction([
+        new HumanMessage({ content: 'turn 1 query', id: 'm1' }),
+        new AIMessage({ content: 'pre-steer reply', id: 'm2' }),
+        new HumanMessage({
+          content: 'steer',
+          id: 'reducer-uuid',
+          additional_kwargs: {
+            role: 'user',
+            source: 'steer',
+            sourceMessageId: 'm2',
+          },
+        }),
+      ]);
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm2' });
+    });
+
     /** `formatAgentMessages` reconstructs skill bodies inside its payload loop
      *  and keeps processing payload entries after, so this unstamped entry — a
      *  reducer UUID by the time compaction sees it — precedes stamped messages.
@@ -1770,13 +1788,13 @@ describe('summarize node breaker capture', () => {
     const entryBreaker = new AbortController();
     /** The trip lands while ON_SUMMARIZE_START is awaited — after the
      * entry check already passed. */
-    jest.spyOn(eventUtils, 'safeDispatchCustomEvent').mockImplementation((async (
-      ...args: unknown[]
-    ) => {
-      if (args[0] === GraphEvents.ON_SUMMARIZE_START) {
-        entryBreaker.abort(trip);
-      }
-    }) as never);
+    jest
+      .spyOn(eventUtils, 'safeDispatchCustomEvent')
+      .mockImplementation((async (...args: unknown[]) => {
+        if (args[0] === GraphEvents.ON_SUMMARIZE_START) {
+          entryBreaker.abort(trip);
+        }
+      }) as never);
     const modelClassSpy = jest
       .spyOn(providers, 'getChatModelClass')
       .mockReturnValue(
@@ -1915,13 +1933,13 @@ describe('summarize node breaker capture', () => {
     const entryBreaker = new AbortController();
     const lateBreaker = new AbortController();
     let started = false;
-    jest.spyOn(eventUtils, 'safeDispatchCustomEvent').mockImplementation((async (
-      ...args: unknown[]
-    ) => {
-      if (args[0] === GraphEvents.ON_SUMMARIZE_START) {
-        started = true;
-      }
-    }) as never);
+    jest
+      .spyOn(eventUtils, 'safeDispatchCustomEvent')
+      .mockImplementation((async (...args: unknown[]) => {
+        if (args[0] === GraphEvents.ON_SUMMARIZE_START) {
+          started = true;
+        }
+      }) as never);
 
     const capturedSignals: Array<AbortSignal | undefined> = [];
     jest.spyOn(providers, 'getChatModelClass').mockReturnValue(

package/src/summarization/node.ts

@@ -17,6 +17,11 @@ import {
   isComputerCallOutputMessage,
   serializeToolContentBounded,
 } from '@/utils/toolContent';
+import {
+  enforceStreamLimitsForWireChunk,
+  StreamLimitExceededError,
+  STREAM_LIMIT_EPOCH_KEY,
+} from '@/llm/streamLimits';
 import {
   addTailCacheControl,
   resolvePromptCacheTtl,
@@ -34,11 +39,6 @@ import {
   Providers,
 } from '@/common';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
-import {
-  enforceStreamLimitsForWireChunk,
-  StreamLimitExceededError,
-  STREAM_LIMIT_EPOCH_KEY,
-} from '@/llm/streamLimits';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { calculateMaxToolResultChars } from '@/utils/truncation';
 import { createRemoveAllMessage } from '@/messages/reducer';
@@ -418,8 +418,9 @@ function computeSummaryTokenCount(
  * in `ToolNode` and `StandardGraph`, handoff cues, reconstructed skill bodies.
  *
  * `steer` is exempt from the `source` check because a replayed steer *is*
- * stamped from its payload entry; rejecting every marked `source` once dropped
- * exactly those retained steers. Injected steers are still caught, by `injected`.
+ * correlated with its payload entry; rejecting every marked `source` once
+ * dropped exactly those retained steers. Injected steers are still caught, by
+ * `injected`.
  *
  * Known limitation: a payload entry that omits `messageId` is never stamped, so
  * the reducer's UUID is recorded and cannot resolve on the next run. There is no
@@ -443,7 +444,10 @@ function resolveSummaryCoverage(
     if (isSyntheticContext(message)) {
       continue;
     }
-    const id = message.id?.trim();
+    const sourceMessageId = message.additional_kwargs.sourceMessageId;
+    const sourceId =
+      typeof sourceMessageId === 'string' ? sourceMessageId.trim() : '';
+    const id = sourceId !== '' ? sourceId : message.id?.trim();
     if (id != null && id !== '') {
       return { retainedFromMessageId: id };
     }
@@ -1244,9 +1248,9 @@ export function createSummarizeNode({
             ? { [Constants.INVOKED_MODEL]: clientConfig.modelName }
             : {}),
           /** Entry-captured breaker epoch: the wire consumer epoch-gates
-           * old-run summary chunks exactly like model-attempt chunks —
-           * without the stamp, a straggling summary from a failed run
-           * reads as current and could abort the next run's controller. */
+             * old-run summary chunks exactly like model-attempt chunks —
+             * without the stamp, a straggling summary from a failed run
+             * reads as current and could abort the next run's controller. */
           ...(entryBreakerEpoch != null
             ? { [STREAM_LIMIT_EPOCH_KEY]: entryBreakerEpoch }
             : {}),

package/src/tools/SubagentTool.ts

@@ -5,7 +5,7 @@ import { Constants } from '@/common';
 
 export const SubagentToolName = Constants.SUBAGENT;
 
-export const SubagentToolDescription = `Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result — all intermediate tool calls, reasoning, and context stay isolated.
+export const SubagentToolDescription = `Delegate a task to a specialized subagent or bounded agent team that runs in an isolated context window. The delegated execution returns only its designated final text result — all intermediate tool calls, reasoning, and context stay isolated.
 
 WHEN TO USE:
 - The task is self-contained and can be described in a single prompt.
@@ -13,9 +13,9 @@ WHEN TO USE:
 - A specialized subagent is available for the task domain.
 
 WHAT HAPPENS:
-- A fresh agent is created with the task description as its only input.
-- The subagent runs to completion using its own tools and context.
-- Only the final text response is returned to you.
+- A fresh agent or configured agent graph is created with the task description as its only input.
+- The delegated agent or team runs to completion using isolated tools and context.
+- Only the single agent's final response or the graph's designated result-agent response is returned to you.
 
 CONSTRAINTS:
 - subagent_type must match one of the available types listed below.