@librechat/agents 3.4.5 → 3.4.7

package/dist/esm/utils/handlers.mjs

@@ -36,6 +36,9 @@ function createHandlers(callbacks) {
 				});
 				callbacks?.onRunStepDelta?.(event, data);
 			} },
+			["on_run_step_closed"]: { handle: (event, data) => {
+				callbacks?.onRunStepClosed?.(event, data);
+			} },
 			["on_message_delta"]: { handle: (event, data) => {
 				aggregateContent({
 					event,

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

@@ -1 +1 @@
-{"version":3,"file":"handlers.mjs","names":[],"sources":["../../../src/utils/handlers.ts"],"sourcesContent":["/**\n * Multi-Agent Handler Utilities\n *\n * Provides a simple helper to create handlers with content aggregation for multi-agent scripts.\n *\n * Usage:\n * ```typescript\n * const { contentParts, aggregateContent, handlers } = createHandlers();\n *\n * // With callbacks\n * const { contentParts, aggregateContent, handlers } = createHandlers({\n *   onRunStep: (event, data) => console.log('Step:', data),\n *   onRunStepCompleted: (event, data) => console.log('Completed:', data)\n * });\n * ```\n */\n\nimport type * as t from '@/types';\nimport { ChatModelStreamHandler, createContentAggregator } from '@/stream';\nimport { ToolEndHandler, ModelEndHandler } from '@/events';\nimport { GraphEvents } from '@/common';\n\ninterface HandlerCallbacks {\n  onRunStep?: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData) => void;\n  onRunStepCompleted?: (\n    event: GraphEvents.ON_RUN_STEP_COMPLETED,\n    data: t.StreamEventData\n  ) => void;\n  onRunStepDelta?: (\n    event: GraphEvents.ON_RUN_STEP_DELTA,\n    data: t.StreamEventData\n  ) => void;\n  onMessageDelta?: (\n    event: GraphEvents.ON_MESSAGE_DELTA,\n    data: t.StreamEventData\n  ) => void;\n}\n\n/**\n * Creates handlers with content aggregation for multi-agent scripts\n */\nexport function createHandlers(callbacks?: HandlerCallbacks): {\n  contentParts: Array<t.MessageContentComplex | undefined>;\n  aggregateContent: ReturnType<\n    typeof createContentAggregator\n  >['aggregateContent'];\n  handlers: Record<string, t.EventHandler>;\n} {\n  // Set up content aggregator\n  const { contentParts, aggregateContent } = createContentAggregator();\n\n  // Create the handlers object\n  const handlers = {\n    [GraphEvents.TOOL_END]: new ToolEndHandler(),\n    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),\n    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),\n\n    [GraphEvents.ON_RUN_STEP]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.RunStep });\n        callbacks?.onRunStep?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_COMPLETED]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_COMPLETED,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({\n          event,\n          data: data as unknown as { result: t.ToolEndEvent },\n        });\n        callbacks?.onRunStepCompleted?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_DELTA]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_DELTA,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.RunStepDeltaEvent });\n        callbacks?.onRunStepDelta?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_MESSAGE_DELTA]: {\n      handle: (\n        event: GraphEvents.ON_MESSAGE_DELTA,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.MessageDeltaEvent });\n        callbacks?.onMessageDelta?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_SUMMARIZE_DELTA]: {\n      handle: (event: string, data: t.StreamEventData): void => {\n        aggregateContent({\n          event: event as GraphEvents,\n          data: data as t.SummarizeDeltaData,\n        });\n      },\n    },\n\n    [GraphEvents.ON_SUMMARIZE_COMPLETE]: {\n      handle: (event: string, data: t.StreamEventData): void => {\n        aggregateContent({\n          event: event as GraphEvents,\n          data: data as t.SummarizeCompleteEvent,\n        });\n      },\n    },\n  };\n\n  return {\n    contentParts,\n    aggregateContent,\n    handlers,\n  };\n}\n"],"mappings":";;;;;;;;AAyCA,SAAgB,eAAe,WAM7B;CAEA,MAAM,EAAE,cAAc,qBAAqB,wBAAwB;CAsEnE,OAAO;EACL;EACA;EACA,UAAA;oBArEwB,IAAI,eAAe;0BACb,IAAI,gBAAgB;6BACjB,IAAI,uBAAuB;oBAEjC,EACzB,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAAkB,CAAC;IACnD,WAAW,YAAY,OAAO,IAAI;GACpC,EACF;8BAEqC,EACnC,SACE,OACA,SACS;IACT,iBAAiB;KACf;KACM;IACR,CAAC;IACD,WAAW,qBAAqB,OAAO,IAAI;GAC7C,EACF;0BAEiC,EAC/B,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAA4B,CAAC;IAC7D,WAAW,iBAAiB,OAAO,IAAI;GACzC,EACF;yBAEgC,EAC9B,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAA4B,CAAC;IAC7D,WAAW,iBAAiB,OAAO,IAAI;GACzC,EACF;2BAEkC,EAChC,SAAS,OAAe,SAAkC;IACxD,iBAAiB;KACR;KACD;IACR,CAAC;GACH,EACF;8BAEqC,EACnC,SAAS,OAAe,SAAkC;IACxD,iBAAiB;KACR;KACD;IACR,CAAC;GACH,EACF;EAMO;CACT;AACF"}
+{"version":3,"file":"handlers.mjs","names":[],"sources":["../../../src/utils/handlers.ts"],"sourcesContent":["/**\n * Multi-Agent Handler Utilities\n *\n * Provides a simple helper to create handlers with content aggregation for multi-agent scripts.\n *\n * Usage:\n * ```typescript\n * const { contentParts, aggregateContent, handlers } = createHandlers();\n *\n * // With callbacks\n * const { contentParts, aggregateContent, handlers } = createHandlers({\n *   onRunStep: (event, data) => console.log('Step:', data),\n *   onRunStepCompleted: (event, data) => console.log('Completed:', data)\n * });\n * ```\n */\n\nimport type * as t from '@/types';\nimport { ChatModelStreamHandler, createContentAggregator } from '@/stream';\nimport { ToolEndHandler, ModelEndHandler } from '@/events';\nimport { GraphEvents } from '@/common';\n\ninterface HandlerCallbacks {\n  onRunStep?: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData) => void;\n  onRunStepCompleted?: (\n    event: GraphEvents.ON_RUN_STEP_COMPLETED,\n    data: t.StreamEventData\n  ) => void;\n  onRunStepDelta?: (\n    event: GraphEvents.ON_RUN_STEP_DELTA,\n    data: t.StreamEventData\n  ) => void;\n  onRunStepClosed?: (\n    event: GraphEvents.ON_RUN_STEP_CLOSED,\n    data: t.RunStepClosedEvent\n  ) => void;\n  onMessageDelta?: (\n    event: GraphEvents.ON_MESSAGE_DELTA,\n    data: t.StreamEventData\n  ) => void;\n}\n\n/**\n * Creates handlers with content aggregation for multi-agent scripts\n */\nexport function createHandlers(callbacks?: HandlerCallbacks): {\n  contentParts: Array<t.MessageContentComplex | undefined>;\n  aggregateContent: ReturnType<\n    typeof createContentAggregator\n  >['aggregateContent'];\n  handlers: Record<string, t.EventHandler>;\n} {\n  // Set up content aggregator\n  const { contentParts, aggregateContent } = createContentAggregator();\n\n  // Create the handlers object\n  const handlers = {\n    [GraphEvents.TOOL_END]: new ToolEndHandler(),\n    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),\n    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),\n\n    [GraphEvents.ON_RUN_STEP]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.RunStep });\n        callbacks?.onRunStep?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_COMPLETED]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_COMPLETED,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({\n          event,\n          data: data as unknown as { result: t.ToolEndEvent },\n        });\n        callbacks?.onRunStepCompleted?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_DELTA]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_DELTA,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.RunStepDeltaEvent });\n        callbacks?.onRunStepDelta?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_CLOSED]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_CLOSED,\n        data: t.StreamEventData\n      ): void => {\n        callbacks?.onRunStepClosed?.(event, data as t.RunStepClosedEvent);\n      },\n    },\n\n    [GraphEvents.ON_MESSAGE_DELTA]: {\n      handle: (\n        event: GraphEvents.ON_MESSAGE_DELTA,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.MessageDeltaEvent });\n        callbacks?.onMessageDelta?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_SUMMARIZE_DELTA]: {\n      handle: (event: string, data: t.StreamEventData): void => {\n        aggregateContent({\n          event: event as GraphEvents,\n          data: data as t.SummarizeDeltaData,\n        });\n      },\n    },\n\n    [GraphEvents.ON_SUMMARIZE_COMPLETE]: {\n      handle: (event: string, data: t.StreamEventData): void => {\n        aggregateContent({\n          event: event as GraphEvents,\n          data: data as t.SummarizeCompleteEvent,\n        });\n      },\n    },\n  };\n\n  return {\n    contentParts,\n    aggregateContent,\n    handlers,\n  };\n}\n"],"mappings":";;;;;;;;AA6CA,SAAgB,eAAe,WAM7B;CAEA,MAAM,EAAE,cAAc,qBAAqB,wBAAwB;CA+EnE,OAAO;EACL;EACA;EACA,UAAA;oBA9EwB,IAAI,eAAe;0BACb,IAAI,gBAAgB;6BACjB,IAAI,uBAAuB;oBAEjC,EACzB,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAAkB,CAAC;IACnD,WAAW,YAAY,OAAO,IAAI;GACpC,EACF;8BAEqC,EACnC,SACE,OACA,SACS;IACT,iBAAiB;KACf;KACM;IACR,CAAC;IACD,WAAW,qBAAqB,OAAO,IAAI;GAC7C,EACF;0BAEiC,EAC/B,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAA4B,CAAC;IAC7D,WAAW,iBAAiB,OAAO,IAAI;GACzC,EACF;2BAEkC,EAChC,SACE,OACA,SACS;IACT,WAAW,kBAAkB,OAAO,IAA4B;GAClE,EACF;yBAEgC,EAC9B,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAA4B,CAAC;IAC7D,WAAW,iBAAiB,OAAO,IAAI;GACzC,EACF;2BAEkC,EAChC,SAAS,OAAe,SAAkC;IACxD,iBAAiB;KACR;KACD;IACR,CAAC;GACH,EACF;8BAEqC,EACnC,SAAS,OAAe,SAAkC;IACxD,iBAAiB;KACR;KACD;IACR,CAAC;GACH,EACF;EAMO;CACT;AACF"}

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

@@ -13,6 +13,8 @@ export declare enum GraphEvents {
     ON_RUN_STEP_DELTA = "on_run_step_delta",
     /** [Custom] Completed event for run steps (tool calls) */
     ON_RUN_STEP_COMPLETED = "on_run_step_completed",
+    /** [Custom] Terminal signal for a run step: closed with status + timestamps */
+    ON_RUN_STEP_CLOSED = "on_run_step_closed",
     /** [Custom] Delta events for messages */
     ON_MESSAGE_DELTA = "on_message_delta",
     /** [Custom] Reasoning Delta events for messages */

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

@@ -45,6 +45,17 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     stepKeyIds: Map<string, string[]>;
     contentIndexMap: Map<string, number>;
     toolCallStepIds: Map<string, string>;
+    /** Step ID -> tool call IDs whose completions have not yet arrived. */
+    pendingToolCallsByStep: Map<string, Set<string>>;
+    /**
+     * Step ID -> latest producer completion time seen for that step. Parallel
+     * calls sharing a step can settle out of producer order when their host
+     * handlers differ in latency, so the call that happens to drain the set is
+     * not necessarily the one that finished last.
+     */
+    latestCompletionByStep: Map<string, number>;
+    /** Agent key ('' for single-agent) -> currently open MESSAGE_CREATION step ID. */
+    openMessageStepByAgent: Map<string, string>;
     /**
      * Step IDs dispatched through the handler registry during this run.
      * Event echo suppression is tracked separately so repeated deltas for
@@ -153,6 +164,16 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     clearHeavyState(): void;
     getEagerEventToolUsageCount(agentId?: string): Map<string, number>;
     protected clearEagerEventToolUsageCounts(): void;
+    /**
+     * Tracks a tool call whose completion must arrive before its step can be
+     * considered finished. Registered wherever `toolCallStepIds` gains entries,
+     * except cross-process subagent resume restoration, where pending state
+     * cannot be faithfully rebuilt and closes fall back to completions/sweep.
+     */
+    registerPendingToolCall(toolCallId: string, stepId: string): void;
+    /** Lazily creates a step's pending-completions set; callers registering a
+     *  batch hoist this lookup out of their per-call loop. */
+    protected getPendingToolCallSet(stepId: string): Set<string>;
     markHandlerDispatchedEvent(eventName: string, stepId: string): () => void;
     hasHandlerDispatchedEvent(eventName: string, stepId: string): boolean;
     /**
@@ -415,6 +436,72 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     releasePreemptSeal(): void;
     getPreemptStats(): t.PreemptStats;
     getRunStep(stepId: string): t.RunStep | undefined;
+    /**
+     * Derives the same lane key `dispatchRunStep` stamps as `runStep.agentId`.
+     * The multi-agent check gates the lookup because `getAgentContext` signals
+     * a miss by throwing: single-agent graphs key every step under `''`, so
+     * resolving the context could only ever produce a thrown-and-discarded
+     * Error on a per-model-call path.
+     */
+    protected getStepAgentKey(metadata?: Record<string, unknown>): string;
+    /**
+     * O(1) reverse lookup: both dispatch funnels key the open-message map by
+     * `runStep.agentId ?? ''`, so the entry is addressable without scanning.
+     */
+    private untrackRunStep;
+    /**
+     * Shared step accounting for both dispatch funnels: a successor step in
+     * the same agent lane marks the previous message step as finished — its
+     * CLOSED event must precede the successor's ON_RUN_STEP so hosts observe
+     * a consistent open-step timeline — then the step is registered in the
+     * content maps and tracked as the lane's open message step when
+     * applicable.
+     */
+    protected trackDispatchedRunStep(runStep: t.RunStep, metadata?: Record<string, unknown>, 
+    /**
+     * Summarization steps are typed MESSAGE_CREATION but own an explicit
+     * completion, and their model call emits `CHAT_MODEL_END` well before the
+     * summary is assembled. Tracking one as the lane's open step would let
+     * model-end publish an authoritative `completed` closure early — the
+     * measured duration would exclude the remaining work and a later
+     * post-model failure could no longer change the status. They close
+     * through `recordStepCompletion` instead.
+     */
+    trackAsOpenMessageStep?: boolean): Promise<void>;
+    /**
+     * Closes a run step: stamps its terminal status + timestamp on the stored
+     * `RunStep` and emits `ON_RUN_STEP_CLOSED`. First close wins — later calls
+     * are no-ops — except a `restamp` close, which lets a `completed`
+     * TOOL_CALLS step refresh `completed_at` when a late-registered parallel
+     * tool call finishes after the step already closed (the eager-execution
+     * race). `cancelled`/`failed` are immutable once stamped.
+     */
+    closeRunStep(stepId: string, status: Exclude<t.RunStepStatus, 'in_progress'>, options?: t.RunStepCloseOptions): Promise<boolean>;
+    /**
+     * Observes one `ON_RUN_STEP_COMPLETED` for a step and closes the step when
+     * no registered tool calls remain pending. Steps without pending tracking
+     * (summaries, cross-process resume) close on their first completion; the
+     * terminal-status guard in `closeRunStep` absorbs duplicate echoes.
+     */
+    recordStepCompletion(stepId: string, options?: t.RecordStepCompletionOptions): Promise<void>;
+    /**
+     * Closes the tracked open MESSAGE_CREATION step for the event's agent lane.
+     * Fires on every model end, so the empty-map check short-circuits ahead of
+     * resolving the lane key — a turn whose message step already closed through
+     * successor-close does no work here.
+     */
+    closeOpenMessageStep(metadata?: Record<string, unknown>, 
+    /** Model-end time captured before host handlers ran, so a slow usage sink
+     *  cannot inflate the step's measured duration. */
+    at?: number): Promise<void>;
+    /**
+     * End-of-run sweep: closes every step that never reached a terminal
+     * status. Dual-dispatches like any other close — the custom-event channel
+     * is usually already torn down here and `safeDispatchCustomEvent` reports
+     * that quietly, but callback-only subscribers still receive the terminal
+     * signal whenever it is alive.
+     */
+    closeUnfinishedRunSteps(status: Exclude<t.RunStepStatus, 'in_progress'>, at?: number): Promise<void>;
     getAgentContext(metadata: Record<string, unknown> | undefined): AgentContext;
     getStepBaseKey(metadata: Record<string, unknown> | undefined): string;
     getStepKey(metadata: Record<string, unknown> | undefined): string;

package/dist/types/langfuseTraceShaping.d.ts

@@ -20,8 +20,9 @@ export declare function shouldDropLangfuseSpan(spanName: string): boolean;
  * - Agent nodes become `agent` observations, while tool-dispatch nodes become
  *   stable `chain` observations whose input is scoped to the pending calls.
  *   Individual child calls remain `tool` observations (items 3 & 4).
- * - Agent trace roots become `agent` observations and title trace roots become
- *   `chain` observations. Root and trace input/output are reduced to the user
- *   question and assistant response when chat messages are available (item 2).
+ * - Agent trace roots become `agent` observations, while title and activity
+ *   summary roots become `chain` observations. Root and trace input/output are
+ *   reduced to the user question and assistant response when chat messages are
+ *   available (item 2).
  */
 export declare function shapeLangfuseSpan(span: ReadableSpan): void;

package/dist/types/run.d.ts

@@ -138,6 +138,14 @@ export declare class Run<_T extends t.BaseGraphState> {
     private createCustomEventCallback;
     private shouldClearHookSession;
     private isAwaitingResume;
+    /**
+     * Terminal status for steps still open at end-of-run: `cancelled` for
+     * intentional stops (caller abort, hook halt), `failed` for unexpected
+     * stream errors, `completed` for a natural finish. Reads `_haltedReason`
+     * behind a method boundary on purpose — it is assigned inside the
+     * `consumeStream` closure, which control-flow narrowing cannot see.
+     */
+    private resolveSweepStatus;
     private getStreamLangfuseConfig;
     private getStreamToolOutputTracingLangfuseConfig;
     processStream(inputs: t.IState | Command, callerConfig: t.RunStreamConfig, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;
@@ -247,7 +255,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     }>;
     /**
      * Generates one parent summary for two or more logical activities. The
-     * summary model is traced as a dedicated activity-phase agent root in the
+     * summary model is traced as a dedicated activity-phase chain root in the
      * conversation session, with the model callback recorded as its generation
      * child. No session id means no phase trace, avoiding orphan observations.
      */

package/dist/types/session/types.d.ts

@@ -150,7 +150,7 @@ export interface AgentSessionRunOptions {
     streamOptions?: t.EventStreamOptions;
 }
 export interface AgentSessionStreamEvent {
-    type: 'run.started' | 'message.delta' | 'reasoning.delta' | 'tool.started' | 'tool.delta' | 'tool.completed' | 'usage.updated' | 'run.completed' | 'run.failed' | 'run.interrupted' | 'run.halted';
+    type: 'run.started' | 'message.delta' | 'reasoning.delta' | 'tool.started' | 'tool.delta' | 'tool.completed' | 'step.finished' | 'usage.updated' | 'run.completed' | 'run.failed' | 'run.interrupted' | 'run.halted';
     sequence: number;
     runId: string;
     threadId: string;

package/dist/types/summarization/node.d.ts

@@ -21,6 +21,12 @@ interface CreateSummarizeNodeParams {
         hookRegistry?: HookRegistry;
         dispatchRunStep: (runStep: t.RunStep, config?: RunnableConfig) => Promise<void>;
         dispatchRunStepCompleted: (stepId: string, result: t.StepCompleted, config?: RunnableConfig) => Promise<void>;
+        /**
+         * Terminal close for a summary step that ends without a completion —
+         * an errored or empty summary would otherwise stay `in_progress` until
+         * the run-end sweep reported it as `completed`.
+         */
+        closeRunStep?: (stepId: string, status: Exclude<t.RunStepStatus, 'in_progress'>, config?: RunnableConfig) => Promise<void>;
         /** The run's shared breaker signal, composed into every summarization
          * model attempt so a sibling branch tripping a stream limit also
          * cancels in-flight summaries. */

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

@@ -5,8 +5,8 @@ import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
+import type { RunStep, RunStepDeltaEvent, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
-import type { RunStep, RunStepDeltaEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
@@ -73,7 +73,7 @@ export interface ContextUsageEvent {
     calibrationRatio?: number;
 }
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
+    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -442,7 +442,7 @@ export type ExecutableSubagentConfig = ResolvedSubagentConfig | LazySingleAgentS
 /** Graph-aware config accepted by the executor. Graph configs stay eager. */
 export type ExecutableSubagentConfigEntry = ExecutableSubagentConfig | GraphSubagentConfig;
 /** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
-export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
+export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'run_step_closed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
 export interface SubagentAncestryEntry {
     readonly subagentRunId: string;
     readonly subagentType: string;

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

@@ -2,6 +2,7 @@ import type { MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessa
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { LLMResult, Generation } from '@langchain/core/outputs';
 import type { Command } from '@langchain/langgraph';
+import type Anthropic from '@anthropic-ai/sdk';
 import type { AnthropicContentBlock } from '@/llm/anthropic/types';
 import type { AssistantTextPhase } from '@/types/assistantPhase';
 import type { SummarizeCompleteEvent } from '@/types/summarize';
@@ -34,8 +35,25 @@ start, stream and end are associated with slightly different data payload.
 
 Please see the documentation for EventData for more details. */
 export type EventName = string;
+export type RunStepStatus = 'in_progress' | 'completed' | 'cancelled' | 'failed';
 export type RunStep = {
     type: StepTypes;
+    /** Epoch ms when the step was dispatched. */
+    created_at?: number;
+    /**
+     * Lifecycle status; terminal values are stamped when the step closes.
+     * Invariant (enforced by `closeRunStep`, not the type, to stay wire-compatible
+     * with the OpenAI Assistants shape): a terminal status sets exactly one
+     * matching `*_at` field; first close wins and `cancelled`/`failed` are
+     * immutable once stamped.
+     */
+    status?: RunStepStatus;
+    /** Epoch ms when the step closed with status `completed`. */
+    completed_at?: number;
+    /** Epoch ms when the step closed with status `cancelled` (abort/halt). */
+    cancelled_at?: number;
+    /** Epoch ms when the step closed with status `failed`. */
+    failed_at?: number;
     id: string;
     runId?: string;
     agentId?: string;
@@ -71,6 +89,41 @@ export interface RunStepDeltaEvent {
      */
     delta: ToolCallDelta;
 }
+/**
+ * Terminal signal for a run step, emitted exactly once per step when it
+ * finishes (`completed`), is aborted/halted (`cancelled`), or the run errors
+ * (`failed`). The `id` is top-level so callback echoes dedupe like other
+ * step-scoped events.
+ */
+export interface RunStepClosedEvent {
+    id: string;
+    index: number;
+    type: StepTypes;
+    status: Exclude<RunStepStatus, 'in_progress'>;
+    /** Epoch ms when the step was dispatched, when known. */
+    created_at?: number;
+    /** Epoch ms when the step reached its terminal status. */
+    closed_at: number;
+    runId?: string;
+    agentId?: string;
+    groupId?: number;
+    stepIndex?: number;
+}
+export type RecordStepCompletionOptions = {
+    /** The completing tool call, when the step tracks pending completions. */
+    toolCallId?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * Producer-stamped completion time (epoch ms). Carried through so a slow
+     * host completion handler cannot inflate the recorded step duration.
+     */
+    at?: number;
+};
+export type RunStepCloseOptions = {
+    /** Epoch ms for the terminal stamp; defaults to `Date.now()` at close time. */
+    at?: number;
+    metadata?: Record<string, unknown>;
+};
 export type StepDetails = MessageCreationDetails | ToolCallsDetails;
 export type SummaryCompleted = {
     type: 'summary';
@@ -132,6 +185,8 @@ export type ToolCompleteEvent = ToolCallCompleted & {
     /** The content index of the tool call */
     index: number;
     type: 'tool_call';
+    /** Epoch ms when this tool call's completion was dispatched. */
+    completed_at?: number;
 };
 export type ToolCallsDetails = {
     type: StepTypes.TOOL_CALLS;
@@ -224,6 +279,8 @@ export type MessageDeltaUpdate = {
     type: ContentTypes.TEXT;
     text: string;
     tool_call_ids?: string[];
+    /** Provider-supplied source citations, accumulated across deltas. */
+    citations?: Anthropic.TextCitation[];
 };
 export type ReasoningDeltaUpdate = {
     type: ContentTypes.THINK;

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

@@ -21,6 +21,7 @@ interface HandlerCallbacks {
     onRunStep?: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData) => void;
     onRunStepCompleted?: (event: GraphEvents.ON_RUN_STEP_COMPLETED, data: t.StreamEventData) => void;
     onRunStepDelta?: (event: GraphEvents.ON_RUN_STEP_DELTA, data: t.StreamEventData) => void;
+    onRunStepClosed?: (event: GraphEvents.ON_RUN_STEP_CLOSED, data: t.RunStepClosedEvent) => void;
     onMessageDelta?: (event: GraphEvents.ON_MESSAGE_DELTA, data: t.StreamEventData) => void;
 }
 /**

package/package.json

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

package/src/aggregator.test.ts

@@ -1085,3 +1085,130 @@ describe('ContentAggregator multi-entry deltas', () => {
     });
   });
 });
+
+describe('ContentAggregator citation deltas', () => {
+  const citation = (url: string, cited_text: string) => ({
+    type: 'web_search_result_location',
+    url,
+    title: 'Example',
+    cited_text,
+    encrypted_index: 'enc',
+  });
+
+  /**
+   * Anthropic emits a search turn's citations as their own `citations_delta`,
+   * which `_makeMessageChunkFromAnthropicEvent` normalizes into a `text` part
+   * carrying `citations` and **no** `text` key.
+   */
+  const citationDelta = (id: string, ...citations: unknown[]) => ({
+    event: GraphEvents.ON_MESSAGE_DELTA,
+    data: {
+      id,
+      delta: { content: [{ type: ContentTypes.TEXT, citations }] },
+    } as t.MessageDeltaEvent,
+  });
+
+  const textDelta = (id: string, text: string) => ({
+    event: GraphEvents.ON_MESSAGE_DELTA,
+    data: {
+      id,
+      delta: { content: [{ type: ContentTypes.TEXT, text }] },
+    } as t.MessageDeltaEvent,
+  });
+
+  it('keeps citations that arrive without accompanying text', () => {
+    const { contentParts, aggregateContent } = createContentAggregator();
+    aggregateContent({
+      event: GraphEvents.ON_RUN_STEP,
+      data: createRunStep('step_citations'),
+    });
+
+    aggregateContent(textDelta('step_citations', 'Answer.'));
+    aggregateContent(
+      citationDelta('step_citations', citation('https://a.example', 'quoted a'))
+    );
+
+    expect(contentParts[0]).toEqual({
+      type: ContentTypes.TEXT,
+      text: 'Answer.',
+      citations: [citation('https://a.example', 'quoted a')],
+    });
+  });
+
+  it('accumulates citations across successive deltas', () => {
+    const { contentParts, aggregateContent } = createContentAggregator();
+    aggregateContent({
+      event: GraphEvents.ON_RUN_STEP,
+      data: createRunStep('step_multi'),
+    });
+
+    aggregateContent(textDelta('step_multi', 'Part one. '));
+    aggregateContent(
+      citationDelta('step_multi', citation('https://a.example', 'quoted a'))
+    );
+    aggregateContent(textDelta('step_multi', 'Part two.'));
+    aggregateContent(
+      citationDelta('step_multi', citation('https://b.example', 'quoted b'))
+    );
+
+    expect(contentParts[0]).toEqual({
+      type: ContentTypes.TEXT,
+      text: 'Part one. Part two.',
+      citations: [
+        citation('https://a.example', 'quoted a'),
+        citation('https://b.example', 'quoted b'),
+      ],
+    });
+  });
+
+  it('leaves parts without citations untouched', () => {
+    const { contentParts, aggregateContent } = createContentAggregator();
+    aggregateContent({
+      event: GraphEvents.ON_RUN_STEP,
+      data: createRunStep('step_plain'),
+    });
+
+    aggregateContent(textDelta('step_plain', 'Hello '));
+    aggregateContent(textDelta('step_plain', 'world.'));
+
+    expect(contentParts[0]).toEqual({
+      type: ContentTypes.TEXT,
+      text: 'Hello world.',
+    });
+    expect(contentParts[0]).not.toHaveProperty('citations');
+  });
+
+  it('preserves tool_call_ids when a citations-only delta follows', () => {
+    const { contentParts, aggregateContent } = createContentAggregator();
+    aggregateContent({
+      event: GraphEvents.ON_RUN_STEP,
+      data: createRunStep('step_tool_ids'),
+    });
+
+    aggregateContent({
+      event: GraphEvents.ON_MESSAGE_DELTA,
+      data: {
+        id: 'step_tool_ids',
+        delta: {
+          content: [
+            {
+              type: ContentTypes.TEXT,
+              text: 'Answer.',
+              tool_call_ids: ['call_1'],
+            },
+          ],
+        },
+      } as t.MessageDeltaEvent,
+    });
+    aggregateContent(
+      citationDelta('step_tool_ids', citation('https://a.example', 'quoted a'))
+    );
+
+    expect(contentParts[0]).toEqual({
+      type: ContentTypes.TEXT,
+      text: 'Answer.',
+      tool_call_ids: ['call_1'],
+      citations: [citation('https://a.example', 'quoted a')],
+    });
+  });
+});

package/src/common/enum.ts

@@ -15,6 +15,8 @@ export enum GraphEvents {
   ON_RUN_STEP_DELTA = 'on_run_step_delta',
   /** [Custom] Completed event for run steps (tool calls) */
   ON_RUN_STEP_COMPLETED = 'on_run_step_completed',
+  /** [Custom] Terminal signal for a run step: closed with status + timestamps */
+  ON_RUN_STEP_CLOSED = 'on_run_step_closed',
   /** [Custom] Delta events for messages */
   ON_MESSAGE_DELTA = 'on_message_delta',
   /** [Custom] Reasoning Delta events for messages */