@librechat/agents 3.1.88 → 3.1.89

package/src/graphs/Graph.ts

@@ -145,6 +145,14 @@ export abstract class Graph<
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
+  /**
+   * True when event-driven tool execution can be routed through callbacks even
+   * though this graph intentionally does not own the full handler registry.
+   * Self-spawned subagent graphs use this shape: their callback forwarder sends
+   * `ON_TOOL_EXECUTE` to the parent's handler, while child run-step events stay
+   * wrapped as `ON_SUBAGENT_UPDATE` instead of leaking as parent events.
+   */
+  eventToolExecutionAvailable: boolean = false;
   hookRegistry: HookRegistry | undefined;
   /**
    * Run-scoped HITL configuration. When `humanInTheLoop?.enabled` is
@@ -167,10 +175,8 @@ export abstract class Graph<
   eagerEventToolExecution: t.EagerEventToolExecutionConfig | undefined;
   eagerEventToolExecutions: Map<string, t.EagerEventToolExecution> = new Map();
   eagerEventToolUsageCount: Map<string, number> = new Map();
-  private eagerEventToolUsageCountsByAgentId: Map<
-    string,
-    Map<string, number>
-  > = new Map();
+  private eagerEventToolUsageCountsByAgentId: Map<string, Map<string, number>> =
+    new Map();
   eagerEventToolCallChunks: Map<string, t.EagerEventToolCallChunkState> =
     new Map();
   /**
@@ -1554,7 +1560,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           parentAgentId: agentContext.agentId,
           tokenCounter: agentContext.tokenCounter,
           maxDepth: effectiveSubagentDepth,
-          createChildGraph: (input): StandardGraph => new StandardGraph(input),
+          createChildGraph: (input): StandardGraph => {
+            const childGraph = new StandardGraph(input);
+            childGraph.toolOutputReferences = this.toolOutputReferences;
+            childGraph.eagerEventToolExecution = this.eagerEventToolExecution;
+            childGraph.toolExecution = this.toolExecution;
+            childGraph.eventToolExecutionAvailable =
+              this.handlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) !=
+              null;
+            return childGraph;
+          },
         });
 
         const subagentTool = tool(async (rawInput, config) => {

package/src/specs/subagent.test.ts

@@ -1,4 +1,4 @@
-import { HumanMessage } from '@langchain/core/messages';
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
 import { FakeListChatModel } from '@langchain/core/utils/testing';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
@@ -220,6 +220,92 @@ describe('Subagent Integration', () => {
     expect(subagentTool).toBeDefined();
   });
 
+  it('inherits eager event-tool settings into self-spawn child graphs', async () => {
+    const originalCreateWorkflow = StandardGraph.prototype.createWorkflow;
+    const observedChildGraphs: Array<{
+      eagerEventToolExecution: StandardGraph['eagerEventToolExecution'];
+      toolOutputReferences: StandardGraph['toolOutputReferences'];
+      eventToolExecutionAvailable: boolean;
+    }> = [];
+    const createWorkflowSpy = jest
+      .spyOn(StandardGraph.prototype, 'createWorkflow')
+      .mockImplementation(function (this: StandardGraph) {
+        if (this.runId?.includes('_sub_') === true) {
+          observedChildGraphs.push({
+            eagerEventToolExecution: this.eagerEventToolExecution,
+            toolOutputReferences: this.toolOutputReferences,
+            eventToolExecutionAvailable: this.eventToolExecutionAvailable,
+          });
+          return {
+            invoke: jest.fn(async () => ({
+              messages: [new AIMessage('child done')],
+            })),
+          } as unknown as ReturnType<StandardGraph['createWorkflow']>;
+        }
+        return originalCreateWorkflow.call(this);
+      });
+
+    const agentWithSelfSpawn: t.AgentInputs = {
+      agentId: 'self-parent',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Agent with self-spawn for context isolation.',
+      maxContextTokens: 8000,
+      toolDefinitions: [{ name: 'mcp_lookup' }],
+      subagentConfigs: [
+        {
+          type: 'isolated',
+          name: 'Isolated Worker',
+          description: 'Runs a task with isolated context',
+          self: true,
+        },
+      ],
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `self-spawn-eager-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithSelfSpawn],
+      },
+      customHandlers: {
+        [GraphEvents.ON_TOOL_EXECUTE]: {
+          handle: async () => undefined,
+        },
+      },
+      eagerEventToolExecution: { enabled: true },
+      toolOutputReferences: { enabled: true },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get(
+      'self-parent'
+    );
+    const subagentTool = (context?.graphTools as t.GenericTool[]).find(
+      (tool) => 'name' in tool && tool.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeDefined();
+
+    await subagentTool!.invoke(
+      {
+        description: 'Use your MCP tool.',
+        subagent_type: 'isolated',
+      },
+      callerConfig
+    );
+
+    expect(observedChildGraphs).toEqual([
+      {
+        eagerEventToolExecution: { enabled: true },
+        toolOutputReferences: { enabled: true },
+        eventToolExecutionAvailable: true,
+      },
+    ]);
+
+    createWorkflowSpy.mockRestore();
+  });
+
   it('should not create subagent tool when maxSubagentDepth is 0', async () => {
     const agentWithZeroDepth: t.AgentInputs = {
       ...createParentAgent(),

package/src/stream.ts

@@ -27,11 +27,16 @@ import {
   coerceRecordArgs,
   normalizeError,
 } from '@/tools/eagerEventExecution';
+import {
+  calculateMaxToolResultChars,
+  truncateToolResultContent,
+} from '@/utils/truncation';
 import {
   getStreamedToolCallSeal,
   getStreamedToolCallAdapter,
   type StreamedToolCallSeal,
 } from '@/tools/streamedToolCallSeals';
+import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
 
 const LOCAL_CODING_BUNDLE_NAME_SET: ReadonlySet<string> = new Set(
   LOCAL_CODING_BUNDLE_NAMES
@@ -98,11 +103,22 @@ function getNonEmptyValue(possibleValues: string[]): string | undefined {
 }
 
 function isBatchSensitiveToolExecution(graph: StandardGraph): boolean {
-  return (
-    graph.hookRegistry != null ||
-    graph.humanInTheLoop?.enabled === true ||
-    graph.toolOutputReferences?.enabled === true
-  );
+  return graph.hookRegistry != null || graph.humanInTheLoop?.enabled === true;
+}
+
+function hasToolOutputReference(value: unknown): boolean {
+  if (typeof value === 'string') {
+    return TOOL_OUTPUT_REF_PATTERN.test(value);
+  }
+  if (Array.isArray(value)) {
+    return value.some((item) => hasToolOutputReference(item));
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.values(value as Record<string, unknown>).some((item) =>
+      hasToolOutputReference(item)
+    );
+  }
+  return false;
 }
 
 function isDirectGraphTool(
@@ -194,7 +210,10 @@ function isEagerToolExecutionEnabledForBatch(args: {
   ) {
     return false;
   }
-  if (graph.handlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) == null) {
+  if (
+    graph.handlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) == null &&
+    graph.eventToolExecutionAvailable !== true
+  ) {
     return false;
   }
   return true;
@@ -257,13 +276,49 @@ function hasPotentialDirectToolInStreamContext(args: {
   if ((agentContext?.graphTools?.length ?? 0) > 0) {
     return true;
   }
+  return false;
+}
+
+function hasDirectToolCallChunkInBatch(args: {
+  graph: StandardGraph;
+  agentContext?: AgentContext;
+  toolCallChunks?: ToolCallChunk[];
+}): boolean {
+  const { graph, agentContext, toolCallChunks } = args;
   return (
-    agentContext?.toolDefinitions?.some((toolDefinition) =>
-      toolDefinition.name.startsWith(Constants.LC_TRANSFER_TO_)
+    toolCallChunks?.some(
+      (toolCallChunk) =>
+        toolCallChunk.name != null &&
+        toolCallChunk.name !== '' &&
+        (isDirectGraphTool(toolCallChunk.name, agentContext) ||
+          isDirectLocalTool(toolCallChunk.name, graph))
     ) === true
   );
 }
 
+function hasDirectToolCallChunkStateInStep(args: {
+  graph: StandardGraph;
+  agentContext?: AgentContext;
+  stepKey: string;
+}): boolean {
+  const { graph, agentContext, stepKey } = args;
+  const prefix = `${stepKey}\u0000`;
+  for (const [key, state] of graph.eagerEventToolCallChunks) {
+    if (!key.startsWith(prefix)) {
+      continue;
+    }
+    const name = state.name;
+    if (
+      name != null &&
+      name !== '' &&
+      (isDirectGraphTool(name, agentContext) || isDirectLocalTool(name, graph))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 type EagerToolExecutionEntry = {
   id: string;
   toolName: string;
@@ -298,6 +353,12 @@ function createEagerToolExecutionPlan(args: {
   if (hasDirectToolCallInBatch({ graph, agentContext, toolCalls })) {
     return undefined;
   }
+  if (
+    graph.toolOutputReferences?.enabled === true &&
+    toolCalls.some((toolCall) => hasToolOutputReference(toolCall.args))
+  ) {
+    return undefined;
+  }
 
   const candidateToolCalls = skipExisting
     ? toolCalls.filter((toolCall) => {
@@ -369,6 +430,7 @@ function startEagerToolExecutions(args: {
     return;
   }
 
+  const records: t.EagerEventToolExecution[] = [];
   const promise: Promise<t.EagerEventToolExecutionOutcome> = new Promise<
     t.ToolExecuteResult[]
   >((resolve, reject) => {
@@ -407,20 +469,104 @@ function startEagerToolExecutions(args: {
       })
       .catch(reject);
   }).then(
-    (results): t.EagerEventToolExecutionOutcome => ({ results }),
+    async (results): Promise<t.EagerEventToolExecutionOutcome> => {
+      await dispatchEagerToolCompletions({
+        graph,
+        agentContext,
+        records,
+        results,
+      });
+      return { results };
+    },
     (error): t.EagerEventToolExecutionOutcome => ({
       error: normalizeError(error),
     })
   );
 
   for (const entry of entries) {
-    graph.eagerEventToolExecutions.set(entry.id, {
+    const record: t.EagerEventToolExecution = {
       toolCallId: entry.id,
       toolName: entry.toolName,
       args: entry.coercedArgs,
       request: entry.request,
       promise,
-    });
+    };
+    records.push(record);
+    graph.eagerEventToolExecutions.set(entry.id, record);
+  }
+}
+
+async function dispatchEagerToolCompletions(args: {
+  graph: StandardGraph;
+  agentContext?: AgentContext;
+  records: t.EagerEventToolExecution[];
+  results: t.ToolExecuteResult[];
+}): Promise<void> {
+  const { graph, agentContext, records, results } = args;
+  const recordById = new Map(
+    records.map((record) => [record.toolCallId, record])
+  );
+  const maxToolResultChars =
+    agentContext?.maxToolResultChars ??
+    calculateMaxToolResultChars(agentContext?.maxContextTokens);
+
+  for (const result of results) {
+    const record = recordById.get(result.toolCallId);
+    if (record == null) {
+      continue;
+    }
+    if (graph.eagerEventToolExecutions.get(result.toolCallId) !== record) {
+      continue;
+    }
+    const stepId =
+      record.request.stepId ??
+      graph.toolCallStepIds.get(result.toolCallId) ??
+      '';
+    if (stepId === '') {
+      continue;
+    }
+    const output =
+      result.status === 'error'
+        ? `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`
+        : truncateToolResultContent(
+          typeof result.content === 'string'
+            ? result.content
+            : JSON.stringify(result.content),
+          maxToolResultChars
+        );
+
+    try {
+      const dispatched = await safeDispatchCustomEvent(
+        GraphEvents.ON_RUN_STEP_COMPLETED,
+        {
+          result: {
+            id: stepId,
+            index: record.request.turn ?? 0,
+            type: 'tool_call' as const,
+            eager: true,
+            tool_call: {
+              args: JSON.stringify(record.request.args),
+              name: record.toolName,
+              id: result.toolCallId,
+              output,
+              progress: 1,
+            } as t.ProcessedToolCall,
+          },
+        },
+        graph.config
+      );
+      if (dispatched === false) {
+        continue;
+      }
+      record.completionDispatched = true;
+    } catch (error) {
+      // Let ToolNode dispatch the completion through the normal path later.
+
+      console.warn(
+        `[stream] eager completion dispatch failed for toolCallId=${result.toolCallId}:`,
+        error instanceof Error ? error.message : error
+      );
+    }
   }
 }
 
@@ -699,6 +845,8 @@ function startReadyStreamedEagerToolExecutions(args: {
   } = args;
   if (
     hasPotentialDirectToolInStreamContext({ graph, agentContext }) ||
+    hasDirectToolCallChunkInBatch({ graph, agentContext, toolCallChunks }) ||
+    hasDirectToolCallChunkStateInStep({ graph, agentContext, stepKey }) ||
     !isEagerToolExecutionEnabledForBatch({ graph, metadata, agentContext })
   ) {
     return;
@@ -1265,9 +1413,12 @@ export function createContentAggregator(): t.ContentAggregatorResult {
 
       const existingContent = contentParts[index] as
         | (Omit<t.ToolCallContent, 'tool_call'> & {
-            tool_call?: t.ToolCallPart;
+            tool_call?: t.ToolCallPart & t.PartMetadata;
           })
         | undefined;
+      if (!finalUpdate && existingContent?.tool_call?.progress === 1) {
+        return;
+      }
 
       /** When args are a valid object, they are likely already invoked */
       let args =