Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🕘 feat: Distinguish Tool Preparation From Tool Call Time (#16455)

lia-by-librechat[bot]a7662d2d2660
diff --git a/api/server/controllers/agents/__tests__/callbacks.spec.js b/api/server/controllers/agents/__tests__/callbacks.spec.js
index 318adaf8bc..b94e7f3e7a 100644
--- a/api/server/controllers/agents/__tests__/callbacks.spec.js
+++ b/api/server/controllers/agents/__tests__/callbacks.spec.js
@@ -25,12 +25,15 @@ jest.mock('@librechat/api', () => ({
isCodeArtifactToolOutput: jest.requireActual('@librechat/api').isCodeArtifactToolOutput,
isCodeSessionToolName: jest.requireActual('@librechat/api').isCodeSessionToolName,
collectToolCallIds: jest.requireActual('@librechat/api').collectToolCallIds,
+ captureSubagentIdentity: jest.requireActual('@librechat/api').captureSubagentIdentity,
+ createToolTimingAdapter: jest.requireActual('@librechat/api').createToolTimingAdapter,
}));
jest.mock('@librechat/data-schemas', () => ({
logger: {
debug: jest.fn(),
error: jest.fn(),
+ warn: jest.fn(),
},
}));
@@ -361,6 +364,139 @@ describe('resumable event generation fencing', () => {
expect(resumedPublish.mock.calls[0][0].activityEventId).not.toBe(firstUpdate.activityEventId);
});
+ it('publishes tool preparation and handoff into event-child activity', async () => {
+ const { GraphEvents, createContentAggregator } = jest.requireActual('@librechat/agents');
+ const { getDefaultHandlers } = require('../callbacks');
+ const publish = jest.fn().mockResolvedValue(undefined);
+ const { contentParts, stepMap, aggregateContent } = createContentAggregator();
+ const handlers = getDefaultHandlers({
+ res: { write: jest.fn() },
+ aggregateContent,
+ contentParts,
+ stepMap,
+ toolEndCallback: jest.fn(),
+ collectedUsage: [],
+ streamId: 'event-thread',
+ eventChildActivity: {
+ runId: 'event-thread',
+ parentRunId: 'parent-conversation',
+ subagentRunId: 'child-1',
+ subagentType: 'researcher',
+ subagentAgentId: 'agent-1',
+ parentAgentId: 'director',
+ publish,
+ },
+ });
+ const step = {
+ id: 'step-child',
+ index: 0,
+ type: 'tool_calls',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-child', name: 'query', args: '{}' }],
+ },
+ };
+ await handlers[GraphEvents.ON_RUN_STEP].handle(GraphEvents.ON_RUN_STEP, step);
+ await handlers[GraphEvents.ON_RUN_STEP_DELTA].handle(GraphEvents.ON_RUN_STEP_DELTA, {
+ id: 'step-child',
+ observed_at: 100,
+ delta: { type: 'tool_calls', tool_calls: [{ id: 'call-child', index: 0, args: '{' }] },
+ });
+ await handlers[StepEvents.ON_TOOL_CALLS_DISPATCHED].handle(
+ StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ {
+ dispatched_at: 500,
+ toolCalls: [{ id: 'call-child', name: 'query', stepId: 'step-child' }],
+ },
+ );
+ await new Promise((resolve) => setImmediate(resolve));
+ expect(publish.mock.calls.map(([value]) => value.phase)).toEqual([
+ 'run_step',
+ 'tool_preparation',
+ 'run_step_delta',
+ 'tool_calls_dispatched',
+ ]);
+ expect(publish.mock.calls[1][0].data).toEqual({
+ id: 'step-child',
+ index: 0,
+ toolCallId: 'call-child',
+ observed_at: 100,
+ });
+ expect(publish.mock.calls[3][0].data.toolCalls[0]).not.toHaveProperty('args');
+ });
+
+ it('folds child dispatch and result into the parent-owned subagent tool part', async () => {
+ const { GraphEvents } = jest.requireActual('@librechat/agents');
+ const { getDefaultHandlers } = require('../callbacks');
+ const aggregators = new Map();
+ const handlers = getDefaultHandlers({
+ res: { write: jest.fn() },
+ aggregateContent: jest.fn(),
+ toolEndCallback: jest.fn(),
+ collectedUsage: [],
+ subagentAggregatorsByToolCallId: aggregators,
+ });
+ const base = {
+ parentToolCallId: 'parent-call',
+ parentRunId: 'parent-run',
+ subagentRunId: 'child-run',
+ subagentType: 'researcher',
+ subagentAgentId: 'child-agent',
+ runId: 'parent-run',
+ };
+ for (const event of [
+ {
+ phase: 'run_step',
+ data: {
+ id: 'child-step',
+ index: 0,
+ type: 'tool_calls',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'child-call', name: 'query', args: '{}' }],
+ },
+ },
+ },
+ {
+ phase: 'tool_preparation',
+ data: { id: 'child-step', toolCallId: 'child-call', observed_at: 100 },
+ },
+ {
+ phase: 'tool_calls_dispatched',
+ data: {
+ dispatched_at: 500,
+ toolCalls: [{ id: 'child-call', stepId: 'child-step', name: 'query' }],
+ },
+ },
+ {
+ phase: 'run_step_completed',
+ data: {
+ result: {
+ id: 'child-step',
+ index: 0,
+ type: 'tool_call',
+ completed_at: 540,
+ tool_call: { id: 'child-call', name: 'query', args: '{}', output: 'ok', progress: 1 },
+ },
+ },
+ },
+ ]) {
+ await handlers[GraphEvents.ON_SUBAGENT_UPDATE].handle(GraphEvents.ON_SUBAGENT_UPDATE, {
+ ...base,
+ ...event,
+ });
+ }
+ expect(jest.requireMock('@librechat/data-schemas').logger.warn).not.toHaveBeenCalled();
+ expect(aggregators.get('parent-call')?.contentParts[0]?.tool_call).toMatchObject({
+ id: 'child-call',
+ toolPreparationStartedAt: 100,
+ toolPreparationDurationMs: 400,
+ toolDispatchedAt: 500,
+ toolExecutionDurationMs: 40,
+ output: 'ok',
+ });
+ });
+
it('forwards the originating job epoch with deferred attachments', () => {
const { GenerationJobManager } = require('@librechat/api');
const { createAttachmentEmitter } = require('../callbacks');
@@ -1308,6 +1444,145 @@ describe('createToolEndCallback', () => {
});
});
+describe('tool dispatch timing', () => {
+ it('forwards the SDK handoff and stores preparation and result intervals independently', async () => {
+ const { GraphEvents, createContentAggregator } = jest.requireActual('@librechat/agents');
+ const { GenerationJobManager } = require('@librechat/api');
+ const { getDefaultHandlers } = require('../callbacks');
+ const { contentParts, stepMap, aggregateContent } = createContentAggregator();
+ const handlers = getDefaultHandlers({
+ res: { write: jest.fn() },
+ contentParts,
+ stepMap,
+ aggregateContent,
+ toolEndCallback: jest.fn(),
+ collectedUsage: [],
+ streamId: 'run',
+ });
+ const step = {
+ id: 'step-1',
+ index: 0,
+ type: 'tool_calls',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-1', name: 'query', args: '{}' }],
+ },
+ };
+ await handlers[GraphEvents.ON_RUN_STEP].handle(GraphEvents.ON_RUN_STEP, step);
+ await handlers[GraphEvents.ON_RUN_STEP_DELTA].handle(GraphEvents.ON_RUN_STEP_DELTA, {
+ id: 'step-1',
+ observed_at: 1_000,
+ delta: { type: 'tool_calls', tool_calls: [{ id: 'call-1', index: 0, args: '{' }] },
+ });
+ const dispatched = {
+ dispatched_at: 248_000,
+ toolCalls: [{ id: 'call-1', name: 'query', stepId: 'step-1' }],
+ };
+ await handlers[StepEvents.ON_TOOL_CALLS_DISPATCHED].handle(
+ StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ dispatched,
+ );
+ await handlers[GraphEvents.ON_RUN_STEP_COMPLETED].handle(GraphEvents.ON_RUN_STEP_COMPLETED, {
+ result: {
+ id: 'step-1',
+ completed_at: 248_340,
+ index: 0,
+ tool_call: { id: 'call-1', name: 'query', args: '{}', output: 'ok' },
+ },
+ });
+ await handlers[GraphEvents.ON_RUN_STEP_CLOSED].handle(GraphEvents.ON_RUN_STEP_CLOSED, {
+ id: 'step-1',
+ index: 0,
+ type: 'tool_calls',
+ status: 'completed',
+ created_at: 1_000,
+ closed_at: 248_340,
+ });
+ expect(GenerationJobManager.emitChunk).toHaveBeenCalledWith(
+ 'run',
+ {
+ event: StepEvents.ON_TOOL_PREPARATION,
+ data: {
+ id: 'step-1',
+ index: 0,
+ toolCallId: 'call-1',
+ observed_at: 1_000,
+ },
+ },
+ expect.anything(),
+ );
+ expect(GenerationJobManager.emitChunk).toHaveBeenCalledWith(
+ 'run',
+ { event: StepEvents.ON_TOOL_CALLS_DISPATCHED, data: dispatched },
+ expect.anything(),
+ );
+ expect(contentParts[0].tool_call).toMatchObject({
+ runStepDurationMs: 247_340,
+ runStepClosedAt: 248_340,
+ toolPreparationDurationMs: 247_000,
+ toolExecutionDurationMs: 340,
+ });
+ });
+
+ it('keeps preparation across a new handler created after HITL approval', async () => {
+ const { GraphEvents, createContentAggregator } = jest.requireActual('@librechat/agents');
+ const { getDefaultHandlers } = require('../callbacks');
+ const { contentParts, stepMap, aggregateContent } = createContentAggregator();
+ const handlers = getDefaultHandlers({
+ res: { write: jest.fn() },
+ contentParts,
+ stepMap,
+ aggregateContent,
+ toolEndCallback: jest.fn(),
+ collectedUsage: [],
+ toolTimingReplayEvents: [
+ {
+ event: StepEvents.ON_TOOL_PREPARATION,
+ data: {
+ id: 'step-1',
+ index: 0,
+ toolCallId: 'call-1',
+ observed_at: 1_000,
+ },
+ },
+ ],
+ });
+ await handlers[GraphEvents.ON_RUN_STEP].handle(GraphEvents.ON_RUN_STEP, {
+ id: 'step-1',
+ index: 0,
+ type: 'tool_calls',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-1', name: 'query', args: '{}' }],
+ },
+ });
+ await handlers[StepEvents.ON_TOOL_CALLS_DISPATCHED].handle(
+ StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ { dispatched_at: 51_000, toolCalls: [{ id: 'call-1', name: 'query', stepId: 'step-1' }] },
+ );
+ await handlers[GraphEvents.ON_RUN_STEP_COMPLETED].handle(GraphEvents.ON_RUN_STEP_COMPLETED, {
+ result: {
+ id: 'step-1',
+ index: 0,
+ completed_at: 51_200,
+ tool_call: { id: 'call-1', name: 'query', args: '{}', output: 'ok' },
+ },
+ });
+ await handlers[GraphEvents.ON_RUN_STEP_CLOSED].handle(GraphEvents.ON_RUN_STEP_CLOSED, {
+ id: 'step-1',
+ index: 0,
+ type: 'tool_calls',
+ status: 'completed',
+ created_at: 1_000,
+ closed_at: 51_200,
+ });
+ expect(contentParts[0].tool_call).toMatchObject({
+ toolPreparationDurationMs: 50_000,
+ toolExecutionDurationMs: 200,
+ });
+ });
+});
+
describe('tool input validation marker', () => {
it('marks the streamed result and persisted content part out of band', async () => {
const { GraphEvents, createContentAggregator } = jest.requireActual('@librechat/agents');
diff --git a/api/server/controllers/agents/callbacks.js b/api/server/controllers/agents/callbacks.js
index 9858b4d69e..d762976f31 100644
--- a/api/server/controllers/agents/callbacks.js
+++ b/api/server/controllers/agents/callbacks.js
@@ -34,6 +34,7 @@ const {
getToolInputValidationDetails,
captureSubagentIdentity,
collectToolCallIds,
+ createToolTimingAdapter,
} = require('@librechat/api');
const { processFileCitations } = require('~/server/services/Files/Citations');
const { processCodeOutput, runPreviewFinalize } = require('~/server/services/Files/Code/process');
@@ -342,10 +343,11 @@ function subagentPhaseToGraphEvent(event) {
* @param {{ aggregateContent: Function, contentParts?: Array, stepMap?: Map }} aggregator
* @param {SubagentUpdateEvent} event
*/
-function feedSubagentAggregator(aggregator, event) {
+function feedSubagentAggregator(aggregator, event, applyChildTiming) {
const graphEvent = subagentPhaseToGraphEvent(event);
+ if (graphEvent) aggregator.aggregateContent({ event: graphEvent, data: event.data });
+ applyChildTiming(aggregator, event);
if (!graphEvent) return;
- aggregator.aggregateContent({ event: graphEvent, data: event.data });
/** The SDK aggregator intentionally projects run-step tool calls onto its
* public content shape, so host-only routing metadata is not copied. Restore
@@ -416,6 +418,7 @@ function getDefaultHandlers({
usageEmitSink = null,
eventChildActivity = null,
resolveMcpServerName = null,
+ toolTimingReplayEvents = [],
}) {
if (!res || !aggregateContent) {
throw new Error(
@@ -425,6 +428,8 @@ function getDefaultHandlers({
const eventActivityPhases = {
[GraphEvents.ON_RUN_STEP]: 'run_step',
[GraphEvents.ON_RUN_STEP_DELTA]: 'run_step_delta',
+ [StepEvents.ON_TOOL_PREPARATION]: 'tool_preparation',
+ [StepEvents.ON_TOOL_CALLS_DISPATCHED]: 'tool_calls_dispatched',
[GraphEvents.ON_RUN_STEP_COMPLETED]: 'run_step_completed',
[GraphEvents.ON_RUN_STEP_CLOSED]: 'run_step_closed',
[GraphEvents.ON_MESSAGE_DELTA]: 'message_delta',
@@ -514,7 +519,12 @@ function getDefaultHandlers({
}
return emitForJob({ event: UsageEvents.ON_TOKEN_USAGE, data: payload });
};
+ const toolTiming = createToolTimingAdapter({
+ replayEvents: toolTimingReplayEvents,
+ emit: emitForJob,
+ });
const handlers = {
+ [StepEvents.ON_TOOL_CALLS_DISPATCHED]: toolTiming.dispatch,
[GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(
collectedUsage,
collectedThoughtSignatures,
@@ -595,6 +605,7 @@ function getDefaultHandlers({
const index = stepMap?.get(stepId)?.index;
const part = typeof index === 'number' ? contentParts[index] : undefined;
if (part?.type === ContentTypes.TOOL_CALL && part.tool_call) {
+ toolTiming.close(part.tool_call, stepId);
part.tool_call.runStepStatus = data.status;
Object.assign(part.tool_call, getRunStepCloseMetadata(data));
/**
@@ -622,6 +633,7 @@ function getDefaultHandlers({
*/
handle: async (event, data, metadata) => {
aggregateContent({ event, data });
+ await toolTiming.delta(data);
if (data?.delta.type === StepTypes.TOOL_CALLS) {
await emitForJob({ event, data });
} else if (checkIfLastAgent(metadata?.last_agent_id, metadata?.langgraph_node)) {
@@ -657,6 +669,7 @@ function getDefaultHandlers({
agentId: metadata?.agent_id,
});
}
+ toolTiming.completed(data);
aggregateContent({ event, data });
const stepId = data?.result?.id;
const runStep = stepMap?.get(stepId);
@@ -769,7 +782,7 @@ function getDefaultHandlers({
}
try {
captureSubagentIdentity(aggregator, data);
- feedSubagentAggregator(aggregator, data);
+ feedSubagentAggregator(aggregator, data, toolTiming.child);
} catch (err) {
logger.warn(
`[ON_SUBAGENT_UPDATE] Failed to aggregate phase "${data?.phase}" for tool_call ${key}: ${err?.message ?? err}`,
diff --git a/api/server/controllers/agents/resume.js b/api/server/controllers/agents/resume.js
index 4caeceb259..fe4e200798 100644
--- a/api/server/controllers/agents/resume.js
+++ b/api/server/controllers/agents/resume.js
@@ -1854,6 +1854,7 @@ const ResumeAgentController = async (req, res, next, initializeClient, addTitle)
checkpointNamespace,
foregroundRunId: mcpRequestBody.messageId,
requestBody: mcpRequestBody,
+ toolTimingReplayEvents: resumeState?.replayEvents,
});
client = result.client;
diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.js
index 94dc2e5b33..68de908eb1 100644
--- a/api/server/services/Endpoints/agents/initialize.js
+++ b/api/server/services/Endpoints/agents/initialize.js
@@ -204,6 +204,7 @@ const initializeClientWithProvider = async ({
checkpointNamespace,
foregroundRunId,
requestBody,
+ toolTimingReplayEvents,
upstreamTokenProvider,
upstreamTokenProviderResolver,
}) => {
@@ -1824,6 +1825,7 @@ const initializeClientWithProvider = async ({
usageEmitSink,
eventChildActivity,
resolveMcpServerName,
+ toolTimingReplayEvents,
});
const client = new AgentClient({
diff --git a/client/src/components/Chat/Messages/Content/Part.tsx b/client/src/components/Chat/Messages/Content/Part.tsx
index 480f81b340..775cc1efdb 100644
--- a/client/src/components/Chat/Messages/Content/Part.tsx
+++ b/client/src/components/Chat/Messages/Content/Part.tsx
@@ -466,6 +466,10 @@ const Part = memo(function Part({
toolCall.backgroundTask?.cancelled === true ? 'cancelled' : toolCall.runStepStatus
}
runStepDurationMs={toolCall.runStepDurationMs}
+ toolPreparationStartedAt={toolCall.toolPreparationStartedAt}
+ toolDispatchedAt={toolCall.toolDispatchedAt}
+ toolPreparationDurationMs={toolCall.toolPreparationDurationMs}
+ toolExecutionDurationMs={toolCall.toolExecutionDurationMs}
/>
);
})();
diff --git a/client/src/components/Chat/Messages/Content/ProgressText.tsx b/client/src/components/Chat/Messages/Content/ProgressText.tsx
index fba3dcc3cc..d4dc702a2e 100644
--- a/client/src/components/Chat/Messages/Content/ProgressText.tsx
+++ b/client/src/components/Chat/Messages/Content/ProgressText.tsx
@@ -8,6 +8,7 @@ import type { ToolCallPhase } from '~/utils/toolCallPhase';
import { cn, getRunStepDurationLabels } from '~/utils';
import CancelledIcon from './CancelledIcon';
import { useFailedReveal } from './reveal';
+import { ElapsedTimer } from '../Elapsed';
import { ROW_GLYPH_SLOT } from './rows';
import { useLocalize } from '~/hooks';
@@ -69,6 +70,9 @@ export default function ProgressText({
icon: iconProp,
subtitle,
durationMs,
+ toolPreparationDurationMs,
+ toolExecutionDurationMs,
+ phaseStartAt,
hasInput = true,
popover = false,
isExpanded = false,
@@ -89,8 +93,11 @@ export default function ProgressText({
authText?: string;
icon?: React.ReactNode;
subtitle?: string;
- /** Wall-clock duration of the run step, from `PartMetadata.runStepDurationMs`. */
+ /** Total run-step lifetime, not necessarily tool execution. */
durationMs?: number;
+ toolPreparationDurationMs?: number;
+ toolExecutionDurationMs?: number;
+ phaseStartAt?: number;
hasInput?: boolean;
popover?: boolean;
isExpanded?: boolean;
@@ -99,6 +106,15 @@ export default function ProgressText({
/** For locale-aware decimal formatting of the sub-10s duration value. */
const { i18n } = useTranslation();
const isRunning = phase === 'running';
+ /** A server-authored phase stamp is an identity, not a browser clock origin.
+ * On reconnect we can only time from local receipt, never infer cross-host skew. */
+ const phaseTimer = useRef<{ stamp?: number; receivedAt: number } | null>(null);
+ if (!isRunning || phaseStartAt == null) {
+ phaseTimer.current = null;
+ } else if (phaseTimer.current?.stamp !== phaseStartAt) {
+ phaseTimer.current = { stamp: phaseStartAt, receivedAt: Date.now() };
+ }
+ const localPhaseStart = phaseTimer.current?.receivedAt;
const rootRef = useRef<HTMLDivElement>(null);
/** A header above asked for its failures. This control is the disclosure
* every card renders, so answering here reaches a failed bash, code,
@@ -139,10 +155,41 @@ export default function ProgressText({
* failed card "how long it took" is not the fact the reader needs — that
* slot already carries the cancelled icon or the failure suffix.
*/
- const duration =
- phase === 'completed' && isReportableRunStepDuration(durationMs)
- ? getRunStepDurationLabels(durationMs, i18n.language)
- : undefined;
+ const measured = toolPreparationDurationMs != null || toolExecutionDurationMs != null;
+ /** The formatter rounds to tenths below ten seconds. Shorter than 50 ms reads as 0.0s. */
+ const showToolCallTime =
+ toolExecutionDurationMs != null &&
+ Number.isFinite(toolExecutionDurationMs) &&
+ toolExecutionDurationMs >= 50;
+ const durationParts =
+ phase !== 'completed'
+ ? []
+ : [
+ ...(isReportableRunStepDuration(toolPreparationDurationMs)
+ ? [
+ {
+ label: localize('com_ui_tool_preparation_time'),
+ duration: getRunStepDurationLabels(toolPreparationDurationMs, i18n.language),
+ },
+ ]
+ : []),
+ ...(showToolCallTime
+ ? [
+ {
+ label: localize('com_ui_tool_call_time'),
+ duration: getRunStepDurationLabels(toolExecutionDurationMs, i18n.language),
+ },
+ ]
+ : []),
+ ...(!measured && isReportableRunStepDuration(durationMs)
+ ? [
+ {
+ label: localize('com_ui_tool_total_time'),
+ duration: getRunStepDurationLabels(durationMs, i18n.language),
+ },
+ ]
+ : []),
+ ];
return (
<Wrapper popover={popover} failed={phase === 'failed'} rootRef={rootRef}>
@@ -194,22 +241,19 @@ export default function ProgressText({
{errorSuffix && (
<span className="shrink-0 font-normal text-status-error">· {errorSuffix}</span>
)}
- {duration && (
- <>
- {/* The compact form is the readable one on screen but a poor
- thing to hear ("one point four s"), so it is hidden from
- assistive technology and paired with a spoken equivalent.
- Both live inside the button, so its accessible name carries
- the duration — this is not an `aria-live` region and does not
- re-announce. */}
- <span className="shrink-0 font-normal text-text-secondary" aria-hidden="true">
- · {localize(duration.key, duration.values)}
+ {isRunning && phaseStartAt != null && localPhaseStart != null && (
+ <ElapsedTimer start={localPhaseStart} />
+ )}
+ {durationParts.map(({ label, duration }) => (
+ <span key={label} className="shrink-0 font-normal text-text-secondary">
+ <span aria-hidden="true">
+ · {label} {localize(duration.key, duration.values)}
</span>
<span className="sr-only">
- {localize(duration.announcedKey, duration.announcedValues)}
+ {label} {localize(duration.announcedKey, duration.announcedValues)}
</span>
- </>
- )}
+ </span>
+ ))}
{hasInput && (
<ChevronDown
className={cn(
diff --git a/client/src/components/Chat/Messages/Content/ToolCall.tsx b/client/src/components/Chat/Messages/Content/ToolCall.tsx
index 63b97d03ec..722276344d 100644
--- a/client/src/components/Chat/Messages/Content/ToolCall.tsx
+++ b/client/src/components/Chat/Messages/Content/ToolCall.tsx
@@ -38,6 +38,10 @@ export default function ToolCall({
onExpand,
runStepStatus,
runStepDurationMs,
+ toolPreparationStartedAt,
+ toolDispatchedAt,
+ toolPreparationDurationMs,
+ toolExecutionDurationMs,
}: {
initialProgress: number;
isLast?: boolean;
@@ -52,6 +56,10 @@ export default function ToolCall({
onExpand?: () => void;
runStepStatus?: PartMetadata['runStepStatus'];
runStepDurationMs?: PartMetadata['runStepDurationMs'];
+ toolPreparationStartedAt?: PartMetadata['toolPreparationStartedAt'];
+ toolDispatchedAt?: PartMetadata['toolDispatchedAt'];
+ toolPreparationDurationMs?: PartMetadata['toolPreparationDurationMs'];
+ toolExecutionDurationMs?: PartMetadata['toolExecutionDurationMs'];
}) {
const localize = useLocalize();
const [oauthError, setOAuthError] = useState<string | null>(null);
@@ -313,6 +321,17 @@ export default function ToolCall({
* the `tool_intents` capability); persists as the settled label —
* completion is a UI state, not a tense change. */
const intent = useToolCallIntent(_args);
+ const subject = intent ?? displayFunctionName;
+ let inProgressText =
+ intent ??
+ (displayFunctionName
+ ? localize('com_assistants_running_var', { 0: displayFunctionName })
+ : localize('com_assistants_running_action'));
+ if (toolDispatchedAt != null) {
+ inProgressText = localize('com_ui_tool_calling', { 0: subject });
+ } else if (toolPreparationStartedAt != null) {
+ inProgressText = localize('com_ui_tool_preparing', { 0: subject });
+ }
const getFinishedText = () => {
if (phase === 'cancelled') {
@@ -357,6 +376,12 @@ export default function ToolCall({
<span className="sr-only" aria-live="polite" aria-atomic="true">
{(() => {
if (phase === 'running') {
+ if (toolDispatchedAt != null) {
+ return localize('com_ui_tool_calling', { 0: displayFunctionName });
+ }
+ if (toolPreparationStartedAt != null) {
+ return localize('com_ui_tool_preparing', { 0: displayFunctionName });
+ }
return displayFunctionName
? localize('com_assistants_running_var', { 0: displayFunctionName })
: localize('com_assistants_running_action');
@@ -368,12 +393,7 @@ export default function ToolCall({
<ProgressText
phase={phase}
onClick={handleToggleInfo}
- inProgressText={
- intent ??
- (displayFunctionName
- ? localize('com_assistants_running_var', { 0: displayFunctionName })
- : localize('com_assistants_running_action'))
- }
+ inProgressText={inProgressText}
authText={
phase === 'running' && authDomain.length > 0
? localize('com_ui_requires_auth')
@@ -382,6 +402,9 @@ export default function ToolCall({
finishedText={getFinishedText()}
subtitle={subtitle}
durationMs={runStepDurationMs}
+ toolPreparationDurationMs={toolPreparationDurationMs}
+ toolExecutionDurationMs={toolExecutionDurationMs}
+ phaseStartAt={toolDispatchedAt ?? toolPreparationStartedAt}
icon={
<ToolIcon type={toolIconType} iconUrl={mcpIconUrl} isAnimating={phase === 'running'} />
}
diff --git a/client/src/components/Chat/Messages/Content/__tests__/ProgressText.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ProgressText.test.tsx
index cf6f1c0569..695aa0e759 100644
--- a/client/src/components/Chat/Messages/Content/__tests__/ProgressText.test.tsx
+++ b/client/src/components/Chat/Messages/Content/__tests__/ProgressText.test.tsx
@@ -9,6 +9,9 @@ jest.mock('~/hooks', () => ({
(key: string, values?: Record<string, string | number>): string => {
const translations: Record<string, string> = {
com_ui_duration_seconds: `${values?.[0]}s`,
+ com_ui_tool_preparation_time: 'Preparation',
+ com_ui_tool_call_time: 'Tool call',
+ com_ui_tool_total_time: 'Total elapsed',
com_ui_duration_minutes: `${values?.[0]}m ${values?.[1]}s`,
com_ui_duration_announced_seconds: `took ${values?.count} seconds`,
com_ui_duration_announced_seconds_one: `took ${values?.count} second`,
@@ -40,21 +43,58 @@ const renderProgressText = (props: Partial<React.ComponentProps<typeof ProgressT
describe('ProgressText duration', () => {
it('renders the compact duration on a settled card', () => {
renderProgressText({ durationMs: 3500 });
- expect(screen.getByText('· 3.5s')).toBeInTheDocument();
+ expect(screen.getByText('· Total elapsed 3.5s')).toBeInTheDocument();
+ });
+
+ it('shows separate preparation and tool intervals without using the total as execution time', () => {
+ renderProgressText({
+ durationMs: 248_000,
+ toolPreparationDurationMs: 242_000,
+ toolExecutionDurationMs: 5_700,
+ });
+ expect(screen.getByText('· Preparation 4m 2s')).toBeInTheDocument();
+ expect(screen.getByText('· Tool call 5.7s')).toBeInTheDocument();
+ expect(screen.queryByText(/Total elapsed/)).not.toBeInTheDocument();
+ });
+
+ it('shows a few-hundred-millisecond tool call beside minutes of preparation', () => {
+ renderProgressText({
+ durationMs: 247_340,
+ toolPreparationDurationMs: 247_000,
+ toolExecutionDurationMs: 340,
+ });
+ expect(screen.getByText('· Preparation 4m 7s')).toBeInTheDocument();
+ expect(screen.getByText('· Tool call 0.3s')).toBeInTheDocument();
+ expect(screen.queryByText(/Total elapsed/)).not.toBeInTheDocument();
+ });
+
+ it('does not show a measured call too short to format as a nonzero interval', () => {
+ renderProgressText({ toolExecutionDurationMs: 40 });
+ expect(screen.queryByText(/Tool call/)).not.toBeInTheDocument();
});
it('formats durations of a minute or more as minutes and seconds', () => {
renderProgressText({ durationMs: 65_000 });
- expect(screen.getByText('· 1m 5s')).toBeInTheDocument();
+ expect(screen.getByText('· Total elapsed 1m 5s')).toBeInTheDocument();
});
/**
* The number would be stale the moment it rendered, and the label beside it
* is still the in-progress one.
*/
+ it('starts each phase timer on the browser clock, not on a skewed server stamp', () => {
+ const clock = jest.spyOn(Date, 'now').mockReturnValue(20_000);
+ const { rerender } = renderProgressText({ phase: 'running', phaseStartAt: 1_000 });
+ expect(screen.getByTestId('stream-elapsed')).toHaveTextContent('0s');
+ clock.mockReturnValue(24_000);
+ rerender(<ProgressText {...defaults} phase="running" phaseStartAt={2_000} />);
+ expect(screen.getByTestId('stream-elapsed')).toHaveTextContent('0s');
+ clock.mockRestore();
+ });
+
it('does not render while the step is still running', () => {
renderProgressText({ phase: 'running', durationMs: 3500 });
- expect(screen.queryByText('· 3.5s')).not.toBeInTheDocument();
+ expect(screen.queryByText('· Total elapsed 3.5s')).not.toBeInTheDocument();
});
/**
@@ -67,13 +107,13 @@ describe('ProgressText duration', () => {
*/
it('does not render on a cancelled card', () => {
renderProgressText({ phase: 'cancelled', durationMs: 3500 });
- expect(screen.queryByText('· 3.5s')).not.toBeInTheDocument();
+ expect(screen.queryByText('· Total elapsed 3.5s')).not.toBeInTheDocument();
});
it('does not render on a failed card', () => {
renderProgressText({ phase: 'failed', durationMs: 3500 });
- expect(screen.queryByText('· 3.5s')).not.toBeInTheDocument();
- expect(screen.queryByText('took 3.5 seconds')).not.toBeInTheDocument();
+ expect(screen.queryByText('· Total elapsed 3.5s')).not.toBeInTheDocument();
+ expect(screen.queryByText('Total elapsed took 3.5 seconds')).not.toBeInTheDocument();
});
it('renders nothing when no duration was derivable', () => {
@@ -84,31 +124,31 @@ describe('ProgressText duration', () => {
/** Sub-threshold durations are noise; the gate lives in the shared helper. */
it('suppresses a duration too short to be worth reporting', () => {
renderProgressText({ durationMs: 300 });
- expect(screen.queryByText('· 0.3s')).not.toBeInTheDocument();
+ expect(screen.queryByText('· Total elapsed 0.3s')).not.toBeInTheDocument();
});
describe('accessibility', () => {
it('hides the compact form from assistive technology and pairs it with a spoken one', () => {
renderProgressText({ durationMs: 3500 });
- expect(screen.getByText('· 3.5s')).toHaveAttribute('aria-hidden', 'true');
- expect(screen.getByText('took 3.5 seconds')).toHaveClass('sr-only');
+ expect(screen.getByText('· Total elapsed 3.5s')).toHaveAttribute('aria-hidden', 'true');
+ expect(screen.getByText('Total elapsed took 3.5 seconds')).toHaveClass('sr-only');
});
it('announces the singular form for exactly one second', () => {
renderProgressText({ durationMs: 1000 });
- expect(screen.getByText('took 1 second')).toBeInTheDocument();
+ expect(screen.getByText('Total elapsed took 1 second')).toBeInTheDocument();
});
it('announces whole minutes for longer steps', () => {
renderProgressText({ durationMs: 150_000 });
- expect(screen.getByText('took 3 minutes')).toBeInTheDocument();
+ expect(screen.getByText('Total elapsed took 3 minutes')).toBeInTheDocument();
});
/** Both spans sit inside the button, so its accessible name carries the
* duration without an `aria-live` region re-announcing it. */
it('keeps the duration inside the button', () => {
renderProgressText({ durationMs: 3500 });
- expect(screen.getByRole('button')).toHaveTextContent('took 3.5 seconds');
+ expect(screen.getByRole('button')).toHaveTextContent('Total elapsed took 3.5 seconds');
});
});
});
@@ -233,7 +273,7 @@ describe('ProgressText fixed siblings', () => {
const box = screen.getByText('Completed foo').parentElement;
expect(box).toHaveClass('min-w-0');
expect(box).toContainElement(screen.getByText('a very long subtitle'));
- expect(screen.getByText('· 3.5s')).toHaveClass('shrink-0');
+ expect(screen.getByText('· Total elapsed 3.5s').parentElement).toHaveClass('shrink-0');
expect(container.querySelector('svg')).toHaveClass('shrink-0');
});
});
diff --git a/client/src/components/Chat/Messages/Content/__tests__/ToolCall.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ToolCall.test.tsx
index 6bca11a0cc..d2ef0c0234 100644
--- a/client/src/components/Chat/Messages/Content/__tests__/ToolCall.test.tsx
+++ b/client/src/components/Chat/Messages/Content/__tests__/ToolCall.test.tsx
@@ -15,6 +15,8 @@ jest.mock('~/hooks', () => ({
com_assistants_completed_action: `Completed action on ${values?.[0]}`,
com_assistants_running_var: `Running ${values?.[0]}`,
com_assistants_running_action: 'Running action',
+ com_ui_tool_preparing: `Preparing ${values?.[0]}`,
+ com_ui_tool_calling: `Calling ${values?.[0]}`,
com_ui_sign_in_to_domain: `Sign in to ${values?.[0]}`,
com_ui_cancelled: 'Cancelled',
com_ui_requires_auth: 'Requires authentication',
@@ -138,6 +140,26 @@ describe('ToolCall', () => {
jest.clearAllMocks();
});
+ describe('tool preparation feedback', () => {
+ it('announces preparation and then execution without calling the tool during argument streaming', () => {
+ const props = {
+ ...mockProps,
+ output: null,
+ initialProgress: 0.1,
+ isSubmitting: true,
+ toolPreparationStartedAt: 1_000,
+ };
+ const { rerender } = renderWithRecoil(<ToolCall {...props} />);
+ expect(screen.getByText('Preparing testFunction')).toBeInTheDocument();
+ rerender(
+ <RecoilRoot>
+ <ToolCall {...props} toolDispatchedAt={4_000} />
+ </RecoilRoot>,
+ );
+ expect(screen.getByText('Calling testFunction')).toBeInTheDocument();
+ });
+ });
+
describe('intent label', () => {
it('renders a streaming intent as the live label before args are complete', () => {
renderWithRecoil(
diff --git a/client/src/components/Chat/Subagents/SubagentActivity.tsx b/client/src/components/Chat/Subagents/SubagentActivity.tsx
index c9f579991c..a884c1b92a 100644
--- a/client/src/components/Chat/Subagents/SubagentActivity.tsx
+++ b/client/src/components/Chat/Subagents/SubagentActivity.tsx
@@ -250,6 +250,16 @@ const toContentPart = (item: ChildActivityItem): TMessageContentParts => {
output: item.output ?? '',
progress: item.status === 'running' ? 0.1 : 1,
...(item.status === 'running' ? {} : { runStepStatus: item.status }),
+ ...(item.toolPreparationStartedAt == null
+ ? {}
+ : { toolPreparationStartedAt: item.toolPreparationStartedAt }),
+ ...(item.toolDispatchedAt == null ? {} : { toolDispatchedAt: item.toolDispatchedAt }),
+ ...(item.toolPreparationDurationMs == null
+ ? {}
+ : { toolPreparationDurationMs: item.toolPreparationDurationMs }),
+ ...(item.toolExecutionDurationMs == null
+ ? {}
+ : { toolExecutionDurationMs: item.toolExecutionDurationMs }),
...(item.inputValidationError === true ? { inputValidationError: true } : {}),
...(item.approval == null ? {} : { approval: item.approval }),
},
diff --git a/client/src/components/Chat/Subagents/adapters.test.ts b/client/src/components/Chat/Subagents/adapters.test.ts
index e257d36cb8..3d86322767 100644
--- a/client/src/components/Chat/Subagents/adapters.test.ts
+++ b/client/src/components/Chat/Subagents/adapters.test.ts
@@ -19,6 +19,86 @@ import {
} from '~/utils/subagentContent';
describe('child activity adapters', () => {
+ it('passes child dispatch and completed durations to the generic tool card', () => {
+ const progress = {
+ subagentRunId: 'child',
+ subagentType: 'researcher',
+ status: 'tool_calls_dispatched' as const,
+ contentParts: aggregateSubagentContent([
+ {
+ runId: 'parent',
+ subagentRunId: 'child',
+ subagentType: 'researcher',
+ subagentAgentId: 'agent',
+ timestamp: '2026-09-28T00:00:00Z',
+ phase: 'run_step',
+ data: {
+ id: 'step-child',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-child', name: 'query', args: '{}' }],
+ },
+ },
+ },
+ {
+ runId: 'parent',
+ subagentRunId: 'child',
+ subagentType: 'researcher',
+ subagentAgentId: 'agent',
+ timestamp: '2026-09-28T00:00:00Z',
+ phase: 'tool_calls_dispatched',
+ data: {
+ dispatched_at: 500,
+ toolCalls: [{ id: 'call-child', stepId: 'step-child' }],
+ },
+ },
+ ]),
+ aggregatorState: initSubagentAggregatorState(),
+ tickerState: initSubagentTickerState(),
+ coverage: 'complete' as const,
+ };
+ expect(
+ adaptLivePersistedActivity({
+ title: 'researcher',
+ progress,
+ persistedContent: undefined,
+ initialProgress: 0.1,
+ isSubmitting: true,
+ }).items[0],
+ ).toMatchObject({
+ type: 'tool',
+ toolCallId: 'call-child',
+ toolDispatchedAt: 500,
+ status: 'running',
+ });
+ const persisted = adaptLivePersistedActivity({
+ title: 'researcher',
+ progress: null,
+ persistedContent: [
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'call-child',
+ name: 'query',
+ args: '{}',
+ output: 'ok',
+ progress: 1,
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 40,
+ },
+ },
+ ] as TMessageContentParts[],
+ initialProgress: 1,
+ isSubmitting: false,
+ });
+ expect(persisted.items[0]).toMatchObject({
+ type: 'tool',
+ toolCallId: 'call-child',
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 40,
+ status: 'completed',
+ });
+ });
it('prefers authoritative parent persistence over a partial live foreground trace', () => {
const activity = adaptLivePersistedActivity({
title: 'researcher',
diff --git a/client/src/components/Chat/Subagents/adapters.ts b/client/src/components/Chat/Subagents/adapters.ts
index ca23aebb8e..b5218373f2 100644
--- a/client/src/components/Chat/Subagents/adapters.ts
+++ b/client/src/components/Chat/Subagents/adapters.ts
@@ -32,6 +32,10 @@ export type ChildActivityItem =
input?: string | Record<string, unknown>;
output?: string;
status: 'running' | 'completed' | 'failed' | 'cancelled';
+ toolPreparationStartedAt?: number;
+ toolDispatchedAt?: number;
+ toolPreparationDurationMs?: number;
+ toolExecutionDurationMs?: number;
inputValidationError?: true;
approval?: Agents.ToolCall['approval'];
inputTruncated?: boolean;
@@ -78,6 +82,10 @@ type ContentToolCall = {
name?: string;
progress?: number;
runStepStatus?: PartMetadata['runStepStatus'];
+ toolPreparationStartedAt?: number;
+ toolDispatchedAt?: number;
+ toolPreparationDurationMs?: number;
+ toolExecutionDurationMs?: number;
inputValidationError?: true;
approval?: Agents.ToolCall['approval'];
};
@@ -163,6 +171,16 @@ const contentPartsToActivity = (
...(tool.args == null ? {} : { input: tool.args }),
...(tool.output == null ? {} : { output: tool.output }),
status: runStepStatus ?? (completed ? 'completed' : 'running'),
+ ...(tool.toolPreparationStartedAt == null
+ ? {}
+ : { toolPreparationStartedAt: tool.toolPreparationStartedAt }),
+ ...(tool.toolDispatchedAt == null ? {} : { toolDispatchedAt: tool.toolDispatchedAt }),
+ ...(tool.toolPreparationDurationMs == null
+ ? {}
+ : { toolPreparationDurationMs: tool.toolPreparationDurationMs }),
+ ...(tool.toolExecutionDurationMs == null
+ ? {}
+ : { toolExecutionDurationMs: tool.toolExecutionDurationMs }),
...(tool.inputValidationError === true ? { inputValidationError: true } : {}),
...(tool.approval == null || approvalVisibility === 'hidden'
? {}
diff --git a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts b/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts
index ca8d4a7b5b..fd5fa24dd8 100644
--- a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts
+++ b/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts
@@ -1817,6 +1817,338 @@ describe('useStepHandler', () => {
});
describe('on_run_step_delta event', () => {
+ it('separates streamed preparation, dispatch, and this call’s result', () => {
+ mockGetMessages.mockReturnValue([createResponseMessage()]);
+ const { result } = renderHook(() => useStepHandler(createHookParams()));
+ const submission = createSubmission();
+ const latest = () => {
+ const messages = mockSetMessages.mock.lastCall?.[0] as TMessage[] | undefined;
+ const part = messages?.find((message) => message.messageId === 'response-msg-1')
+ ?.content?.[0];
+ return part?.type === ContentTypes.TOOL_CALL ? part.tool_call : undefined;
+ };
+ act(() => {
+ result.current.stepHandler(
+ { event: StepEvents.ON_RUN_STEP, data: createToolCallRunStep() },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_DELTA,
+ data: {
+ id: 'step-tool-1',
+ observed_at: 1_000,
+ delta: {
+ type: StepTypes.TOOL_CALLS,
+ tool_calls: [{ id: 'tool-call-1', index: 0, args: '{' }],
+ },
+ },
+ },
+ submission,
+ );
+ });
+ expect(latest()?.toolPreparationStartedAt).toBe(1_000);
+ expect(latest()?.toolDispatchedAt).toBeUndefined();
+ act(() => {
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ data: {
+ dispatched_at: 248_000,
+ toolCalls: [{ id: 'tool-call-1', name: 'test_tool', stepId: 'step-tool-1' }],
+ },
+ },
+ submission,
+ );
+ });
+ expect(latest()?.toolDispatchedAt).toBe(248_000);
+ act(() => {
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_COMPLETED,
+ data: {
+ result: {
+ id: 'step-tool-1',
+ index: 0,
+ completed_at: 248_340,
+ tool_call: { id: 'tool-call-1', name: 'test_tool', args: '{}', output: 'done' },
+ },
+ },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_CLOSED,
+ data: {
+ id: 'step-tool-1',
+ index: 0,
+ type: StepTypes.TOOL_CALLS,
+ status: 'completed',
+ created_at: 1_000,
+ closed_at: 248_340,
+ },
+ },
+ submission,
+ );
+ });
+ expect(latest()).toMatchObject({
+ runStepStatus: 'completed',
+ runStepDurationMs: 247_340,
+ runStepClosedAt: 248_340,
+ toolPreparationDurationMs: 247_000,
+ toolExecutionDurationMs: 340,
+ });
+ });
+
+ it('retains an ID-less first-fragment timestamp when the call receives its ID later', () => {
+ mockGetMessages.mockReturnValue([createResponseMessage()]);
+ const { result } = renderHook(() => useStepHandler(createHookParams()));
+ const submission = createSubmission();
+ act(() => {
+ result.current.stepHandler(
+ { event: StepEvents.ON_RUN_STEP, data: createToolCallRunStep() },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_DELTA,
+ data: {
+ id: 'step-tool-1',
+ observed_at: 100,
+ delta: { type: StepTypes.TOOL_CALLS, tool_calls: [{ index: 0, args: '{' }] },
+ },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_DELTA,
+ data: {
+ id: 'step-tool-1',
+ observed_at: 200,
+ delta: {
+ type: StepTypes.TOOL_CALLS,
+ tool_calls: [{ id: 'tool-call-1', index: 0, args: '"x":1}' }],
+ },
+ },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ data: {
+ dispatched_at: 500,
+ toolCalls: [{ id: 'tool-call-1', name: 'test_tool', stepId: 'step-tool-1' }],
+ },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_COMPLETED,
+ data: {
+ result: {
+ id: 'step-tool-1',
+ index: 0,
+ completed_at: 530,
+ tool_call: { id: 'tool-call-1', name: 'test_tool', args: '{}', output: 'done' },
+ },
+ },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_CLOSED,
+ data: {
+ id: 'step-tool-1',
+ index: 0,
+ type: StepTypes.TOOL_CALLS,
+ status: 'completed',
+ created_at: 100,
+ closed_at: 530,
+ },
+ },
+ submission,
+ );
+ });
+ const messages = mockSetMessages.mock.lastCall?.[0] as TMessage[] | undefined;
+ const part = messages?.find((message) => message.messageId === 'response-msg-1')
+ ?.content?.[0];
+ expect(part?.type === ContentTypes.TOOL_CALL ? part.tool_call : undefined).toMatchObject({
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 30,
+ });
+ });
+
+ it('restores the Preparing and Calling phases from compact replay events', () => {
+ mockGetMessages.mockReturnValue([createResponseMessage()]);
+ const { result } = renderHook(() => useStepHandler(createHookParams()));
+ const submission = createSubmission();
+ const currentPart = () => {
+ const response = (mockSetMessages.mock.lastCall?.[0] as TMessage[] | undefined)?.find(
+ (message) => message.messageId === 'response-msg-1',
+ );
+ const part = response?.content?.[0];
+ return part?.type === ContentTypes.TOOL_CALL ? part.tool_call : undefined;
+ };
+ act(() => {
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_TOOL_PREPARATION,
+ data: { id: 'step-tool-1', toolCallId: 'tool-call-1', index: 0, observed_at: 100 },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP,
+ data: createToolCallRunStep(),
+ },
+ submission,
+ );
+ });
+ expect(currentPart()?.toolPreparationStartedAt).toBe(100);
+ act(() => {
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ data: {
+ dispatched_at: 500,
+ toolCalls: [{ id: 'tool-call-1', name: 'test_tool', stepId: 'step-tool-1' }],
+ },
+ },
+ submission,
+ );
+ });
+ expect(currentPart()?.toolDispatchedAt).toBe(500);
+ act(() => {
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_COMPLETED,
+ data: {
+ result: {
+ id: 'step-tool-1',
+ index: 0,
+ completed_at: 540,
+ tool_call: { id: 'tool-call-1', name: 'test_tool', args: '{}', output: 'done' },
+ },
+ },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_CLOSED,
+ data: {
+ id: 'step-tool-1',
+ type: StepTypes.TOOL_CALLS,
+ index: 0,
+ status: 'completed',
+ created_at: 90,
+ closed_at: 540,
+ },
+ },
+ submission,
+ );
+ });
+ expect(currentPart()).toMatchObject({
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 40,
+ });
+ });
+
+ it('isolates duplicate provider IDs across simultaneous run steps', () => {
+ mockGetMessages.mockReturnValue([createResponseMessage()]);
+ const { result } = renderHook(() => useStepHandler(createHookParams()));
+ const submission = createSubmission();
+ for (const [id, index, observedAt, dispatchedAt, completedAt] of [
+ ['step-tool-1', 0, 100, 300, 310],
+ ['step-tool-2', 1, 200, 500, 550],
+ ] as const) {
+ act(() => {
+ result.current.stepHandler(
+ { event: StepEvents.ON_RUN_STEP, data: createToolCallRunStep({ id, index }) },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_DELTA,
+ data: {
+ id,
+ observed_at: observedAt,
+ delta: {
+ type: StepTypes.TOOL_CALLS,
+ tool_calls: [{ id: 'tool-call-1', index: 0, args: '{' }],
+ },
+ },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ data: {
+ dispatched_at: dispatchedAt,
+ toolCalls: [{ id: 'tool-call-1', name: 'test_tool', stepId: id }],
+ },
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_COMPLETED,
+ data: {
+ result: {
+ id,
+ index,
+ completed_at: completedAt,
+ tool_call: { id: 'tool-call-1', name: 'test_tool', args: '{}', output: 'done' },
+ },
+ },
+ },
+ submission,
+ );
+ });
+ }
+ for (const [id, index, closedAt] of [
+ ['step-tool-1', 0, 310],
+ ['step-tool-2', 1, 550],
+ ] as const) {
+ act(() => {
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP_CLOSED,
+ data: {
+ id,
+ index,
+ type: StepTypes.TOOL_CALLS,
+ status: 'completed',
+ created_at: 100,
+ closed_at: closedAt,
+ },
+ },
+ submission,
+ );
+ });
+ }
+ const parts = (mockSetMessages.mock.lastCall?.[0] as TMessage[] | undefined)?.find(
+ (message) => message.messageId === 'response-msg-1',
+ )?.content;
+ const first = parts?.[0];
+ const second = parts?.[1];
+ expect(first?.type === ContentTypes.TOOL_CALL ? first.tool_call : undefined).toMatchObject({
+ toolPreparationDurationMs: 200,
+ toolExecutionDurationMs: 10,
+ });
+ expect(second?.type === ContentTypes.TOOL_CALL ? second.tool_call : undefined).toMatchObject({
+ toolPreparationDurationMs: 300,
+ toolExecutionDurationMs: 50,
+ });
+ });
+
it('should update tool call with delta args', () => {
const responseMessage = createResponseMessage();
mockGetMessages.mockReturnValue([responseMessage]);
diff --git a/client/src/hooks/SSE/useStepHandler.ts b/client/src/hooks/SSE/useStepHandler.ts
index f6a08bf63f..4fd07ffc7c 100644
--- a/client/src/hooks/SSE/useStepHandler.ts
+++ b/client/src/hooks/SSE/useStepHandler.ts
@@ -10,6 +10,7 @@ import {
getNonEmptyValue,
getRunStepDurationMs,
getRunStepCloseMetadata,
+ getToolTimingDurations,
} from 'librechat-data-provider';
import type {
Agents,
@@ -61,12 +62,16 @@ type TUseStepHandler = {
onSubagentIndexChange?: (conversationId: string) => void;
};
+const toolTimingKey = (stepId: string, callId: string) => `${stepId}\u0000${callId}`;
+
type TStepEvent =
| { event: StepEvents.ON_RUN_STEP; data: Agents.RunStep }
| { event: StepEvents.ON_AGENT_UPDATE; data: Agents.AgentUpdate }
| { event: StepEvents.ON_MESSAGE_DELTA; data: Agents.MessageDeltaEvent }
| { event: StepEvents.ON_REASONING_DELTA; data: Agents.ReasoningDeltaEvent }
| { event: StepEvents.ON_RUN_STEP_DELTA; data: Agents.RunStepDeltaEvent }
+ | { event: StepEvents.ON_TOOL_CALLS_DISPATCHED; data: Agents.ToolCallsDispatchedEvent }
+ | { event: StepEvents.ON_TOOL_PREPARATION; data: Agents.ToolPreparationMarker }
| { event: StepEvents.ON_RUN_STEP_COMPLETED; data: { result: Agents.ToolEndEvent } }
| { event: StepEvents.ON_RUN_STEP_CLOSED; data: Agents.RunStepClosedEvent }
| { event: StepEvents.ON_SUMMARIZE_START; data: Agents.SummarizeStartEvent }
@@ -165,6 +170,10 @@ export default function useStepHandler({
}: TUseStepHandler) {
const subagentStore = useStore();
const toolCallIdMap = useRef(new Map<string, string | undefined>());
+ const firstFragmentByCall = useRef(new Map<string, number>());
+ const firstFragmentByStep = useRef(new Map<string, number>());
+ const dispatchedByCall = useRef(new Map<string, number>());
+ const completedByCall = useRef(new Map<string, number>());
const messageMap = useRef(new Map<string, TMessage>());
const stepMap = useRef(new Map<string, Agents.RunStep>());
/** Buffer for deltas that arrive before their corresponding run step */
@@ -622,7 +631,9 @@ export default function useStepHandler({
};
} else if (contentType === ContentTypes.TOOL_CALL && 'tool_call' in contentPart) {
const existingContent = updatedContent[index] as Agents.ToolCallContent | undefined;
- const existingToolCall = existingContent?.tool_call;
+ const existingToolCall = existingContent?.tool_call as
+ | (Agents.ToolCall & PartMetadata)
+ | undefined;
const toolCallArgs = (contentPart.tool_call as Agents.ToolCall).args;
/** When args are a valid object, they are likely already invoked */
let args =
@@ -647,6 +658,11 @@ export default function useStepHandler({
type: ToolCallTypes.TOOL_CALL,
auth: contentPart.tool_call.auth,
expires_at: contentPart.tool_call.expires_at,
+ toolPreparationStartedAt:
+ contentPart.tool_call.toolPreparationStartedAt ??
+ existingToolCall?.toolPreparationStartedAt,
+ toolDispatchedAt:
+ contentPart.tool_call.toolDispatchedAt ?? existingToolCall?.toolDispatchedAt,
};
if (finalUpdate) {
@@ -956,6 +972,7 @@ export default function useStepHandler({
// Store tool call IDs if present
if (runStep.stepDetails.type === StepTypes.TOOL_CALLS) {
+ const streamedCallCount = runStep.stepDetails.tool_calls?.length ?? 0;
let updatedResponse = { ...response };
((runStep.stepDetails.tool_calls ?? []) as Agents.ToolCall[]).forEach((toolCall) => {
const toolCallId = toolCall.id ?? '';
@@ -970,6 +987,14 @@ export default function useStepHandler({
args: toolCall.args,
id: toolCallId,
stepId: runStep.id,
+ toolPreparationStartedAt:
+ firstFragmentByCall.current.get(toolTimingKey(runStep.id, toolCallId)) ??
+ (streamedCallCount <= 1
+ ? firstFragmentByStep.current.get(runStep.id)
+ : undefined),
+ toolDispatchedAt: dispatchedByCall.current.get(
+ toolTimingKey(runStep.id, toolCallId),
+ ),
},
};
@@ -1200,8 +1225,92 @@ export default function useStepHandler({
scheduleCoalescedMessagesFlush(responseMessageId);
}
}
+ } else if (stepEvent.event === StepEvents.ON_TOOL_PREPARATION) {
+ const { id, index, toolCallId, observed_at: at } = stepEvent.data;
+ if (!id || typeof at !== 'number' || !Number.isFinite(at) || at < 0) return;
+ const runStep = stepMap.current.get(id);
+ const declaredCalls =
+ runStep?.stepDetails.type === StepTypes.TOOL_CALLS
+ ? runStep.stepDetails.tool_calls
+ : undefined;
+ const resolvedId =
+ toolCallId ??
+ (index === 0 && declaredCalls?.length === 1 ? declaredCalls[0]?.id : undefined);
+ if (resolvedId) {
+ const key = toolTimingKey(id, resolvedId);
+ firstFragmentByCall.current.set(
+ key,
+ Math.min(firstFragmentByCall.current.get(key) ?? at, at),
+ );
+ } else if (index === 0) {
+ firstFragmentByStep.current.set(
+ id,
+ Math.min(firstFragmentByStep.current.get(id) ?? at, at),
+ );
+ }
+ if (!runStep?.runId || (runStep.status && runStep.status !== 'in_progress')) return;
+ const responseId =
+ runStep.runId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID
+ ? (submission.initialResponse?.messageId ?? '')
+ : runStep.runId;
+ const response = messageMap.current.get(responseId);
+ const contentIndex = runStep.index + editPrefixOffset;
+ const part = response?.content?.[contentIndex];
+ if (
+ !response ||
+ part?.type !== ContentTypes.TOOL_CALL ||
+ part.tool_call.runStepStatus != null ||
+ (resolvedId && part.tool_call.id !== resolvedId)
+ )
+ return;
+ const content = [...(response.content ?? [])];
+ content[contentIndex] = {
+ ...part,
+ tool_call: {
+ ...part.tool_call,
+ toolPreparationStartedAt: Math.min(part.tool_call.toolPreparationStartedAt ?? at, at),
+ },
+ };
+ const updated = { ...response, content };
+ messageMap.current.set(responseId, updated);
+ setMessages(
+ mergeResponseMessage(messages, updated, responseId, { ensureUserMessage: true }),
+ );
} else if (stepEvent.event === StepEvents.ON_RUN_STEP_DELTA) {
const runStepDelta = stepEvent.data;
+ const at = runStepDelta.observed_at;
+ if (typeof at === 'number' && Number.isFinite(at) && at >= 0) {
+ for (const chunk of runStepDelta.delta.tool_calls ?? []) {
+ if (chunk.id) {
+ const first =
+ chunk.index === 0 ? firstFragmentByStep.current.get(runStepDelta.id) : undefined;
+ const key = toolTimingKey(runStepDelta.id, chunk.id);
+ firstFragmentByCall.current.set(
+ key,
+ Math.min(firstFragmentByCall.current.get(key) ?? at, first ?? at, at),
+ );
+ if (first != null) firstFragmentByStep.current.delete(runStepDelta.id);
+ } else if (chunk.index === 0 && runStepDelta.delta.tool_calls?.length === 1) {
+ const declared = stepMap.current.get(runStepDelta.id)?.stepDetails;
+ const firstCallId =
+ declared?.type === StepTypes.TOOL_CALLS && declared.tool_calls?.length === 1
+ ? declared.tool_calls[0]?.id
+ : undefined;
+ if (firstCallId) {
+ const key = toolTimingKey(runStepDelta.id, firstCallId);
+ firstFragmentByCall.current.set(
+ key,
+ Math.min(firstFragmentByCall.current.get(key) ?? at, at),
+ );
+ } else {
+ firstFragmentByStep.current.set(
+ runStepDelta.id,
+ Math.min(firstFragmentByStep.current.get(runStepDelta.id) ?? at, at),
+ );
+ }
+ }
+ }
+ }
const runStep = stepMap.current.get(runStepDelta.id);
let responseMessageId = runStep?.runId ?? '';
if (responseMessageId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID) {
@@ -1225,7 +1334,7 @@ export default function useStepHandler({
let updatedResponse = { ...response };
runStepDelta.delta.tool_calls.forEach((toolCallDelta) => {
- const toolCallId = toolCallIdMap.current.get(runStepDelta.id) ?? '';
+ const toolCallId = toolCallDelta.id || toolCallIdMap.current.get(runStepDelta.id) || '';
const contentPart: Agents.MessageContentComplex = {
type: ContentTypes.TOOL_CALL,
@@ -1234,6 +1343,14 @@ export default function useStepHandler({
args: toolCallDelta.args ?? '',
id: toolCallId,
stepId: runStepDelta.id,
+ toolPreparationStartedAt:
+ firstFragmentByCall.current.get(toolTimingKey(runStepDelta.id, toolCallId)) ??
+ (toolCallDelta.index === 0
+ ? firstFragmentByStep.current.get(runStepDelta.id)
+ : undefined),
+ toolDispatchedAt: dispatchedByCall.current.get(
+ toolTimingKey(runStepDelta.id, toolCallId),
+ ),
},
};
@@ -1260,11 +1377,55 @@ export default function useStepHandler({
}),
);
}
+ } else if (stepEvent.event === StepEvents.ON_TOOL_CALLS_DISPATCHED) {
+ const { dispatched_at: at, toolCalls } = stepEvent.data;
+ if (typeof at !== 'number' || !Number.isFinite(at) || at < 0) return;
+ for (const call of toolCalls ?? []) {
+ if (!call.id) continue;
+ if (!call.stepId) continue;
+ const key = toolTimingKey(call.stepId, call.id);
+ const dispatchedAt = Math.min(dispatchedByCall.current.get(key) ?? at, at);
+ dispatchedByCall.current.set(key, dispatchedAt);
+ const runStep = stepMap.current.get(call.stepId ?? '');
+ if (!runStep?.runId) continue;
+ const responseId =
+ runStep.runId === Constants.USE_PRELIM_RESPONSE_MESSAGE_ID
+ ? (submission.initialResponse?.messageId ?? '')
+ : runStep.runId;
+ const response = messageMap.current.get(responseId);
+ const index = runStep.index + editPrefixOffset;
+ const part = response?.content?.[index];
+ if (
+ !response ||
+ part?.type !== ContentTypes.TOOL_CALL ||
+ part.tool_call.id !== call.id ||
+ part.tool_call.runStepStatus != null
+ )
+ continue;
+ const content = [...(response.content ?? [])];
+ content[index] = {
+ ...part,
+ tool_call: { ...part.tool_call, toolDispatchedAt: dispatchedAt },
+ };
+ const updated = { ...response, content };
+ messageMap.current.set(responseId, updated);
+ setMessages(
+ mergeResponseMessage(messages, updated, responseId, { ensureUserMessage: true }),
+ );
+ }
} else if (stepEvent.event === StepEvents.ON_RUN_STEP_COMPLETED) {
const { result } = stepEvent.data;
const { id: stepId } = result;
- clearSandboxStarting(result.tool_call?.id);
+ const completedCallId = result.tool_call?.id;
+ if (
+ completedCallId &&
+ typeof result.completed_at === 'number' &&
+ Number.isFinite(result.completed_at)
+ ) {
+ completedByCall.current.set(toolTimingKey(stepId, completedCallId), result.completed_at);
+ }
+ clearSandboxStarting(completedCallId);
const runStep = stepMap.current.get(stepId);
let responseMessageId = runStep?.runId ?? '';
@@ -1351,6 +1512,25 @@ export default function useStepHandler({
* server already stamped in place, rather than overwriting it with
* `undefined`. */
const durationMs = getRunStepDurationMs(closed);
+ const callId = existingToolCall.id ?? '';
+ const key = toolTimingKey(closed.id, callId);
+ const singleCallStep =
+ runStep.stepDetails.type === StepTypes.TOOL_CALLS &&
+ (runStep.stepDetails.tool_calls?.length ?? 0) <= 1;
+ const observedAt = Math.min(
+ firstFragmentByCall.current.get(key) ?? Infinity,
+ existingToolCall.toolPreparationStartedAt ?? Infinity,
+ singleCallStep ? (firstFragmentByStep.current.get(closed.id) ?? Infinity) : Infinity,
+ );
+ const timing = getToolTimingDurations({
+ observedAt: Number.isFinite(observedAt) ? observedAt : undefined,
+ dispatchedAt: existingToolCall.toolDispatchedAt ?? dispatchedByCall.current.get(key),
+ completedAt: completedByCall.current.get(key),
+ });
+ firstFragmentByCall.current.delete(key);
+ firstFragmentByStep.current.delete(closed.id);
+ dispatchedByCall.current.delete(key);
+ completedByCall.current.delete(key);
const updatedContent = [...(response.content ?? [])];
updatedContent[currentIndex] = {
...existing,
@@ -1359,6 +1539,7 @@ export default function useStepHandler({
runStepStatus: closed.status,
...getRunStepCloseMetadata(closed),
...(durationMs != null && { runStepDurationMs: durationMs }),
+ ...timing,
},
};
@@ -1561,6 +1742,10 @@ export default function useStepHandler({
}
cancelPendingDeltaFlush();
toolCallIdMap.current.clear();
+ firstFragmentByCall.current.clear();
+ firstFragmentByStep.current.clear();
+ dispatchedByCall.current.clear();
+ completedByCall.current.clear();
messageMap.current.clear();
stepMap.current.clear();
pendingDeltaBuffer.current.clear();
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index ced97bbc6d..da661641f9 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -1468,6 +1468,11 @@
"com_ui_duration_announced_seconds_one": "took {{count}} second",
"com_ui_duration_minutes": "{{0}}m {{1}}s",
"com_ui_duration_seconds": "{{0}}s",
+ "com_ui_tool_preparing": "Preparing {{0}}",
+ "com_ui_tool_calling": "Calling {{0}}",
+ "com_ui_tool_preparation_time": "Preparation",
+ "com_ui_tool_call_time": "Tool call",
+ "com_ui_tool_total_time": "Total elapsed",
"com_ui_during_run_actions": "More send options",
"com_ui_edit": "Edit",
"com_ui_edit_editing_image": "Editing image",
diff --git a/client/src/utils/__tests__/subagentContent.test.ts b/client/src/utils/__tests__/subagentContent.test.ts
index dd8782dcfc..e861303b0f 100644
--- a/client/src/utils/__tests__/subagentContent.test.ts
+++ b/client/src/utils/__tests__/subagentContent.test.ts
@@ -160,6 +160,105 @@ describe('aggregateSubagentContent', () => {
expect((parts[0] as { tool_call: { progress: number } }).tool_call.progress).toBe(0.1);
});
+ it('folds a child handoff into its own running tool card and measured call time', () => {
+ const events = [
+ makeEvent({
+ phase: 'run_step',
+ data: {
+ id: 'step-child',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-child', name: 'query', args: '{}' }],
+ },
+ },
+ }),
+ makeEvent({
+ phase: 'tool_preparation',
+ data: {
+ id: 'step-child',
+ toolCallId: 'call-child',
+ observed_at: 100,
+ },
+ }),
+ makeEvent({
+ phase: 'tool_calls_dispatched',
+ data: {
+ dispatched_at: 500,
+ toolCalls: [
+ { id: 'call-child', stepId: 'step-child', name: 'query' },
+ { id: 'other-child', stepId: 'other-step', name: 'query' },
+ ],
+ },
+ }),
+ ];
+ const running = aggregateSubagentContent(events);
+ expect(running[0]).toMatchObject({
+ tool_call: {
+ id: 'call-child',
+ stepId: 'step-child',
+ toolPreparationStartedAt: 100,
+ toolDispatchedAt: 500,
+ progress: 0.1,
+ },
+ });
+ const completed = aggregateSubagentContent([
+ ...events,
+ makeEvent({
+ phase: 'run_step_completed',
+ data: {
+ result: {
+ id: 'step-child',
+ completed_at: 540,
+ type: 'tool_call',
+ tool_call: { id: 'call-child', name: 'query', args: '{}', output: 'ok', progress: 1 },
+ },
+ },
+ }),
+ ]);
+ expect(completed[0]).toMatchObject({
+ tool_call: {
+ id: 'call-child',
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 40,
+ output: 'ok',
+ progress: 1,
+ },
+ });
+ });
+
+ it('ignores a late handoff for a settled child tool', () => {
+ const completed = aggregateSubagentContent([
+ makeEvent({
+ phase: 'run_step',
+ data: {
+ id: 'step-child',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-child', name: 'query', args: '{}' }],
+ },
+ },
+ }),
+ makeEvent({
+ phase: 'run_step_completed',
+ data: {
+ result: {
+ id: 'step-child',
+ completed_at: 540,
+ tool_call: { id: 'call-child', name: 'query', output: 'ok', progress: 1 },
+ },
+ },
+ }),
+ makeEvent({
+ phase: 'tool_calls_dispatched',
+ data: {
+ dispatched_at: 500,
+ toolCalls: [{ id: 'call-child', stepId: 'step-child' }],
+ },
+ }),
+ ]);
+ expect(completed[0]).not.toHaveProperty('tool_call.toolDispatchedAt');
+ });
+
it('finalizes a TOOL_CALL part on run_step_completed with output and progress=1', () => {
const parts = aggregateSubagentContent([
makeEvent({
diff --git a/client/src/utils/subagentContent.ts b/client/src/utils/subagentContent.ts
index 393c67278e..ccab985ddd 100644
--- a/client/src/utils/subagentContent.ts
+++ b/client/src/utils/subagentContent.ts
@@ -1,4 +1,4 @@
-import { ContentTypes, ToolCallTypes } from 'librechat-data-provider';
+import { ContentTypes, ToolCallTypes, getToolTimingDurations } from 'librechat-data-provider';
import type { SubagentUpdateEvent } from 'librechat-data-provider';
/**
@@ -35,6 +35,8 @@ type RunStepData = {
type RunStepCompletedData = {
result?: {
+ id?: string;
+ completed_at?: number;
type?: string;
tool_call?: {
id?: string;
@@ -51,6 +53,17 @@ type RunStepClosedData = {
id?: string;
};
+type ToolDispatchData = {
+ dispatched_at?: number;
+ toolCalls?: Array<{ id?: string; stepId?: string }>;
+};
+
+type ToolPreparationData = {
+ id?: string;
+ toolCallId?: string;
+ observed_at?: number;
+};
+
type MessageDeltaData = {
id?: string;
delta?: {
@@ -81,6 +94,11 @@ type ToolCallPart = {
progress: number;
inputValidationError?: true;
type?: string;
+ stepId?: string;
+ toolPreparationStartedAt?: number;
+ toolDispatchedAt?: number;
+ toolPreparationDurationMs?: number;
+ toolExecutionDurationMs?: number;
};
};
@@ -269,6 +287,7 @@ export function foldSubagentEvent(
type: ContentTypes.TOOL_CALL,
tool_call: {
id: tc.id,
+ ...(typeof data?.id === 'string' ? { stepId: data.id } : {}),
name: tc.name ?? '',
args: stringifyArgs(tc.args),
progress: 0.1,
@@ -291,6 +310,57 @@ export function foldSubagentEvent(
};
}
+ if (event.phase === 'tool_preparation') {
+ const data = event.data as ToolPreparationData | undefined;
+ const id = data?.toolCallId;
+ const at = data?.observed_at;
+ if (!id || typeof at !== 'number' || !Number.isFinite(at) || at < 0) return { parts, state };
+ const idx = state.toolCallIndexById[id];
+ const part = idx == null ? undefined : parts[idx];
+ if (
+ part?.type !== ContentTypes.TOOL_CALL ||
+ part.tool_call.stepId !== data.id ||
+ part.tool_call.progress >= 1
+ )
+ return { parts, state };
+ const next = parts.slice();
+ next[idx] = {
+ ...part,
+ tool_call: {
+ ...part.tool_call,
+ toolPreparationStartedAt: Math.min(part.tool_call.toolPreparationStartedAt ?? at, at),
+ },
+ };
+ return { parts: next, state };
+ }
+
+ if (event.phase === 'tool_calls_dispatched') {
+ const data = event.data as ToolDispatchData | undefined;
+ const at = data?.dispatched_at;
+ if (typeof at !== 'number' || !Number.isFinite(at) || at < 0) return { parts, state };
+ let next = parts;
+ for (const call of data?.toolCalls ?? []) {
+ if (!call.id || !call.stepId) continue;
+ const idx = state.toolCallIndexById[call.id];
+ const part = idx == null ? undefined : next[idx];
+ if (
+ part?.type !== ContentTypes.TOOL_CALL ||
+ part.tool_call.stepId !== call.stepId ||
+ part.tool_call.progress >= 1
+ )
+ continue;
+ if (next === parts) next = parts.slice();
+ next[idx] = {
+ ...part,
+ tool_call: {
+ ...part.tool_call,
+ toolDispatchedAt: Math.min(part.tool_call.toolDispatchedAt ?? at, at),
+ },
+ };
+ }
+ return { parts: next, state };
+ }
+
if (event.phase === 'run_step_completed') {
const data = event.data as RunStepCompletedData | undefined;
const tc = data?.result?.tool_call;
@@ -298,10 +368,19 @@ export function foldSubagentEvent(
const existingIdx = state.toolCallIndexById[tc.id];
if (existingIdx != null) {
const existing = parts[existingIdx] as ToolCallPart;
+ const timings =
+ data?.result?.id === existing.tool_call.stepId
+ ? getToolTimingDurations({
+ observedAt: existing.tool_call.toolPreparationStartedAt,
+ dispatchedAt: existing.tool_call.toolDispatchedAt,
+ completedAt: data?.result?.completed_at,
+ })
+ : {};
const merged: ToolCallPart = {
type: ContentTypes.TOOL_CALL,
tool_call: {
...existing.tool_call,
+ ...timings,
...(tc.name ? { name: tc.name } : {}),
...(tc.args != null ? { args: stringifyArgs(tc.args) } : {}),
...(tc.output != null ? { output: tc.output } : {}),
diff --git a/package-lock.json b/package-lock.json
index 85504bcc0e..47d470a9d8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10622,9 +10622,9 @@
}
},
"node_modules/@librechat/agents": {
- "version": "3.9.7",
- "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.9.7.tgz",
- "integrity": "sha512-r3JSh7ACjKVn/ZzDlXtRU/l16L19pxjlPzcTxa+h+Myol3qLDdx/ldmSiNpSFMUQcGDcCxE07A+ZJWhChcaBZg==",
+ "version": "3.9.8",
+ "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.9.8.tgz",
+ "integrity": "sha512-mVunoG+xQ7dXTDCLF2CmeDnrWOs0BCpZzNRqZZwoXEfLToXGkIjZiGFPiffhsQ6FkOn6DvMipzBFLKA9k5G2YA==",
"license": "MIT",
"dependencies": {
"@anthropic-ai/sdk": "^0.115.0",
@@ -42428,7 +42428,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "5.1.6",
- "@librechat/agents": "^3.9.7",
+ "@librechat/agents": "^3.9.8",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.30.0",
"@opentelemetry/api": "^1.9.0",
diff --git a/packages/api/package.json b/packages/api/package.json
index bf9bb07619..d9259129df 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -120,7 +120,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "5.1.6",
- "@librechat/agents": "^3.9.7",
+ "@librechat/agents": "^3.9.8",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.30.0",
"@opentelemetry/api": "^1.9.0",
diff --git a/packages/api/src/agents/activity.spec.ts b/packages/api/src/agents/activity.spec.ts
index 7113971ca0..6b2938bb06 100644
--- a/packages/api/src/agents/activity.spec.ts
+++ b/packages/api/src/agents/activity.spec.ts
@@ -6,6 +6,49 @@ import {
} from './activity';
describe('durable subagent activity projection', () => {
+ it('drops negative or non-finite persisted child timings', () => {
+ const result = projectPersistedMessageActivity([
+ {
+ type: 'tool',
+ toolCallId: 'call-child',
+ name: 'query',
+ runStepStatus: 'completed',
+ toolPreparationStartedAt: -1,
+ toolDispatchedAt: Infinity,
+ toolPreparationDurationMs: -400,
+ toolExecutionDurationMs: NaN,
+ },
+ ]);
+ expect(result.activity[0]).toEqual({
+ type: 'tool',
+ toolCallId: 'call-child',
+ name: 'query',
+ status: 'completed',
+ });
+ });
+
+ it('preserves split tool timing through a bounded persisted child view', () => {
+ const result = projectPersistedMessageActivity([
+ {
+ type: 'tool',
+ toolCallId: 'call-child',
+ name: 'query',
+ runStepStatus: 'completed',
+ toolPreparationStartedAt: 100,
+ toolDispatchedAt: 500,
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 40,
+ },
+ ]);
+ expect(result.activity[0]).toMatchObject({
+ type: 'tool',
+ toolCallId: 'call-child',
+ toolPreparationStartedAt: 100,
+ toolDispatchedAt: 500,
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 40,
+ });
+ });
it('projects ordinary persisted chat content into the shared activity vocabulary', () => {
const projection = projectPersistedMessageActivity([
{ type: 'reasoning' },
diff --git a/packages/api/src/agents/activity.ts b/packages/api/src/agents/activity.ts
index 7d0aa864d7..0f2df76684 100644
--- a/packages/api/src/agents/activity.ts
+++ b/packages/api/src/agents/activity.ts
@@ -139,6 +139,11 @@ const visibleStatus = (value: unknown): 'running' | 'completed' | 'failed' | 'ca
const finiteNumber = (value: unknown): number | undefined =>
typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+const nonNegativeTiming = (value: unknown): number | undefined => {
+ const parsed = finiteNumber(value);
+ return parsed != null && parsed >= 0 ? parsed : undefined;
+};
+
const stringArray = (value: unknown): string[] | undefined => {
if (!Array.isArray(value)) return undefined;
const result = value.filter((candidate): candidate is string => typeof candidate === 'string');
@@ -227,6 +232,10 @@ export function projectPersistedMessageActivity(
finiteNumber(candidate.progress) != null && finiteNumber(candidate.progress)! >= 1;
const output = typeof candidate.output === 'string' ? candidate.output : undefined;
const runStepStatus = visibleStatus(candidate.runStepStatus);
+ const toolPreparationStartedAt = nonNegativeTiming(candidate.toolPreparationStartedAt);
+ const toolDispatchedAt = nonNegativeTiming(candidate.toolDispatchedAt);
+ const toolPreparationDurationMs = nonNegativeTiming(candidate.toolPreparationDurationMs);
+ const toolExecutionDurationMs = nonNegativeTiming(candidate.toolExecutionDurationMs);
let status: MutableToolActivity['status'] = runStepStatus;
if (candidate.runStepStatus == null) {
status = completed || output != null ? 'completed' : 'running';
@@ -241,6 +250,10 @@ export function projectPersistedMessageActivity(
: {}),
...(output == null || output === '' ? {} : { output }),
status,
+ ...(toolPreparationStartedAt == null ? {} : { toolPreparationStartedAt }),
+ ...(toolDispatchedAt == null ? {} : { toolDispatchedAt }),
+ ...(toolPreparationDurationMs == null ? {} : { toolPreparationDurationMs }),
+ ...(toolExecutionDurationMs == null ? {} : { toolExecutionDurationMs }),
...(candidate.inputValidationError === true ? { inputValidationError: true } : {}),
...(candidate.inputTruncated === true ? { inputTruncated: true } : {}),
...(candidate.outputTruncated === true ? { outputTruncated: true } : {}),
diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.ts
index 5869bdf582..e4976ebf54 100644
--- a/packages/api/src/agents/index.ts
+++ b/packages/api/src/agents/index.ts
@@ -88,6 +88,7 @@ export * from './workspace';
export * from './reasoningLabels';
export * from './refusal';
export * from './toolValidation';
+export * from './toolTiming';
export * from './remote';
export * from './queuedTurns';
export * from './queuedTurnHttp';
diff --git a/packages/api/src/agents/toolTiming.spec.ts b/packages/api/src/agents/toolTiming.spec.ts
new file mode 100644
index 0000000000..f84a28e5b3
--- /dev/null
+++ b/packages/api/src/agents/toolTiming.spec.ts
@@ -0,0 +1,292 @@
+import { StepEvents } from 'librechat-data-provider';
+import { createToolTimingAdapter, createToolTimingTracker } from './toolTiming';
+
+describe('createToolTimingTracker', () => {
+ it('projects child dispatch and completion only onto its own persisted tool part', () => {
+ const part = { type: 'tool_call', tool_call: { id: 'child-call' } };
+ const aggregator = { contentParts: [part], stepMap: new Map([['child-step', { index: 0 }]]) };
+ const adapter = createToolTimingAdapter({ emit: async () => undefined });
+ adapter.child(aggregator, {
+ phase: 'tool_preparation',
+ data: {
+ id: 'child-step',
+ toolCallId: 'child-call',
+ observed_at: 100,
+ },
+ });
+ adapter.child(aggregator, {
+ phase: 'tool_calls_dispatched',
+ data: {
+ dispatched_at: 1_000,
+ toolCalls: [
+ { id: 'different-call', stepId: 'child-step' },
+ { id: 'child-call', stepId: 'other-step' },
+ { id: 'child-call', stepId: 'child-step' },
+ ],
+ },
+ });
+ expect(part.tool_call).toMatchObject({ toolDispatchedAt: 1_000 });
+ const completedPart = { type: 'tool_call', tool_call: { id: 'child-call', output: 'ok' } };
+ aggregator.contentParts[0] = completedPart;
+ adapter.child(aggregator, {
+ phase: 'run_step_completed',
+ data: {
+ result: { id: 'child-step', completed_at: 1_340, tool_call: { id: 'child-call' } },
+ },
+ });
+ expect(completedPart.tool_call).toMatchObject({
+ toolPreparationStartedAt: 100,
+ toolPreparationDurationMs: 900,
+ toolDispatchedAt: 1_000,
+ toolExecutionDurationMs: 340,
+ });
+ });
+
+ it('publishes each first fragment once without forwarding tool arguments', async () => {
+ const publish = jest.fn(async () => undefined);
+ const adapter = createToolTimingAdapter({ emit: publish });
+ const fragment = {
+ id: 'step-1',
+ observed_at: 100,
+ delta: {
+ type: 'tool_calls' as const,
+ tool_calls: [{ id: 'call-1', index: 0, args: 'secret' }],
+ },
+ };
+ await adapter.delta(fragment);
+ await adapter.delta({ ...fragment, observed_at: 200 });
+ expect(publish).toHaveBeenCalledTimes(1);
+ expect(publish).toHaveBeenCalledWith({
+ event: StepEvents.ON_TOOL_PREPARATION,
+ data: { id: 'step-1', index: 0, toolCallId: 'call-1', observed_at: 100 },
+ });
+ });
+ it('records each call separately even when results complete out of order', () => {
+ const timing = createToolTimingTracker();
+ timing.observe({
+ id: 'step_a',
+ observed_at: 100,
+ delta: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'a', index: 0, args: '{' }],
+ },
+ });
+ timing.observe({
+ id: 'step_b',
+ observed_at: 200,
+ delta: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'b', index: 1, args: '{' }],
+ },
+ });
+ timing.dispatched({
+ dispatched_at: 500,
+ toolCalls: [
+ { id: 'a', stepId: 'step_a' },
+ { id: 'b', stepId: 'step_b' },
+ ],
+ });
+ timing.completed('step_b', 'b', 530);
+ timing.completed('step_a', 'a', 700);
+ expect(timing.take('b', 'step_b')).toEqual({
+ toolPreparationDurationMs: 300,
+ toolExecutionDurationMs: 30,
+ });
+ expect(timing.take('a', 'step_a')).toEqual({
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 200,
+ });
+ expect(timing.take('a', 'step_a')).toEqual({});
+ });
+
+ it('keeps an idless initial fragment for the sole first call without assigning sibling fragments', () => {
+ const timing = createToolTimingTracker();
+ timing.observe({
+ id: 'sole_step',
+ observed_at: 100,
+ delta: {
+ type: 'tool_calls',
+ tool_calls: [{ index: 0, args: '{' }],
+ },
+ });
+ timing.observe({
+ id: 'multi_step',
+ observed_at: 90,
+ delta: {
+ type: 'tool_calls',
+ tool_calls: [
+ { index: 0, args: '{' },
+ { index: 1, args: '{' },
+ ],
+ },
+ });
+ timing.dispatched({
+ dispatched_at: 400,
+ toolCalls: [
+ { id: 'sole', stepId: 'sole_step' },
+ { id: 'sibling', stepId: 'multi_step' },
+ ],
+ });
+ timing.completed('sole_step', 'sole', 405);
+ timing.completed('multi_step', 'sibling', 420);
+ expect(timing.take('sole', 'sole_step')).toEqual({
+ toolPreparationDurationMs: 300,
+ toolExecutionDurationMs: 5,
+ });
+ expect(timing.take('sibling', 'multi_step')).toEqual({ toolExecutionDurationMs: 20 });
+ });
+
+ it('keeps the earliest ID-less fragment when the first call gains an ID later', () => {
+ const timing = createToolTimingTracker();
+ timing.observe({
+ id: 'step',
+ observed_at: 100,
+ delta: { type: 'tool_calls', tool_calls: [{ index: 0, args: '{' }] },
+ });
+ timing.observe({
+ id: 'step',
+ observed_at: 200,
+ delta: { type: 'tool_calls', tool_calls: [{ id: 'call', index: 0, args: '"x":1}' }] },
+ });
+ timing.dispatched({ dispatched_at: 500, toolCalls: [{ id: 'call', stepId: 'step' }] });
+ timing.completed('step', 'call', 530);
+ expect(timing.take('call', 'step')).toEqual({
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 30,
+ });
+ });
+
+ it('keeps the earliest timestamp when a named fragment is delivered before the ID-less one', () => {
+ const timing = createToolTimingTracker();
+ timing.observe({
+ id: 'step',
+ observed_at: 200,
+ delta: { type: 'tool_calls', tool_calls: [{ id: 'call', index: 0, args: '"x":1}' }] },
+ });
+ timing.observe({
+ id: 'step',
+ observed_at: 100,
+ delta: { type: 'tool_calls', tool_calls: [{ index: 0, args: '{' }] },
+ });
+ timing.dispatched({ dispatched_at: 500, toolCalls: [{ id: 'call', stepId: 'step' }] });
+ timing.completed('step', 'call', 530);
+ expect(timing.take('call', 'step')).toEqual({
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 30,
+ });
+ });
+
+ it('uses the ID-less start for an indexless named fragment only when it owns the step', () => {
+ const timing = createToolTimingTracker();
+ timing.observe({
+ id: 'step',
+ observed_at: 100,
+ delta: { type: 'tool_calls', tool_calls: [{ index: 0, args: '{' }] },
+ });
+ timing.observe({
+ id: 'step',
+ observed_at: 200,
+ delta: { type: 'tool_calls', tool_calls: [{ id: 'call', args: '"x":1}' }] },
+ });
+ timing.dispatched({ dispatched_at: 500, toolCalls: [{ id: 'call', stepId: 'step' }] });
+ timing.completed('step', 'call', 530);
+ expect(timing.take('call', 'step')).toEqual({
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 30,
+ });
+ });
+
+ it('does not give an ID-less first call’s preparation to an unobserved sibling', () => {
+ const timing = createToolTimingTracker();
+ timing.observe({
+ id: 'step',
+ observed_at: 100,
+ delta: { type: 'tool_calls', tool_calls: [{ index: 0, args: '{' }] },
+ });
+ timing.dispatched({
+ dispatched_at: 500,
+ toolCalls: [
+ { id: 'first', stepId: 'step' },
+ { id: 'second', stepId: 'step' },
+ ],
+ });
+ timing.completed('step', 'second', 540);
+ expect(timing.take('second', 'step')).toEqual({ toolExecutionDurationMs: 40 });
+ });
+
+ it('keeps a first-call ID-less fragment after a faster sibling settles', () => {
+ const timing = createToolTimingTracker();
+ timing.observe({
+ id: 'step',
+ observed_at: 100,
+ delta: {
+ type: 'tool_calls',
+ tool_calls: [{ index: 0, args: '{' }],
+ },
+ });
+ timing.observe({
+ id: 'step',
+ observed_at: 200,
+ delta: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'first', index: 0, args: '"x":1}' }],
+ },
+ });
+ timing.dispatched({
+ dispatched_at: 500,
+ toolCalls: [
+ { id: 'first', stepId: 'step' },
+ { id: 'second', stepId: 'step' },
+ ],
+ });
+ timing.completed('step', 'second', 515);
+ expect(timing.take('second', 'step')).toEqual({ toolExecutionDurationMs: 15 });
+ timing.completed('step', 'first', 560);
+ expect(timing.take('first', 'step')).toEqual({
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 60,
+ });
+ });
+
+ it('isolates simultaneous duplicate provider call IDs by step', () => {
+ const timing = createToolTimingTracker();
+ for (const [stepId, observedAt, dispatchedAt, completedAt] of [
+ ['step_1', 100, 300, 310],
+ ['step_2', 150, 500, 550],
+ ] as const) {
+ timing.observe({
+ id: stepId,
+ observed_at: observedAt,
+ delta: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'shared', index: 0, args: '{' }],
+ },
+ });
+ timing.dispatched({ dispatched_at: dispatchedAt, toolCalls: [{ id: 'shared', stepId }] });
+ timing.completed(stepId, 'shared', completedAt);
+ }
+ expect(timing.take('shared', 'step_1')).toEqual({
+ toolPreparationDurationMs: 200,
+ toolExecutionDurationMs: 10,
+ });
+ expect(timing.take('shared', 'step_2')).toEqual({
+ toolPreparationDurationMs: 350,
+ toolExecutionDurationMs: 50,
+ });
+ });
+
+ it('does not manufacture execution duration on abort or an unobserved dispatch', () => {
+ const timing = createToolTimingTracker();
+ timing.observe({
+ id: 'step',
+ observed_at: 100,
+ delta: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'denied', index: 0, args: '{}' }],
+ },
+ });
+ expect(timing.take('denied', 'step')).toEqual({});
+ timing.dispatched({ dispatched_at: 500, toolCalls: [{ id: 'cancelled', stepId: 'step' }] });
+ expect(timing.take('cancelled', 'step')).toEqual({});
+ });
+});
diff --git a/packages/api/src/agents/toolTiming.ts b/packages/api/src/agents/toolTiming.ts
new file mode 100644
index 0000000000..c35c597e11
--- /dev/null
+++ b/packages/api/src/agents/toolTiming.ts
@@ -0,0 +1,284 @@
+import { StepEvents, getToolTimingDurations } from 'librechat-data-provider';
+import type { Agents } from 'librechat-data-provider';
+
+/** SDK handoff, not proof that the host or database started executing. */
+type DispatchedCall = { id: string; stepId?: string };
+type Dispatch = { dispatched_at: number; toolCalls: DispatchedCall[] };
+type Fragment = Pick<Agents.RunStepDeltaEvent, 'id' | 'delta' | 'observed_at'>;
+export type ToolPreparationMarker = Agents.ToolPreparationMarker;
+type StepTiming = {
+ firstByCall: Map<string, number>;
+ firstUnidentified?: number;
+ firstCallId?: string;
+ dispatchedByCall: Map<string, number>;
+ completedByCall: Map<string, number>;
+ pendingIds: Set<string>;
+};
+
+export type ToolTimingTracker = {
+ observe(fragment: Fragment): ToolPreparationMarker[];
+ prepare(marker: ToolPreparationMarker): void;
+ dispatched(event: Dispatch): void;
+ completed(stepId: string, callId: string, at?: number): void;
+ take(callId: string, stepId: string): ReturnType<typeof getToolTimingDurations>;
+};
+
+const validTime = (value: number | undefined): value is number =>
+ typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+/** One instance per response. Only bounded IDs and timestamps are retained. */
+type TimingEvent =
+ | { event: StepEvents.ON_TOOL_PREPARATION; data: ToolPreparationMarker }
+ | { event: StepEvents.ON_TOOL_CALLS_DISPATCHED; data: Agents.ToolCallsDispatchedEvent };
+
+type ToolCompletion = {
+ result?: { id?: string; completed_at?: number; tool_call?: { id?: string } };
+};
+
+type ChildTimingStamps = { observedAt?: number; dispatchedAt?: number };
+
+type ChildTimingAggregator = {
+ stepMap?: Map<string, { index: number }>;
+ contentParts?: Array<{
+ type?: string;
+ tool_call?: {
+ id?: string;
+ toolPreparationStartedAt?: number;
+ toolDispatchedAt?: number;
+ toolPreparationDurationMs?: number;
+ toolExecutionDurationMs?: number;
+ };
+ }>;
+};
+
+export type ToolTimingAdapter = {
+ dispatch: { handle(event: string, data: Agents.ToolCallsDispatchedEvent): Promise<void> };
+ delta(fragment: Fragment): Promise<void>;
+ completed(event: ToolCompletion): void;
+ close(toolCall: { id?: string }, stepId: string): void;
+ child(aggregator: ChildTimingAggregator, update: { phase?: string; data?: unknown }): void;
+};
+
+/** Owns timing event transitions; legacy Express only wires these handlers. */
+export function createToolTimingAdapter({
+ replayEvents,
+ emit,
+}: {
+ replayEvents?: readonly { event: string; data?: unknown }[];
+ emit(event: TimingEvent): Promise<void> | void;
+}): ToolTimingAdapter {
+ const tracker = createToolTimingTracker(replayEvents);
+ const childStamps = new WeakMap<ChildTimingAggregator, Map<string, ChildTimingStamps>>();
+ return {
+ dispatch: {
+ async handle(_event, data) {
+ tracker.dispatched(data);
+ await emit({ event: StepEvents.ON_TOOL_CALLS_DISPATCHED, data });
+ },
+ },
+ async delta(fragment) {
+ for (const marker of tracker.observe(fragment)) {
+ await emit({ event: StepEvents.ON_TOOL_PREPARATION, data: marker });
+ }
+ },
+ completed(event) {
+ const result = event?.result;
+ if (result?.id && result.tool_call?.id) {
+ tracker.completed(result.id, result.tool_call.id, result.completed_at);
+ }
+ },
+ close(toolCall, stepId) {
+ Object.assign(toolCall, tracker.take(toolCall.id ?? '', stepId));
+ },
+ child(aggregator, update) {
+ let stamps = childStamps.get(aggregator);
+ if (!stamps) {
+ stamps = new Map();
+ childStamps.set(aggregator, stamps);
+ }
+ applySubagentToolTiming(aggregator, update, stamps);
+ },
+ };
+}
+
+function applySubagentToolTiming(
+ aggregator: ChildTimingAggregator,
+ update: { phase?: string; data?: unknown },
+ stamps: Map<string, ChildTimingStamps>,
+): void {
+ if (
+ update.phase !== 'tool_preparation' &&
+ update.phase !== 'tool_calls_dispatched' &&
+ update.phase !== 'run_step_completed'
+ )
+ return;
+ if (update.data == null || typeof update.data !== 'object') return;
+ const data = update.data as {
+ id?: string;
+ toolCallId?: string;
+ observed_at?: number;
+ dispatched_at?: number;
+ toolCalls?: Array<{ id?: string; stepId?: string }>;
+ result?: { id?: string; completed_at?: number; tool_call?: { id?: string } };
+ };
+ const apply = (
+ stepId: string | undefined,
+ callId: string | undefined,
+ fn: (tool: {
+ id?: string;
+ toolPreparationStartedAt?: number;
+ toolDispatchedAt?: number;
+ toolPreparationDurationMs?: number;
+ toolExecutionDurationMs?: number;
+ }) => void,
+ ) => {
+ if (!stepId || !callId) return;
+ const index = aggregator.stepMap?.get(stepId)?.index;
+ const part = index == null ? undefined : aggregator.contentParts?.[index];
+ if (part?.type !== 'tool_call' || part.tool_call?.id !== callId) return;
+ fn(part.tool_call);
+ };
+ if (update.phase === 'tool_preparation' && validTime(data.observed_at)) {
+ if (!data.id || !data.toolCallId) return;
+ const key = `${data.id}\u0000${data.toolCallId}`;
+ const previous = stamps.get(key) ?? {};
+ const observedAt = Math.min(previous.observedAt ?? data.observed_at, data.observed_at);
+ stamps.set(key, { ...previous, observedAt });
+ apply(data.id, data.toolCallId, (tool) => {
+ tool.toolPreparationStartedAt = observedAt;
+ });
+ }
+ if (update.phase === 'tool_calls_dispatched' && validTime(data.dispatched_at)) {
+ for (const call of data.toolCalls ?? []) {
+ if (!call.stepId || !call.id) continue;
+ const key = `${call.stepId}\u0000${call.id}`;
+ const previous = stamps.get(key) ?? {};
+ const dispatchedAt = Math.min(
+ previous.dispatchedAt ?? data.dispatched_at!,
+ data.dispatched_at!,
+ );
+ stamps.set(key, { ...previous, dispatchedAt });
+ apply(call.stepId, call.id, (tool) => {
+ tool.toolDispatchedAt = dispatchedAt;
+ if (previous.observedAt != null) tool.toolPreparationStartedAt = previous.observedAt;
+ });
+ }
+ }
+ if (update.phase === 'run_step_completed' && validTime(data.result?.completed_at)) {
+ const stepId = data.result?.id;
+ const callId = data.result?.tool_call?.id;
+ if (!stepId || !callId) return;
+ const key = `${stepId}\u0000${callId}`;
+ const recorded = stamps.get(key);
+ apply(stepId, callId, (tool) => {
+ if (recorded?.dispatchedAt != null) tool.toolDispatchedAt = recorded.dispatchedAt;
+ if (recorded?.observedAt != null) tool.toolPreparationStartedAt = recorded.observedAt;
+ Object.assign(
+ tool,
+ getToolTimingDurations({
+ observedAt: tool.toolPreparationStartedAt,
+ dispatchedAt: tool.toolDispatchedAt,
+ completedAt: data.result?.completed_at,
+ }),
+ );
+ });
+ stamps.delete(key);
+ }
+}
+
+export function createToolTimingTracker(
+ replayEvents: readonly { event: string; data?: unknown }[] = [],
+): ToolTimingTracker {
+ const steps = new Map<string, StepTiming>();
+ const getStep = (id: string): StepTiming => {
+ let step = steps.get(id);
+ if (!step) {
+ step = {
+ firstByCall: new Map(),
+ dispatchedByCall: new Map(),
+ completedByCall: new Map(),
+ pendingIds: new Set(),
+ };
+ steps.set(id, step);
+ }
+ return step;
+ };
+ const prepare = ({ id, index, toolCallId, observed_at: at }: ToolPreparationMarker): void => {
+ if (!id || !validTime(at)) return;
+ const step = getStep(id);
+ if (toolCallId) {
+ step.firstByCall.set(toolCallId, Math.min(step.firstByCall.get(toolCallId) ?? at, at));
+ if (index === 0) step.firstCallId = toolCallId;
+ } else if (index === 0) {
+ step.firstUnidentified = Math.min(step.firstUnidentified ?? at, at);
+ if (step.firstCallId) {
+ const first = step.firstCallId;
+ step.firstByCall.set(first, Math.min(step.firstByCall.get(first) ?? at, at));
+ }
+ }
+ };
+
+ const tracker: ToolTimingTracker = {
+ observe({ id, delta, observed_at: at }: Fragment): ToolPreparationMarker[] {
+ if (!id || !validTime(at) || delta.type !== 'tool_calls') return [];
+ const markers: ToolPreparationMarker[] = [];
+ const step = getStep(id);
+ for (const chunk of delta.tool_calls ?? []) {
+ const index = typeof chunk.index === 'number' ? chunk.index : undefined;
+ const callId = typeof chunk.id === 'string' && chunk.id ? chunk.id : undefined;
+ if (!callId && (index !== 0 || delta.tool_calls?.length !== 1)) continue;
+ const prior = callId ? step.firstByCall.get(callId) : step.firstUnidentified;
+ const marker = { id, index, ...(callId && { toolCallId: callId }), observed_at: at };
+ prepare(marker);
+ if (prior == null) markers.push(marker);
+ }
+ return markers;
+ },
+ prepare,
+ dispatched({ dispatched_at: at, toolCalls }: Dispatch): void {
+ if (!validTime(at) || !Array.isArray(toolCalls)) return;
+ for (const call of toolCalls) {
+ if (!call.id || !call.stepId) continue;
+ const step = getStep(call.stepId);
+ step.pendingIds.add(call.id);
+ step.dispatchedByCall.set(call.id, Math.min(step.dispatchedByCall.get(call.id) ?? at, at));
+ }
+ },
+ completed(stepId: string, callId: string, at?: number): void {
+ if (stepId && callId && validTime(at)) getStep(stepId).completedByCall.set(callId, at);
+ },
+ take(callId: string, stepId: string): ReturnType<typeof getToolTimingDurations> {
+ const step = steps.get(stepId);
+ if (!step) return {};
+ const sole = step.pendingIds.size === 1 && step.pendingIds.has(callId);
+ const unidentified =
+ step.firstCallId === callId || (step.firstCallId == null && sole)
+ ? step.firstUnidentified
+ : undefined;
+ const start = Math.min(step.firstByCall.get(callId) ?? Infinity, unidentified ?? Infinity);
+ const duration = getToolTimingDurations({
+ observedAt: Number.isFinite(start) ? start : undefined,
+ dispatchedAt: step.dispatchedByCall.get(callId),
+ completedAt: step.completedByCall.get(callId),
+ });
+ step.firstByCall.delete(callId);
+ step.dispatchedByCall.delete(callId);
+ step.completedByCall.delete(callId);
+ step.pendingIds.delete(callId);
+ if (step.pendingIds.size === 0) steps.delete(stepId);
+ return duration;
+ },
+ };
+ for (const event of replayEvents) {
+ if (event.data == null || typeof event.data !== 'object') continue;
+ if (event.event === StepEvents.ON_TOOL_PREPARATION) {
+ const marker = event.data as Partial<ToolPreparationMarker>;
+ if (typeof marker.id === 'string' && typeof marker.observed_at === 'number') {
+ tracker.prepare(marker as ToolPreparationMarker);
+ }
+ } else if (event.event === StepEvents.ON_TOOL_CALLS_DISPATCHED) {
+ tracker.dispatched(event.data as Dispatch);
+ }
+ }
+ return tracker;
+}
diff --git a/packages/api/src/stream/GenerationJobManager.ts b/packages/api/src/stream/GenerationJobManager.ts
index a54ee838be..749db957be 100644
--- a/packages/api/src/stream/GenerationJobManager.ts
+++ b/packages/api/src/stream/GenerationJobManager.ts
@@ -4,6 +4,7 @@ import {
Constants,
ContentTypes,
StepTypes,
+ StepEvents,
UsageEvents,
ApprovalEvents,
SteerEvents,
@@ -443,10 +444,44 @@ function getReplayStepId(event: t.ServerSentEvent): unknown {
const result = 'result' in event.data ? event.data.result : undefined;
return result != null && typeof result === 'object' && 'id' in result ? result.id : undefined;
}
+ if (event.event === StepEvents.ON_TOOL_PREPARATION) {
+ const marker = event.data as { id?: unknown; toolCallId?: unknown; index?: unknown };
+ return typeof marker.id === 'string'
+ ? `${marker.id}:${typeof marker.toolCallId === 'string' ? marker.toolCallId : `#${marker.index}`}`
+ : undefined;
+ }
+ if (event.event === StepEvents.ON_TOOL_CALLS_DISPATCHED) {
+ const calls = (event.data as { toolCalls?: unknown }).toolCalls;
+ return Array.isArray(calls)
+ ? JSON.stringify(calls.map((call) => [call?.stepId, call?.id]))
+ : undefined;
+ }
return undefined;
}
+function isToolTimingReplayEvent(event: t.ServerSentEvent): boolean {
+ if (!('event' in event) || event.data == null || typeof event.data !== 'object') return false;
+ if (event.event === StepEvents.ON_TOOL_PREPARATION) {
+ const marker = event.data as { id?: unknown; observed_at?: unknown };
+ return (
+ typeof marker.id === 'string' &&
+ marker.id !== '' &&
+ typeof marker.observed_at === 'number' &&
+ Number.isFinite(marker.observed_at)
+ );
+ }
+ if (event.event === StepEvents.ON_TOOL_CALLS_DISPATCHED) {
+ const dispatch = event.data as { dispatched_at?: unknown; toolCalls?: unknown };
+ return (
+ typeof dispatch.dispatched_at === 'number' &&
+ Number.isFinite(dispatch.dispatched_at) &&
+ Array.isArray(dispatch.toolCalls)
+ );
+ }
+ return false;
+}
+
function isOAuthReplayEvent(event: t.ServerSentEvent): boolean {
if (!('event' in event) || !event.data || typeof event.data !== 'object') {
return false;
@@ -7468,6 +7503,9 @@ class GenerationJobManagerClass {
if (event.event === UsageEvents.ON_TOKEN_USAGE) {
return this.trackTokenUsage(streamId, event, expectedCreatedAt);
}
+ if (isToolTimingReplayEvent(event)) {
+ return this.trackReplayEvent(streamId, event, expectedCreatedAt);
+ }
if (
(event.event === 'on_run_step' ||
event.event === 'on_run_step_delta' ||
@@ -7758,7 +7796,7 @@ class GenerationJobManagerClass {
event: t.ServerSentEvent,
expectedCreatedAt: number,
): Promise<void> {
- if (!isOAuthReplayEvent(event)) {
+ if (!isOAuthReplayEvent(event) && !isToolTimingReplayEvent(event)) {
return;
}
diff --git a/packages/api/src/stream/__tests__/GenerationJobManager.resumeReplay.spec.ts b/packages/api/src/stream/__tests__/GenerationJobManager.resumeReplay.spec.ts
index 7e67fec122..5456045ebb 100644
--- a/packages/api/src/stream/__tests__/GenerationJobManager.resumeReplay.spec.ts
+++ b/packages/api/src/stream/__tests__/GenerationJobManager.resumeReplay.spec.ts
@@ -1,9 +1,11 @@
+import { StepEvents } from 'librechat-data-provider';
import type { StandardGraph } from '@librechat/agents';
import type { Agents } from 'librechat-data-provider';
import type { ServerSentEvent } from '~/types';
import { InMemoryEventTransport } from '~/stream/implementations/InMemoryEventTransport';
import { InMemoryJobStore } from '~/stream/implementations/InMemoryJobStore';
import { GenerationJobManagerClass } from '~/stream/GenerationJobManager';
+import { createToolTimingTracker } from '~/agents/toolTiming';
jest.spyOn(console, 'log').mockImplementation();
@@ -83,6 +85,46 @@ describe('GenerationJobManager resume replay events', () => {
});
});
+ test('replays bounded first-fragment and dispatch evidence without tool arguments', async () => {
+ manager = createInMemoryManager();
+ const streamId = `tool-timing-resume-${Date.now()}`;
+ await manager.createJob(streamId, 'user-1', streamId);
+ const first = {
+ event: StepEvents.ON_TOOL_PREPARATION,
+ data: {
+ id: 'step-1',
+ index: 0,
+ observed_at: 100,
+ },
+ };
+ const named = {
+ event: StepEvents.ON_TOOL_PREPARATION,
+ data: {
+ id: 'step-1',
+ index: 0,
+ toolCallId: 'call-1',
+ observed_at: 200,
+ },
+ };
+ const dispatched = {
+ event: StepEvents.ON_TOOL_CALLS_DISPATCHED,
+ data: {
+ dispatched_at: 500,
+ toolCalls: [{ id: 'call-1', name: 'query', stepId: 'step-1' }],
+ },
+ };
+ for (const event of [first, named, dispatched, named]) await manager.emitChunk(streamId, event);
+ const state = await manager.getResumeState(streamId);
+ expect(state?.replayEvents).toEqual([first, named, dispatched]);
+ expect(JSON.stringify(state?.replayEvents)).not.toContain('args');
+ const rebuilt = createToolTimingTracker(state?.replayEvents ?? []);
+ rebuilt.completed('step-1', 'call-1', 560);
+ expect(rebuilt.take('call-1', 'step-1')).toEqual({
+ toolPreparationDurationMs: 400,
+ toolExecutionDurationMs: 60,
+ });
+ });
+
test('includes OAuth run step and delta replay events in resume state', async () => {
manager = createInMemoryManager();
const streamId = `oauth-delta-resume-${Date.now()}`;
diff --git a/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts b/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts
index df15322b64..30068cea15 100644
--- a/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts
+++ b/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts
@@ -1971,6 +1971,95 @@ describe('RedisJobStore Integration Tests', () => {
await store.destroy();
});
+ test('reconstructs split tool timings and close metadata across instances', async () => {
+ if (!ioredisClient) return;
+ const { RedisJobStore } = await import('../implementations/RedisJobStore');
+ const producer = new RedisJobStore(ioredisClient);
+ const consumer = new RedisJobStore(ioredisClient);
+ await producer.initialize();
+ await consumer.initialize();
+ const streamId = `tool-timing-recon-${Date.now()}`;
+ const job = await producer.createJob(streamId, 'user-1', streamId);
+ const events = [
+ {
+ event: 'on_run_step',
+ data: {
+ id: 'step-1',
+ runId: 'response-1',
+ index: 0,
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-1', name: 'lookup', args: '{}' }],
+ },
+ },
+ },
+ {
+ event: 'on_run_step_delta',
+ data: {
+ id: 'step-1',
+ observed_at: 1_000,
+ delta: { type: 'tool_calls', tool_calls: [{ id: 'call-1', index: 0, args: '{' }] },
+ },
+ },
+ {
+ event: 'on_tool_preparation',
+ data: {
+ id: 'step-1',
+ toolCallId: 'call-1',
+ index: 0,
+ observed_at: 1_000,
+ },
+ },
+ {
+ event: 'on_tool_calls_dispatched',
+ data: {
+ dispatched_at: 248_000,
+ toolCalls: [{ id: 'call-1', name: 'lookup', stepId: 'step-1' }],
+ },
+ },
+ {
+ event: 'on_run_step_completed',
+ data: {
+ result: {
+ id: 'step-1',
+ index: 0,
+ type: 'tool_call',
+ completed_at: 248_340,
+ tool_call: { id: 'call-1', name: 'lookup', args: '{}', output: 'done', progress: 1 },
+ },
+ },
+ },
+ {
+ event: 'on_run_step_closed',
+ data: {
+ id: 'step-1',
+ type: 'tool_calls',
+ index: 0,
+ status: 'completed',
+ created_at: 1_000,
+ closed_at: 248_340,
+ },
+ },
+ ];
+ for (const event of events) {
+ await producer.appendChunk(streamId, event);
+ }
+ const result = await consumer.getContentParts(streamId, job.createdAt, { durableOnly: true });
+ expect(result?.content[0]).toMatchObject({
+ type: 'tool_call',
+ tool_call: {
+ id: 'call-1',
+ runStepStatus: 'completed',
+ runStepClosedAt: 248_340,
+ runStepDurationMs: 247_340,
+ toolPreparationDurationMs: 247_000,
+ toolExecutionDurationMs: 340,
+ },
+ });
+ await producer.destroy();
+ await consumer.destroy();
+ });
+
test('should share run steps between instances', async () => {
if (!ioredisClient) {
return;
diff --git a/packages/api/src/stream/__tests__/RedisJobStore.toolTiming.spec.ts b/packages/api/src/stream/__tests__/RedisJobStore.toolTiming.spec.ts
new file mode 100644
index 0000000000..d867c190fc
--- /dev/null
+++ b/packages/api/src/stream/__tests__/RedisJobStore.toolTiming.spec.ts
@@ -0,0 +1,90 @@
+import { RedisJobStore } from '../implementations/RedisJobStore';
+
+/** Exercise the actual reconstruction method against a durable chunk snapshot, not a live host cache. */
+describe('RedisJobStore tool timing reconstruction', () => {
+ it('restores preparation, SDK handoff, result time, and the upstream close stamp', async () => {
+ const chunks = [
+ {
+ event: 'on_run_step',
+ data: {
+ id: 'step-1',
+ index: 0,
+ runId: 'response-1',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-1', name: 'lookup', args: '{}' }],
+ },
+ },
+ },
+ {
+ event: 'on_run_step_delta',
+ data: {
+ id: 'step-1',
+ observed_at: 1_000,
+ delta: { type: 'tool_calls', tool_calls: [{ id: 'call-1', index: 0, args: '{' }] },
+ },
+ },
+ {
+ event: 'on_tool_preparation',
+ data: {
+ id: 'step-1',
+ toolCallId: 'call-1',
+ index: 0,
+ observed_at: 1_000,
+ },
+ },
+ {
+ event: 'on_tool_calls_dispatched',
+ data: {
+ dispatched_at: 248_000,
+ toolCalls: [{ id: 'call-1', name: 'lookup', stepId: 'step-1' }],
+ },
+ },
+ {
+ event: 'on_run_step_completed',
+ data: {
+ result: {
+ id: 'step-1',
+ index: 0,
+ type: 'tool_call',
+ completed_at: 248_340,
+ tool_call: { id: 'call-1', name: 'lookup', args: '{}', output: 'done', progress: 1 },
+ },
+ },
+ },
+ {
+ event: 'on_run_step_closed',
+ data: {
+ id: 'step-1',
+ type: 'tool_calls',
+ index: 0,
+ status: 'completed',
+ created_at: 1_000,
+ closed_at: 248_340,
+ },
+ },
+ ];
+ const store = Object.create(RedisJobStore.prototype) as RedisJobStore;
+ const snapshot = jest.fn(async () => ({ chunks, durableEventCount: chunks.length }));
+ Object.defineProperty(store, 'getChunkSnapshot', { value: snapshot });
+ const result = await store.getContentParts('tool-run', undefined, { durableOnly: true });
+ expect(snapshot).toHaveBeenCalledWith('tool-run', undefined, true);
+ expect(result).toMatchObject({
+ reconstructedEventCount: chunks.length,
+ durableEventCount: chunks.length,
+ content: [
+ {
+ type: 'tool_call',
+ tool_call: {
+ id: 'call-1',
+ runStepStatus: 'completed',
+ runStepClosedAt: 248_340,
+ runStepDurationMs: 247_340,
+ toolPreparationDurationMs: 247_000,
+ toolExecutionDurationMs: 340,
+ },
+ },
+ ],
+ });
+ });
+});
diff --git a/packages/api/src/stream/implementations/RedisJobStore.ts b/packages/api/src/stream/implementations/RedisJobStore.ts
index c616170e57..4d1f74db77 100644
--- a/packages/api/src/stream/implementations/RedisJobStore.ts
+++ b/packages/api/src/stream/implementations/RedisJobStore.ts
@@ -2,6 +2,7 @@ import { logger } from '@librechat/data-schemas';
import { createContentAggregator } from '@librechat/agents';
import {
ContentTypes,
+ StepEvents,
getRunStepDurationMs,
getRunStepCloseMetadata,
} from 'librechat-data-provider';
@@ -53,6 +54,7 @@ import {
import { instrumentIORedisClient, RedisUseCases } from '~/cache/redisTelemetry';
import { RecoveredSteerPayloadMismatchError } from '~/stream/SteerRecovery';
import { createCheckpointNamespace } from '~/stream/checkpoints';
+import { createToolTimingTracker } from '~/agents/toolTiming';
import { evalScript } from '~/cache/redisScript';
const CLIENT_REQUEST_ID_PATTERN = /^[A-Za-z0-9:_-]{1,128}$/;
@@ -4120,6 +4122,7 @@ export class RedisJobStore implements IJobStoreV2 {
// Use the same content aggregator as live streaming
const { contentParts, aggregateContent } = createContentAggregator();
+ const toolTiming = createToolTimingTracker();
// Step ID -> content index, rebuilt from the replayed `on_run_step`
// payloads. Those carry the index the offset wrappers shifted, whereas a
@@ -4233,6 +4236,24 @@ export class RedisJobStore implements IJobStoreV2 {
continue;
}
+ if (event.event === StepEvents.ON_TOOL_PREPARATION) {
+ toolTiming.prepare(event.data as Agents.ToolPreparationMarker);
+ continue;
+ }
+ if (event.event === StepEvents.ON_TOOL_CALLS_DISPATCHED) {
+ toolTiming.dispatched(event.data as Agents.ToolCallsDispatchedEvent);
+ continue;
+ }
+ if (event.event === StepEvents.ON_RUN_STEP_DELTA) {
+ toolTiming.observe(event.data as Agents.RunStepDeltaEvent);
+ }
+ if (event.event === StepEvents.ON_RUN_STEP_COMPLETED) {
+ const completion = (event.data as { result?: Agents.ToolEndEvent }).result;
+ if (completion?.tool_call?.id) {
+ toolTiming.completed(completion.id, completion.tool_call.id, completion.completed_at);
+ }
+ }
+
// Step closures are host-authored like steers and labels: the SDK
// aggregator has no notion of the event, so the terminal status is
// stamped onto the part the replayed steps already rebuilt. Resolved by
@@ -4250,6 +4271,7 @@ export class RedisJobStore implements IJobStoreV2 {
const part = index != null ? contentParts[index] : undefined;
if (closed.status && part?.type === ContentTypes.TOOL_CALL && part.tool_call) {
part.tool_call.runStepStatus = closed.status;
+ Object.assign(part.tool_call, toolTiming.take(part.tool_call.id ?? '', closed.id ?? ''));
Object.assign(part.tool_call, getRunStepCloseMetadata(closed));
const durationMs = getRunStepDurationMs(closed);
if (durationMs != null) {
diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.ts
index 92cb7a6cc8..e8e8e3f3d3 100644
--- a/packages/data-provider/src/index.ts
+++ b/packages/data-provider/src/index.ts
@@ -13,6 +13,7 @@ export * from './messages';
export * from './errors';
/* run steps */
export * from './runSteps';
+export * from './toolTiming';
/* artifacts */
export * from './artifacts';
/* schema helpers */
diff --git a/packages/data-provider/src/toolTiming.spec.ts b/packages/data-provider/src/toolTiming.spec.ts
new file mode 100644
index 0000000000..23cdb26181
--- /dev/null
+++ b/packages/data-provider/src/toolTiming.spec.ts
@@ -0,0 +1,31 @@
+import { getToolTimingDurations } from './toolTiming';
+
+describe('getToolTimingDurations', () => {
+ it('separates minutes of argument preparation from a fast tool result', () => {
+ expect(
+ getToolTimingDurations({ observedAt: 1_000, dispatchedAt: 248_000, completedAt: 248_340 }),
+ ).toEqual({ toolPreparationDurationMs: 247_000, toolExecutionDurationMs: 340 });
+ });
+
+ it('omits unknown phases independently rather than inventing a start', () => {
+ expect(getToolTimingDurations({ dispatchedAt: 10_000, completedAt: 11_000 })).toEqual({
+ toolExecutionDurationMs: 1_000,
+ });
+ expect(getToolTimingDurations({ observedAt: 1_000, completedAt: 11_000 })).toEqual({});
+ expect(getToolTimingDurations({ observedAt: 1_000, dispatchedAt: 10_000 })).toEqual({
+ toolPreparationDurationMs: 9_000,
+ });
+ });
+
+ it('does not mislabel a reordered or non-finite clock pair', () => {
+ expect(
+ getToolTimingDurations({ observedAt: 12_000, dispatchedAt: 10_000, completedAt: 11_000 }),
+ ).toEqual({ toolExecutionDurationMs: 1_000 });
+ expect(
+ getToolTimingDurations({ observedAt: 1_000, dispatchedAt: 10_000, completedAt: 9_000 }),
+ ).toEqual({ toolPreparationDurationMs: 9_000 });
+ expect(
+ getToolTimingDurations({ observedAt: NaN, dispatchedAt: Infinity, completedAt: 12_000 }),
+ ).toEqual({});
+ });
+});
diff --git a/packages/data-provider/src/toolTiming.ts b/packages/data-provider/src/toolTiming.ts
new file mode 100644
index 0000000000..3a42cd68fa
--- /dev/null
+++ b/packages/data-provider/src/toolTiming.ts
@@ -0,0 +1,29 @@
+/** Wall-clock phases of one tool call, never batch or database execution time. */
+export type ToolTimingStamps = {
+ observedAt?: number;
+ dispatchedAt?: number;
+ completedAt?: number;
+};
+
+const validTime = (value: number | undefined): value is number =>
+ typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+/** Omit an interval rather than presenting clock skew or a missing stamp as measured time. */
+export function getToolTimingDurations({
+ observedAt,
+ dispatchedAt,
+ completedAt,
+}: ToolTimingStamps): {
+ toolPreparationDurationMs?: number;
+ toolExecutionDurationMs?: number;
+} {
+ if (!validTime(dispatchedAt)) return {};
+ return {
+ ...(validTime(observedAt) && observedAt <= dispatchedAt
+ ? { toolPreparationDurationMs: dispatchedAt - observedAt }
+ : {}),
+ ...(validTime(completedAt) && dispatchedAt <= completedAt
+ ? { toolExecutionDurationMs: completedAt - dispatchedAt }
+ : {}),
+ };
+}
diff --git a/packages/data-provider/src/types/agents.ts b/packages/data-provider/src/types/agents.ts
index 98f9591cb6..aa88059fb0 100644
--- a/packages/data-provider/src/types/agents.ts
+++ b/packages/data-provider/src/types/agents.ts
@@ -137,6 +137,7 @@ export namespace Agents {
export type ToolEndEvent = {
/** The Step Id of the Tool Call */
id: string;
+ completed_at?: number;
/** The Completed Tool Call */
tool_call?: ToolCall;
/** The content index of the tool call */
@@ -258,6 +259,19 @@ export namespace Agents {
* because the caller aborted — which is the only signal that distinguishes
* a stopped step from one still in flight.
*/
+ export type ToolPreparationMarker = {
+ id: string;
+ index?: number;
+ toolCallId?: string;
+ observed_at: number;
+ };
+
+ export type ToolCallsDispatchedEvent = {
+ dispatched_at: number;
+ runId?: string;
+ toolCalls: Array<{ id: string; name: string; stepId?: string }>;
+ };
+
export type RunStepClosedEvent = {
id: string;
index: number;
@@ -361,6 +375,8 @@ export namespace Agents {
* The delta containing the fields that have changed on the run step.
*/
delta: ToolCallDelta;
+ /** SDK receipt timestamp before awaited step dispatch, when available. */
+ observed_at?: number;
}
export type StepDetails = MessageCreationDetails | ToolCallsDetails;
export type MessageCreationDetails = {
diff --git a/packages/data-provider/src/types/content.ts b/packages/data-provider/src/types/content.ts
index d751a15afd..e0d3cce1bd 100644
--- a/packages/data-provider/src/types/content.ts
+++ b/packages/data-provider/src/types/content.ts
@@ -162,6 +162,14 @@ export type PartMetadata = {
runStepDurationMs?: number;
/** Host-reported close time in epoch milliseconds, when valid. Absent on older content. */
runStepClosedAt?: number;
+ /** First observed argument fragment, while this tool call is still being prepared. */
+ toolPreparationStartedAt?: number;
+ /** SDK handoff to direct invocation or host dispatch, not the MCP round trip. */
+ toolDispatchedAt?: number;
+ /** Time from the first observed argument fragment to SDK handoff, if both are known. */
+ toolPreparationDurationMs?: number;
+ /** Time from SDK handoff to this call's result, not database execution time. */
+ toolExecutionDurationMs?: number;
/**
* Stamped by the background harvester when a detached task's final output
* replaces the dispatch handle in `tool_call.output`. The handle JSON and
diff --git a/packages/data-provider/src/types/runs.ts b/packages/data-provider/src/types/runs.ts
index 45a5b2ac82..8cebf418bc 100644
--- a/packages/data-provider/src/types/runs.ts
+++ b/packages/data-provider/src/types/runs.ts
@@ -38,6 +38,10 @@ export enum StepEvents {
ON_MESSAGE_DELTA = 'on_message_delta',
ON_REASONING_DELTA = 'on_reasoning_delta',
ON_RUN_STEP_DELTA = 'on_run_step_delta',
+ /** SDK handoff from generated arguments to host or direct tool execution. */
+ ON_TOOL_CALLS_DISPATCHED = 'on_tool_calls_dispatched',
+ /** Compact first-fragment marker, retained for resumable generations. */
+ ON_TOOL_PREPARATION = 'on_tool_preparation',
ON_RUN_STEP_COMPLETED = 'on_run_step_completed',
/** Terminal signal for a run step: closed with a status and timestamps. */
ON_RUN_STEP_CLOSED = 'on_run_step_closed',
@@ -539,6 +543,8 @@ export type SubagentUpdatePhase =
| 'start'
| 'run_step'
| 'run_step_delta'
+ | 'tool_preparation'
+ | 'tool_calls_dispatched'
| 'run_step_completed'
| 'run_step_closed'
| 'message_delta'
diff --git a/packages/data-provider/src/types/subagents.ts b/packages/data-provider/src/types/subagents.ts
index 1199a6b2dd..86fa532640 100644
--- a/packages/data-provider/src/types/subagents.ts
+++ b/packages/data-provider/src/types/subagents.ts
@@ -79,6 +79,10 @@ export type SubagentActivityItem =
input?: string;
output?: string;
status: 'running' | 'completed' | 'failed' | 'cancelled';
+ toolPreparationStartedAt?: number;
+ toolDispatchedAt?: number;
+ toolPreparationDurationMs?: number;
+ toolExecutionDurationMs?: number;
inputValidationError?: true;
inputTruncated?: boolean;
outputTruncated?: boolean;