@librechat/agents 3.4.4 → 3.4.6

package/dist/esm/run.mjs

@@ -39,11 +39,14 @@ const defaultOmitOptions = new Set([
 	"maxOutputTokens",
 	"additionalModelRequestFields"
 ]);
+const ACTIVITY_LABEL_TRACE_NAME = "LibreChat Activity Label";
+const ACTIVITY_PHASE_TRACE_NAME = "LibreChat Activity Phase";
 const CUSTOM_GRAPH_EVENTS = new Set([
 	"on_agent_update",
 	"on_run_step",
 	"on_run_step_delta",
 	"on_run_step_completed",
+	"on_run_step_closed",
 	"on_message_delta",
 	"on_reasoning_delta",
 	"on_tool_execute",
@@ -58,6 +61,7 @@ const CUSTOM_GRAPH_EVENTS = new Set([
 const DIRECT_DISPATCHED_STEP_EVENTS = new Set([
 	"on_run_step",
 	"on_run_step_delta",
+	"on_run_step_closed",
 	"on_message_delta",
 	"on_reasoning_delta"
 ]);
@@ -66,6 +70,25 @@ function getStepScopedEventId(data) {
 	const candidate = data;
 	return typeof candidate.id === "string" ? candidate.id : void 0;
 }
+/**
+* Narrows an ON_RUN_STEP_COMPLETED payload (`{ result: ToolCompleteEvent }`)
+* to the ids step closure needs. Returns undefined for malformed payloads and
+* the resume race's empty step id.
+*/
+function getToolCompletion(data) {
+	if (data == null || typeof data !== "object") return;
+	const { result } = data;
+	if (result == null || typeof result !== "object") return;
+	const candidate = result;
+	if (typeof candidate.id !== "string" || candidate.id === "") return;
+	const toolCallId = candidate.tool_call?.id;
+	const completedAt = candidate.completed_at;
+	return {
+		stepId: candidate.id,
+		...typeof toolCallId === "string" ? { toolCallId } : {},
+		...typeof completedAt === "number" ? { completedAt } : {}
+	};
+}
 function isLangGraphResumeMapForInterrupt(value, interruptId) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
 	return Object.prototype.hasOwnProperty.call(value, interruptId);
@@ -464,7 +487,32 @@ var Run = class Run {
 			const stepScopedEventId = getStepScopedEventId(data);
 			if (DIRECT_DISPATCHED_STEP_EVENTS.has(eventName) && this.Graph != null && stepScopedEventId != null && this.Graph.hasHandlerDispatchedEvent(eventName, stepScopedEventId)) return;
 			const handler = this.handlerRegistry?.getHandler(eventName);
-			if (handler && this.Graph) return await handler.handle(eventName, data, metadata, this.Graph);
+			/**
+			* Tool completions arriving over the custom-event channel are the only
+			* signal ToolNode (which holds no graph reference) emits — observe them
+			* here to drive step closure. Runs in `finally`, independent of handler
+			* registration, so an absent or throwing host handler cannot lose the
+			* close; duplicate callback echoes are absorbed by the terminal-status
+			* guard in `closeRunStep`.
+			*/
+			try {
+				if (handler && this.Graph) return await handler.handle(eventName, data, metadata, this.Graph);
+			} finally {
+				if (eventName === "on_run_step_completed" && this.Graph != null) {
+					const completion = getToolCompletion(data);
+					if (completion != null)
+ /**
+					* The producer stamped `completed_at` before dispatch. Carrying it
+					* through keeps the recorded duration the tool's, not the host
+					* handler's — this runs after an arbitrarily slow handler resolves.
+					*/
+					await this.Graph.recordStepCompletion(completion.stepId, {
+						toolCallId: completion.toolCallId,
+						metadata,
+						at: completion.completedAt
+					});
+				}
+			}
 		};
 	}
 	shouldClearHookSession(streamThrew) {
@@ -473,6 +521,18 @@ var Run = class Run {
 	isAwaitingResume(streamThrew) {
 		return this._interrupt != null && this._haltedReason == null && !streamThrew;
 	}
+	/**
+	* 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.
+	*/
+	resolveSweepStatus(streamThrew, streamAborted) {
+		if (streamThrew) return streamAborted ? "cancelled" : "failed";
+		if (this._haltedReason != null) return "cancelled";
+		return "completed";
+	}
 	getStreamLangfuseConfig(graph) {
 		const primaryContext = graph.agentContexts.get(graph.defaultAgentId);
 		if (primaryContext != null) return resolveLangfuseConfig(this.langfuse, primaryContext.langfuse);
@@ -644,6 +704,14 @@ var Run = class Run {
 		* preserving session hooks would leak them into the next run.
 		*/
 		let streamThrew = false;
+		let streamAborted = false;
+		/**
+		* When the stream itself ended — captured before the post-stream work in
+		* the `finally` (Stop/StopFailure hooks, Langfuse disposal, which can
+		* force-flush) so a slow hook cannot inflate the terminal stamps that the
+		* sweep writes onto steps that were still open.
+		*/
+		let terminalAt;
 		const consumeStream = async () => {
 			/**
 			* `streamEvents` accepts both state inputs and `Command` (resume) at
@@ -700,9 +768,22 @@ var Run = class Run {
 						};
 					}
 				}
+				/**
+				* Stamped before the handler runs: the close below happens after an
+				* arbitrarily slow host handler resolves, and the step's duration
+				* should end when the model did, not when the host finished with it.
+				*/
+				const modelEndAt = eventName === "on_chat_model_end" ? Date.now() : void 0;
 				const handler = this.handlerRegistry?.getHandler(eventName);
 				if (handler) await handler.handle(eventName, data, metadata, this.Graph);
 				/**
+				* A finished model call ends its lane's open message step. Placed
+				* here — not in `ModelEndHandler` — because hosts replace the
+				* CHAT_MODEL_END handler with their own instance, which would
+				* silently drop the close.
+				*/
+				if (eventName === "on_chat_model_end" && this.Graph != null) await this.Graph.closeOpenMessageStep(metadata, modelEndAt);
+				/**
 				* Mid-flight halt: any hook (PreToolUse, PostToolUse,
 				* PostToolBatch, SubagentStart/Stop, PreCompact, PostCompact)
 				* that returned `preventContinuation: true` raises a halt
@@ -729,6 +810,7 @@ var Run = class Run {
 					break;
 				}
 			}
+			terminalAt = Date.now();
 			if (this._interrupt != null) await this.resolveInterruptResumeConfig(config);
 			/**
 			* Skip the Stop hook when the run paused on a HITL interrupt
@@ -787,7 +869,16 @@ var Run = class Run {
 				tags: ["librechat", "agent"]
 			}, consumeStream));
 		} catch (err) {
+			terminalAt = Date.now();
 			streamThrew = true;
+			/**
+			* Corroborate cancellation against an actually-aborted signal. A
+			* provider SDK or host handler can reject with an `AbortError` while
+			* nothing was cancelled — that is an unexpected failure (it also fires
+			* `StopFailure`), and naming it `cancelled` would misreport abort
+			* forensics.
+			*/
+			streamAborted = config.signal?.aborted === true || this.Graph.signal?.aborted === true;
 			if (this.hookRegistry?.hasHookFor("StopFailure", this.id) === true) {
 				const runMessages = this.Graph.getRunMessages() ?? [];
 				await executeHooks({
@@ -831,6 +922,21 @@ var Run = class Run {
 			this.hookRegistry?.clearHaltSignal(this.id);
 			await disposeLangfuseHandler(langfuseHandler);
 			/**
+			* Terminal sweep: close every step that never reached a terminal
+			* status — `completed` on a natural end, `cancelled` on caller abort
+			* or hook halt, `failed` on an unexpected stream error. Skipped on a
+			* HITL pause, where the open steps continue after `resume()`.
+			*
+			* Runs BEFORE the callback teardown below, so a caller observing
+			* lifecycle events only through `RunnableConfig.callbacks` still
+			* receives these closures rather than being left with unmatched
+			* starts, and before `getContentParts()` so terminal stamps flow into
+			* content and session serialization.
+			*/
+			if (!this.isAwaitingResume(streamThrew)) try {
+				await this.Graph.closeUnfinishedRunSteps(this.resolveSweepStatus(streamThrew, streamAborted), terminalAt);
+			} catch {}
+			/**
 			* Break the reference chain that keeps heavy data alive via
 			* LangGraph's internal `__pregel_scratchpad.currentTaskInput` →
 			* `@langchain/core` `RunTree.extra[lc:child_config]` →
@@ -1190,17 +1296,40 @@ var Run = class Run {
 		*  than the labeled agent's. Skip generation entirely instead. */
 		if (agentId != null && requestedContext == null) return {};
 		const labelContext = this.Graph == null ? void 0 : requestedContext ?? this.Graph.agentContexts.get(this.Graph.defaultAgentId);
-		const traceMetadata = createLangfuseTraceMetadata({
-			messageId: "activity-label-" + this.id,
-			agentName: labelContext?.name
-		});
-		const labelRunName = getLangfuseTraceName(traceMetadata, "LibreChat Activity Label");
 		/** Shallow-cloned: activity labels run once per tool batch, and writing
 		*  the Langfuse handler back onto a host-reused `chainOptions` would
 		*  accumulate duplicate callbacks across batches. */
 		const labelChainOptions = { ...chainOptions ?? {} };
 		const labelUserId = typeof labelChainOptions.configurable?.user_id === "string" ? labelChainOptions.configurable.user_id : void 0;
 		const labelSessionId = typeof labelChainOptions.configurable?.thread_id === "string" ? labelChainOptions.configurable.thread_id : void 0;
+		const labelIndex = labelSeq - 1;
+		const labelParentMessageId = labelChainOptions.configurable?.requestBody?.parentMessageId;
+		/** An omitted `agentId` is attributable only when exactly one context
+		*  exists. Multi-agent callers remain unattributed instead of being
+		*  incorrectly assigned to the graph's default agent. */
+		const labelAgentId = agentId ?? (this.Graph?.agentContexts.size === 1 ? this.Graph.defaultAgentId : void 0);
+		const labelAgentName = labelAgentId == null ? void 0 : labelContext?.name;
+		const labelMetadata = {
+			sourceRunId: this.id,
+			responseId: this.id,
+			activityIndex: labelIndex,
+			...typeof labelParentMessageId === "string" ? { parentMessageId: labelParentMessageId } : {},
+			...labelAgentId == null ? {} : { agentId: labelAgentId },
+			...labelAgentName == null ? {} : { agentName: labelAgentName }
+		};
+		const traceMetadata = {
+			...createLangfuseTraceMetadata({
+				messageId: "activity-label-" + this.id,
+				parentMessageId: labelParentMessageId,
+				agentId: labelAgentId,
+				agentName: labelAgentName
+			}),
+			sourceRunId: this.id,
+			responseId: this.id,
+			activityIndex: String(labelIndex)
+		};
+		const labelRunName = labelChainOptions.runName ?? ACTIVITY_LABEL_TRACE_NAME;
+		const labelTags = ["librechat", "activity-label"];
 		const labelLangfuseConfig = resolveLangfuseConfig(this.langfuse, labelContext?.langfuse);
 		initializeLangfuseTracing(labelLangfuseConfig);
 		/** Seed policy, threading two constraints:
@@ -1236,11 +1365,11 @@ var Run = class Run {
 			userId: labelUserId,
 			sessionId: labelSessionId,
 			traceMetadata,
-			tags: ["librechat", "activity-label"],
+			tags: labelTags,
 			traceIdSeed: labelLangfuseConfig?.deterministicTraceId === true ? labelTraceSeed : void 0,
 			runId: labelScopeRunId,
 			toolOutputTracing: labelRuntimeScope.toolOutputTracing,
-			traceName: labelChainOptions.runName ?? labelRunName
+			traceName: labelRunName
 		});
 		if (labelLangfuseHandler != null) labelChainOptions.callbacks = appendCallbacks(labelChainOptions.callbacks, [labelLangfuseHandler]);
 		/** The label prompt becomes Langfuse generation input, so the resolved
@@ -1293,15 +1422,20 @@ var Run = class Run {
 		const invokeConfig = Object.assign({}, labelChainOptions, {
 			run_id: labelRunId,
 			runId: labelRunId,
-			runName: labelChainOptions.runName ?? labelRunName
+			runName: labelRunName,
+			tags: [...new Set([...labelChainOptions.tags ?? [], ...labelTags])],
+			metadata: {
+				...labelChainOptions.metadata ?? {},
+				...labelMetadata
+			}
 		});
 		const invokeLabel = (runtimeConfig) => withLangfuseAttributes({
 			langfuse: labelLangfuseConfig,
 			userId: labelUserId,
 			sessionId: labelSessionId,
-			traceName: runtimeConfig.runName ?? labelRunName,
+			traceName: labelRunName,
 			traceMetadata,
-			tags: ["librechat", "activity-label"]
+			tags: labelTags
 		}, () => model.invoke([new SystemMessage(prompt ?? ACTIVITY_LABEL_PROMPT), new HumanMessage(userPrompt)], runtimeConfig));
 		const extractLabel = (response) => {
 			const content = response?.content;
@@ -1339,7 +1473,7 @@ var Run = class Run {
 	}
 	/**
 	* 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.
 	*/
@@ -1417,8 +1551,7 @@ var Run = class Run {
 			...contributingAgentIds.length === 0 ? {} : { contributingAgentIds: contributingAgentIds.join(",") },
 			...closingTextPhase == null ? {} : { closingTextPhase }
 		};
-		const phaseRunName = getLangfuseTraceName(traceMetadata, "LibreChat Activity Phase");
-		const phaseTraceName = phaseChainOptions.runName ?? phaseRunName;
+		const phaseTraceName = phaseChainOptions.runName ?? ACTIVITY_PHASE_TRACE_NAME;
 		const phaseTags = [
 			"librechat",
 			"activity-phase",