@librechat/agents 3.9.7 → 3.9.8

package/dist/esm/utils/events.mjs

@@ -10,9 +10,14 @@ async function safeDispatchCustomEvent(event, payload, config) {
 			payload = {
 				...request,
 				resolve: (results) => {
-					traceHostToolResults(request, results, config).then(() => request.resolve(results), () => {
+					const receivedAt = Date.now();
+					const stamped = results.map((result) => ({
+						...result,
+						received_at: receivedAt
+					}));
+					traceHostToolResults(request, results, config).then(() => request.resolve(stamped), () => {
 						console.warn("Failed to record host tool execution metadata");
-						request.resolve(results);
+						request.resolve(stamped);
 					});
 				}
 			};
@@ -25,6 +30,18 @@ async function safeDispatchCustomEvent(event, payload, config) {
 		return false;
 	}
 }
+function createToolCallsDispatchedEvent(config, calls) {
+	const runId = config.configurable?.run_id;
+	return {
+		dispatched_at: Date.now(),
+		...typeof runId === "string" ? { runId } : {},
+		toolCalls: calls.map(({ id, name, stepId }) => ({
+			id,
+			name,
+			stepId
+		}))
+	};
+}
 function emitAgentLog(config, level, scope, message, data, meta, options) {
 	if (!config) return;
 	if (level === "debug" && !(options?.force ?? false) && process.env.AGENT_DEBUG_LOGGING !== "true") return;
@@ -37,6 +54,6 @@ function emitAgentLog(config, level, scope, message, data, meta, options) {
 	}, config);
 }
 //#endregion
-export { emitAgentLog, safeDispatchCustomEvent };
+export { createToolCallsDispatchedEvent, emitAgentLog, safeDispatchCustomEvent };
 
 //# sourceMappingURL=events.mjs.map

package/dist/esm/utils/events.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.mjs","names":[],"sources":["../../../src/utils/events.ts"],"mappings":";;;;;AAaA,eAAsB,wBACpB,OACA,SACA,QACyB;CACzB,IAAI;EACF,IAAI,UAAA,mBAAuC;GACzC,MAAM,UAAU;GAChB,UAAU;IACR,GAAG;IACH,UACE,YACS;KACT,qBAA0B,SAAS,SAAS,MAAM,CAAC,CAAC,WAC5C,QAAQ,QAAQ,OAAO,SACvB;MACJ,QAAQ,KAAK,+CAA+C;MAC5D,QAAQ,QAAQ,OAAO;KACzB,CACF;IACF;GACF;EACF;EACA,MAAM,oBAAoB,OAAO,SAAS,MAAM;EAChD,OAAO;CACT,SAAS,GAAG;EAEV,IACE,aAAa,SACb,EAAE,QAAQ,SAAS,2BAA2B,KAC9C,EAAE,QAAQ,SAAS,sBAAsB,GAKzC,OAAO;EAGT,QAAQ,MAAM,mCAAmC,CAAC;EAClD,OAAO;CACT;AACF;AAQA,SAAgB,aACd,QACA,OACA,OACA,SACA,MACA,MACA,SACM;CACN,IAAI,CAAC,QAAQ;CACb,IACE,UAAU,WACV,EAAE,SAAS,SAAS,UACpB,QAAQ,IAAI,wBAAwB,QAEpC;CACF,wBAAK,gBAEH;EAAE;EAAO;EAAO;EAAS;EAAM,GAAG;CAAK,GACvC,MACF;AACF"}
+{"version":3,"file":"events.mjs","names":[],"sources":["../../../src/utils/events.ts"],"mappings":";;;;;AAcA,eAAsB,wBACpB,OACA,SACA,QACyB;CACzB,IAAI;EACF,IAAI,UAAA,mBAAuC;GACzC,MAAM,UAAU;GAChB,UAAU;IACR,GAAG;IACH,UACE,YACS;KACT,MAAM,aAAa,KAAK,IAAI;KAC5B,MAAM,UAAU,QAAQ,KAAK,YAAY;MAAE,GAAG;MAAQ,aAAa;KAAW,EAAE;KAChF,qBAA0B,SAAS,SAAS,MAAM,CAAC,CAAC,WAC5C,QAAQ,QAAQ,OAAO,SACvB;MACJ,QAAQ,KAAK,+CAA+C;MAC5D,QAAQ,QAAQ,OAAO;KACzB,CACF;IACF;GACF;EACF;EACA,MAAM,oBAAoB,OAAO,SAAS,MAAM;EAChD,OAAO;CACT,SAAS,GAAG;EAEV,IACE,aAAa,SACb,EAAE,QAAQ,SAAS,2BAA2B,KAC9C,EAAE,QAAQ,SAAS,sBAAsB,GAKzC,OAAO;EAGT,QAAQ,MAAM,mCAAmC,CAAC;EAClD,OAAO;CACT;AACF;AAGA,SAAgB,+BACd,QACA,OAI0B;CAC1B,MAAM,QAAQ,OAAO,cAAc;CACnC,OAAO;EACL,eAAe,KAAK,IAAI;EACxB,GAAI,OAAO,UAAU,WAAW,EAAE,MAAM,IAAI,CAAC;EAC7C,WAAW,MAAM,KAAK,EAAE,IAAI,MAAM,cAAc;GAAE;GAAI;GAAM;EAAO,EAAE;CACvE;AACF;AAQA,SAAgB,aACd,QACA,OACA,OACA,SACA,MACA,MACA,SACM;CACN,IAAI,CAAC,QAAQ;CACb,IACE,UAAU,WACV,EAAE,SAAS,SAAS,UACpB,QAAQ,IAAI,wBAAwB,QAEpC;CACF,wBAAK,gBAEH;EAAE;EAAO;EAAO;EAAS;EAAM,GAAG;CAAK,GACvC,MACF;AACF"}

package/dist/types/common/enum.d.ts

@@ -23,6 +23,8 @@ export declare enum GraphEvents {
     ON_MESSAGE_DELTA = "on_message_delta",
     /** [Custom] Reasoning Delta events for messages */
     ON_REASONING_DELTA = "on_reasoning_delta",
+    /** [Custom] Per-call handoff boundary between streamed tool preparation and execution */
+    ON_TOOL_CALLS_DISPATCHED = "on_tool_calls_dispatched",
     /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
     ON_TOOL_EXECUTE = "on_tool_execute",
     /** [Custom] Emitted when the summarize node begins generating a summary */

package/dist/types/graphs/Graph.d.ts

@@ -38,7 +38,7 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     abstract getStepIdByKey(stepKey: string, index?: number): string;
     abstract getRunStep(stepId: string): t.RunStep | undefined;
     abstract dispatchRunStep(stepKey: string, stepDetails: t.StepDetails, metadata?: Record<string, unknown>): Promise<string>;
-    abstract dispatchRunStepDelta(id: string, delta: t.ToolCallDelta, metadata?: Record<string, unknown>): Promise<void>;
+    abstract dispatchRunStepDelta(id: string, delta: t.ToolCallDelta, metadata?: Record<string, unknown>, observedAt?: number): Promise<void>;
     abstract dispatchMessageDelta(id: string, delta: t.MessageDelta, metadata?: Record<string, unknown>): Promise<void>;
     abstract dispatchReasoningDelta(stepId: string, delta: t.ReasoningDelta, metadata?: Record<string, unknown>): Promise<void>;
     abstract createCallModel(agentId?: string, currentModel?: t.ChatModel): (state: t.AgentSubgraphState, config?: RunnableConfig) => Promise<Partial<t.AgentSubgraphState>>;
@@ -761,7 +761,7 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * Kept for backward compatibility
      */
     handleToolCallError(data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<boolean>;
-    dispatchRunStepDelta(id: string, delta: t.ToolCallDelta, metadata?: Record<string, unknown>): Promise<void>;
+    dispatchRunStepDelta(id: string, delta: t.ToolCallDelta, metadata?: Record<string, unknown>, observedAt?: number): Promise<void>;
     dispatchMessageDelta(id: string, delta: t.MessageDelta, metadata?: Record<string, unknown>): Promise<void>;
     dispatchReasoningDelta: (stepId: string, delta: t.ReasoningDelta, metadata?: Record<string, unknown>) => Promise<void>;
 }

package/dist/types/tools/handlers.d.ts

@@ -2,11 +2,12 @@ import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { Graph, MultiAgentGraph, StandardGraph } from '@/graphs';
 import type { AgentContext } from '@/agents/AgentContext';
 import type * as t from '@/types';
-export declare function handleToolCallChunks({ graph, stepKey, toolCallChunks, metadata, }: {
+export declare function handleToolCallChunks({ graph, stepKey, toolCallChunks, metadata, observedAt, }: {
     graph: StandardGraph | MultiAgentGraph;
     stepKey: string;
     toolCallChunks: ToolCallChunk[];
     metadata?: Record<string, unknown>;
+    observedAt?: number;
 }): Promise<void>;
 export declare const handleToolCalls: (toolCalls?: ToolCall[], metadata?: Record<string, unknown>, graph?: Graph | StandardGraph | MultiAgentGraph) => Promise<void>;
 export declare const toolResultTypes: Set<string>;

package/dist/types/types/graph.d.ts

@@ -4,7 +4,7 @@ import type { START, StateGraph, StateGraphArgs } from '@langchain/langgraph';
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { RunStep, ModelResponseEvent, ModelToolsClaimedEvent, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
+import type { RunStep, ModelResponseEvent, ModelToolsClaimedEvent, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, ToolCallsDispatchedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, CompactionSemanticIndex, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecutionConfig, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
@@ -139,7 +139,7 @@ export interface FadingTier {
 /** Latched fading tiers keyed by agent ID. */
 export type FadingTiers = Record<string, FadingTier>;
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | ModelResponseEvent | ModelToolsClaimedEvent | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
+    handle(event: string, data: StreamEventData | ModelEndData | ModelResponseEvent | ModelToolsClaimedEvent | RunStep | RunStepDeltaEvent | RunStepClosedEvent | ToolCallsDispatchedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -531,7 +531,7 @@ export type ExecutableSubagentConfig = ResolvedSubagentConfig | LazySingleAgentS
 /** Graph-aware config accepted by the executor. Graph configs stay eager. */
 export type ExecutableSubagentConfigEntry = ExecutableSubagentConfig | GraphSubagentConfig;
 /** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
-export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'run_step_closed' | 'message_delta' | 'reasoning_delta' | 'control' | 'stop' | 'error';
+export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'tool_calls_dispatched' | 'run_step_completed' | 'run_step_closed' | 'message_delta' | 'reasoning_delta' | 'control' | 'stop' | 'error';
 export interface SubagentAncestryEntry {
     readonly subagentRunId: string;
     readonly subagentType: string;

package/dist/types/types/stream.d.ts

@@ -127,6 +127,8 @@ export interface RunStepDeltaEvent {
      * The delta containing the fields that have changed on the run step.
      */
     delta: ToolCallDelta;
+    /** Epoch ms when the SDK received this tool-call fragment, before step dispatch. */
+    observed_at?: number;
 }
 /**
  * Terminal signal for a run step, emitted exactly once per step when it
@@ -218,6 +220,28 @@ export type ToolCallCompleted = {
     type: 'tool_call';
     tool_call: ProcessedToolCall;
 };
+/**
+ * A tool call has crossed from model-authored argument preparation into SDK
+ * execution. Emitted immediately before host dispatch or direct invocation;
+ * it does not claim the host has begun its own work. Paired with the tool
+ * completion `completed_at`, the stamp measures SDK handoff-to-result time,
+ * not MCP or database execution time. The earliest `observed_at` tool-call
+ * delta for a call bounds its argument preparation time; consumers correlate
+ * deltas by step/index until an ID is known. For a call without streamed
+ * fragments, the preparation start is unknown. Never infer a missing start.
+ * An eager call may dispatch before it has a step ID, and this observational
+ * event may arrive after completion: correlate by tool call ID and timestamps,
+ * not arrival order.
+ */
+export type ToolCallsDispatchedEvent = {
+    dispatched_at: number;
+    runId?: string;
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        stepId?: string;
+    }>;
+};
 export type ToolCompleteEvent = ToolCallCompleted & {
     /** The Step Id of the Tool Call */
     id: string;

package/dist/types/types/tools.d.ts

@@ -644,6 +644,8 @@ export type OutcomePatch = {
 export type ToolExecuteResult = {
     /** Matches ToolCallRequest.id */
     toolCallId: string;
+    /** SDK-stamped result receipt time; never host-supplied or inferred from handler cleanup. */
+    received_at?: number;
     /** Tool output content */
     content: string | unknown[];
     /** Optional artifact (for content_and_artifact format) */

package/dist/types/utils/events.d.ts

@@ -1,10 +1,14 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolCallsDispatchedEvent } from '@/types/stream';
+import type { ToolExecuteBatchRequest } from '@/types/tools';
 import type { AgentLogEvent } from '@/types/graph';
 /**
  * Safely dispatches a custom event and properly awaits it to avoid
  * race conditions where events are dispatched after run cleanup.
  */
 export declare function safeDispatchCustomEvent(event: string, payload: unknown, config?: RunnableConfig): Promise<boolean | void>;
+/** Builds an argument-free snapshot once per handoff, not once per result. */
+export declare function createToolCallsDispatchedEvent(config: RunnableConfig, calls: readonly Pick<ToolExecuteBatchRequest['toolCalls'][number], 'id' | 'name' | 'stepId'>[]): ToolCallsDispatchedEvent;
 /**
  * Fire-and-forget diagnostic log event.
  * Debug-level logs are gated behind AGENT_DEBUG_LOGGING=true to avoid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.9.7",
+  "version": "3.9.8",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/common/enum.ts

@@ -26,6 +26,8 @@ export enum GraphEvents {
   ON_MESSAGE_DELTA = 'on_message_delta',
   /** [Custom] Reasoning Delta events for messages */
   ON_REASONING_DELTA = 'on_reasoning_delta',
+  /** [Custom] Per-call handoff boundary between streamed tool preparation and execution */
+  ON_TOOL_CALLS_DISPATCHED = 'on_tool_calls_dispatched',
   /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
   ON_TOOL_EXECUTE = 'on_tool_execute',
   /** [Custom] Emitted when the summarize node begins generating a summary */

package/src/graphs/Graph.ts

@@ -766,7 +766,8 @@ export abstract class Graph<
   abstract dispatchRunStepDelta(
     id: string,
     delta: t.ToolCallDelta,
-    metadata?: Record<string, unknown>
+    metadata?: Record<string, unknown>,
+    observedAt?: number
   ): Promise<void>;
   abstract dispatchMessageDelta(
     id: string,
@@ -6130,7 +6131,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   async dispatchRunStepDelta(
     id: string,
     delta: t.ToolCallDelta,
-    metadata?: Record<string, unknown>
+    metadata?: Record<string, unknown>,
+    observedAt?: number
   ): Promise<void> {
     if (!this.config) {
       throw new Error('No config provided');
@@ -6140,6 +6142,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     const runStepDelta: t.RunStepDeltaEvent = {
       id,
       delta,
+      ...(observedAt != null && { observed_at: observedAt }),
     };
     const handler = this.handlerRegistry?.getHandler(
       GraphEvents.ON_RUN_STEP_DELTA

package/src/run.ts

@@ -37,13 +37,6 @@ import {
   DEFAULT_MAX_STOP_CONTINUATIONS,
   DEFAULT_RECURSION_LIMIT,
 } from '@/common';
-import {
-  ACTIVITY_PHASE_LABEL_PROMPT,
-  ACTIVITY_LABEL_PROMPT,
-  buildActivityLabelPrompt,
-  buildActivityPhaseLabelPrompt,
-  normalizeActivityPhaseLabel,
-} from '@/prompts/activityLabel';
 import {
   createLangfuseTraceMetadata,
   createLangfuseHandler,
@@ -53,6 +46,13 @@ import {
   isLangfuseCallbackHandler,
   withLangfuseAttributes,
 } from '@/langfuse';
+import {
+  ACTIVITY_PHASE_LABEL_PROMPT,
+  ACTIVITY_LABEL_PROMPT,
+  buildActivityLabelPrompt,
+  buildActivityPhaseLabelPrompt,
+  normalizeActivityPhaseLabel,
+} from '@/prompts/activityLabel';
 import {
   requireValidSubagentResumeManifest,
   SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
@@ -204,6 +204,7 @@ const CUSTOM_GRAPH_EVENTS = new Set<string>([
   GraphEvents.ON_RUN_STEP_DELTA,
   GraphEvents.ON_RUN_STEP_COMPLETED,
   GraphEvents.ON_RUN_STEP_CLOSED,
+  GraphEvents.ON_TOOL_CALLS_DISPATCHED,
   GraphEvents.ON_MESSAGE_DELTA,
   GraphEvents.ON_REASONING_DELTA,
   GraphEvents.ON_TOOL_EXECUTE,
@@ -1095,6 +1096,7 @@ export class Run<_T extends t.BaseGraphState> {
               | t.RunStep
               | t.RunStepDeltaEvent
               | t.RunStepClosedEvent
+              | t.ToolCallsDispatchedEvent
               | t.MessageDeltaEvent
               | t.ReasoningDeltaEvent
               | { result: t.ToolEndEvent },

package/src/stream.ts

@@ -55,13 +55,13 @@ import {
   calculateMaxToolResultChars,
   truncateToolResultContent,
 } from '@/utils/truncation';
+import { createToolCallsDispatchedEvent, safeDispatchCustomEvent } from '@/utils/events';
 import { resolveToolOutcome, outcomeFieldsFromResult } from '@/tools/intentArg';
-import { formatToolErrorContent } from '@/tools/toolErrorContent';
 import { snapshotValidatedModelChunk } from '@/graphs/acceptedModelResponse';
 import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
+import { formatToolErrorContent } from '@/tools/toolErrorContent';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { isReasoningContentBlock } from '@/messages/core';
-import { safeDispatchCustomEvent } from '@/utils/events';
 import { composeAbortSignals } from '@/utils/misc';
 import { isGoogleLike } from '@/utils/llm';
 import { getMessageId } from '@/messages';
@@ -871,6 +871,13 @@ function startEagerToolExecutions(args: {
       reject,
     };
 
+    if (graph.config != null) {
+      void safeDispatchCustomEvent(
+        GraphEvents.ON_TOOL_CALLS_DISPATCHED,
+        createToolCallsDispatchedEvent(graph.config, batchRequest.toolCalls),
+        graph.config
+      );
+    }
     void safeDispatchCustomEvent(
       GraphEvents.ON_TOOL_EXECUTE,
       batchRequest,
@@ -980,7 +987,7 @@ async function dispatchEagerToolCompletions(args: {
               progress: 1,
               ...(outcome != null && { outcome }),
             } as t.ProcessedToolCall,
-            completed_at: Date.now(),
+            completed_at: result.received_at ?? Date.now(),
           },
         },
         graph.config
@@ -1701,6 +1708,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
     // Callback delivery can beat the producer's iterator. Validate before
     // accounting, run steps, or eager dispatch reads raw tool descriptors.
     chunk = snapshotValidatedModelChunk(chunk as AIMessageChunk);
+    const observedAt = Date.now();
 
     /**
      * Enforced before every content-specific early return below
@@ -1923,6 +1931,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
         stepKey,
         toolCallChunks: chunk.tool_call_chunks,
         metadata,
+        observedAt,
       });
       if (canStreamEager) {
         if (runScopeInvalidated()) {

package/src/tools/ToolNode.ts

@@ -170,7 +170,7 @@ function stripHostExecutionConfig(
 }
 import { convertInjectedMessages } from '@/messages/injected';
 import { stampSyntheticProviderMessage } from '@/messages/provenance';
-import { safeDispatchCustomEvent } from '@/utils/events';
+import { createToolCallsDispatchedEvent, safeDispatchCustomEvent } from '@/utils/events';
 import { RunnableCallable, composeAbortSignals } from '@/utils';
 import {
   executeHooks,
@@ -1672,6 +1672,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     };
     this.throwIfBreakerTripped(config);
     config.signal?.throwIfAborted();
+    if (call.id != null && call.id !== '') {
+      void safeDispatchCustomEvent(
+        GraphEvents.ON_TOOL_CALLS_DISPATCHED,
+        createToolCallsDispatchedEvent(config, [
+          { id: call.id, name: call.name, stepId: this.toolCallStepIds?.get(call.id) },
+        ]),
+        config
+      );
+    }
     return tool.invoke(invokeParams, runtime);
   }
 
@@ -4334,7 +4343,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       const dispatchRequestById = new Map(
         dispatchRequests.map((request) => [request.id, request])
       );
+      const receivedAtById = new Map<string, number>();
       const onResult = (result: t.ToolExecuteResult): void => {
+        const receivedAt = Date.now();
         /** Runtime-honest widening: hosts may omit the id despite the
          * field type. */
         const resultToolCallId = result.toolCallId as string | undefined;
@@ -4349,8 +4360,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           return;
         }
         earlyCompletionDispatchedIds.add(result.toolCallId);
+        receivedAtById.set(result.toolCallId, receivedAt);
         earlyCompletionDispatches.push(
-          this.dispatchEarlyToolCompletion(result, request, config).then(
+          this.dispatchEarlyToolCompletion({ ...result, received_at: receivedAt }, request, config).then(
             (dispatched) => {
               if (!dispatched) {
                 earlyCompletionDispatchedIds.delete(result.toolCallId);
@@ -4402,6 +4414,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
                   | undefined,
               signal: config.signal,
               resolve: (results): void => {
+                const receivedAt = Date.now();
+                for (const result of results) {
+                  if (dispatchRequestById.has(result.toolCallId)) {
+                    receivedAtById.set(result.toolCallId, result.received_at ?? receivedAt);
+                  }
+                }
                 resultSettled = true;
                 settledResults = results;
                 maybeResolve();
@@ -4410,6 +4428,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               ...(canEmitEarlyCompletions && { onResult }),
             };
 
+            void safeDispatchCustomEvent(
+              GraphEvents.ON_TOOL_CALLS_DISPATCHED,
+              createToolCallsDispatchedEvent(config, dispatchRequests),
+              config
+            );
             void safeDispatchCustomEvent(
               GraphEvents.ON_TOOL_EXECUTE,
               batchRequest,
@@ -4695,7 +4718,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             request?.turn,
             resolveToolOutcome(request?.args, outcomeFieldsFromResult(result), {
               isError: result.status === 'error',
-            })
+            }),
+            receivedAtById.get(result.toolCallId) ?? result.received_at
           );
         }
 
@@ -4997,7 +5021,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     output: string,
     config: RunnableConfig,
     turn?: number,
-    outcome?: string
+    outcome?: string,
+    receivedAt?: number
   ): Promise<boolean> {
     const stepId = this.toolCallStepIds?.get(toolCallId) ?? '';
     if (!stepId) {
@@ -5024,7 +5049,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             progress: 1,
             ...(outcome != null && { outcome }),
           } as t.ProcessedToolCall,
-          completed_at: Date.now(),
+          completed_at: receivedAt ?? Date.now(),
         },
       },
       config
@@ -5064,7 +5089,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       request.turn,
       resolveToolOutcome(request.args, outcomeFieldsFromResult(result), {
         isError: result.status === 'error',
-      })
+      }),
+      result.received_at
     );
   }
 

package/src/tools/handlers.ts

@@ -26,11 +26,13 @@ export async function handleToolCallChunks({
   stepKey,
   toolCallChunks,
   metadata,
+  observedAt = Date.now(),
 }: {
   graph: StandardGraph | MultiAgentGraph;
   stepKey: string;
   toolCallChunks: ToolCallChunk[];
   metadata?: Record<string, unknown>;
+  observedAt?: number;
 }): Promise<void> {
   let prevStepId: string;
   let prevRunStep: t.RunStep | undefined;
@@ -124,7 +126,8 @@ export async function handleToolCallChunks({
       type: StepTypes.TOOL_CALLS,
       tool_calls: toolCallChunks,
     },
-    metadata
+    metadata,
+    observedAt
   );
 }
 

package/src/tools/subagent/SubagentExecutor.ts

@@ -3463,6 +3463,10 @@ export class SubagentExecutor {
           scheduleWrap(eventName, 'run_step', data, memberAgentId);
           return;
         }
+        if (eventName === GraphEvents.ON_TOOL_CALLS_DISPATCHED) {
+          scheduleWrap(eventName, 'tool_calls_dispatched', data, memberAgentId);
+          return;
+        }
         if (eventName === GraphEvents.ON_RUN_STEP_DELTA) {
           scheduleWrap(eventName, 'run_step_delta', data, memberAgentId);
           return;
@@ -3816,6 +3820,26 @@ export function sanitizeForwardedSubagentUpdateData(
   if (eventName === GraphEvents.ON_RUN_STEP_DELTA) {
     return sanitizeRunStepDeltaUpdateData(data);
   }
+  if (eventName === GraphEvents.ON_TOOL_CALLS_DISPATCHED) {
+    if (!isObjectLike(data)) return undefined;
+    const event = data as { dispatched_at?: number; toolCalls?: unknown };
+    if (!Array.isArray(event.toolCalls) || typeof event.dispatched_at !== 'number') {
+      return undefined;
+    }
+    return {
+      dispatched_at: event.dispatched_at,
+      toolCalls: (event.toolCalls as unknown[]).flatMap((call) => {
+        if (!isObjectLike(call)) return [];
+        const entry = call as Record<string, unknown>;
+        if (typeof entry.id !== 'string' || typeof entry.name !== 'string') return [];
+        return [{
+          id: entry.id,
+          name: entry.name,
+          ...(typeof entry.stepId === 'string' ? { stepId: entry.stepId } : {}),
+        }];
+      }),
+    };
+  }
   if (eventName === GraphEvents.ON_RUN_STEP_COMPLETED) {
     return sanitizeRunStepCompletedUpdateData(data);
   }

package/src/types/graph.ts

@@ -17,6 +17,7 @@ import type {
   RunStepDeltaEvent,
   RunStepResumeState,
   RunStepClosedEvent,
+  ToolCallsDispatchedEvent,
   MessageDeltaEvent,
   ReasoningDeltaEvent,
 } from '@/types/stream';
@@ -209,6 +210,7 @@ export interface EventHandler {
       | RunStep
       | RunStepDeltaEvent
       | RunStepClosedEvent
+      | ToolCallsDispatchedEvent
       | MessageDeltaEvent
       | ReasoningDeltaEvent
       | SummarizeStartEvent
@@ -694,6 +696,7 @@ export type SubagentUpdatePhase =
   | 'start'
   | 'run_step'
   | 'run_step_delta'
+  | 'tool_calls_dispatched'
   | 'run_step_completed'
   | 'run_step_closed'
   | 'message_delta'

package/src/types/stream.ts

@@ -158,6 +158,8 @@ export interface RunStepDeltaEvent {
    * The delta containing the fields that have changed on the run step.
    */
   delta: ToolCallDelta;
+  /** Epoch ms when the SDK received this tool-call fragment, before step dispatch. */
+  observed_at?: number;
 }
 
 /**
@@ -264,6 +266,25 @@ export type ToolCallCompleted = {
   tool_call: ProcessedToolCall;
 };
 
+/**
+ * A tool call has crossed from model-authored argument preparation into SDK
+ * execution. Emitted immediately before host dispatch or direct invocation;
+ * it does not claim the host has begun its own work. Paired with the tool
+ * completion `completed_at`, the stamp measures SDK handoff-to-result time,
+ * not MCP or database execution time. The earliest `observed_at` tool-call
+ * delta for a call bounds its argument preparation time; consumers correlate
+ * deltas by step/index until an ID is known. For a call without streamed
+ * fragments, the preparation start is unknown. Never infer a missing start.
+ * An eager call may dispatch before it has a step ID, and this observational
+ * event may arrive after completion: correlate by tool call ID and timestamps,
+ * not arrival order.
+ */
+export type ToolCallsDispatchedEvent = {
+  dispatched_at: number;
+  runId?: string;
+  toolCalls: Array<{ id: string; name: string; stepId?: string }>;
+};
+
 export type ToolCompleteEvent = ToolCallCompleted & {
   /** The Step Id of the Tool Call */
   id: string;

package/src/types/tools.ts

@@ -700,6 +700,8 @@ export type OutcomePatch = {
 export type ToolExecuteResult = {
   /** Matches ToolCallRequest.id */
   toolCallId: string;
+  /** SDK-stamped result receipt time; never host-supplied or inferred from handler cleanup. */
+  received_at?: number;
   /** Tool output content */
   content: string | unknown[];
   /** Optional artifact (for content_and_artifact format) */

package/src/utils/events.ts

@@ -2,6 +2,7 @@
 // src/utils/events.ts
 import { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolCallsDispatchedEvent } from '@/types/stream';
 import type { ToolExecuteBatchRequest } from '@/types/tools';
 import type { AgentLogEvent } from '@/types/graph';
 import { traceHostToolResults } from '@/langfuse';
@@ -24,11 +25,13 @@ export async function safeDispatchCustomEvent(
         resolve: (
           results: Parameters<ToolExecuteBatchRequest['resolve']>[0]
         ): void => {
+          const receivedAt = Date.now();
+          const stamped = results.map((result) => ({ ...result, received_at: receivedAt }));
           void traceHostToolResults(request, results, config).then(
-            () => request.resolve(results),
+            () => request.resolve(stamped),
             () => {
               console.warn('Failed to record host tool execution metadata');
-              request.resolve(results);
+              request.resolve(stamped);
             }
           );
         },
@@ -54,6 +57,22 @@ export async function safeDispatchCustomEvent(
   }
 }
 
+/** Builds an argument-free snapshot once per handoff, not once per result. */
+export function createToolCallsDispatchedEvent(
+  config: RunnableConfig,
+  calls: readonly Pick<
+    ToolExecuteBatchRequest['toolCalls'][number],
+    'id' | 'name' | 'stepId'
+  >[]
+): ToolCallsDispatchedEvent {
+  const runId = config.configurable?.run_id;
+  return {
+    dispatched_at: Date.now(),
+    ...(typeof runId === 'string' ? { runId } : {}),
+    toolCalls: calls.map(({ id, name, stepId }) => ({ id, name, stepId })),
+  };
+}
+
 /**
  * Fire-and-forget diagnostic log event.
  * Debug-level logs are gated behind AGENT_DEBUG_LOGGING=true to avoid