@librechat/agents 3.4.7 → 3.5.0

package/dist/esm/tools/subagent/SubagentExecutor.mjs

@@ -263,12 +263,6 @@ function createReplayCheckpointWorkflow(checkpointer) {
 var SubagentExecutor = class {
 	configs;
 	parentSignal;
-	/** Aborted when a child trips a stream circuit breaker: parallel sibling
-	* subagents run concurrently on the parent's signal, and rejecting the
-	* batch alone would leave their provider requests streaming after the
-	* safety abort. One-way by design — a tripped breaker ends the run, so no
-	* later child of this executor should start either. Fallback for hosts
-	* that do not supply the graph's shared `breakerScope`. */
 	childRunAbort = new AbortController();
 	breakerScope;
 	hookRegistry;
@@ -318,18 +312,12 @@ var SubagentExecutor = class {
 		if (typeof rawRegistry === "function") this.resolveParentHandlerRegistry = rawRegistry;
 		else if (rawRegistry != null) this.resolveParentHandlerRegistry = () => rawRegistry;
 	}
-	/** The breaker controller current for this execution — read per spawn
-	* because the graph recreates its controller each run. */
 	resolveBreakerController() {
 		return this.breakerScope?.controller() ?? this.childRunAbort;
 	}
-	/** One signal that fires on the parent's abort or the breaker abort,
-	* collapsed to a single signal when possible (mirrors
-	* `composeAbortSignals` in Graph.ts). */
 	composeChildSignal(breaker, executionSignal) {
 		return composeAbortSignals(composeAbortSignals(this.parentSignal, breaker.signal), executionSignal) ?? breaker.signal;
 	}
-	/** Snapshot of the parent's registry at the moment a subagent is dispatched. */
 	getParentHandlerRegistry() {
 		return this.resolveParentHandlerRegistry?.();
 	}
@@ -342,9 +330,6 @@ var SubagentExecutor = class {
 			throw error;
 		}
 	}
-	/** Resolve one lazy descriptor per stable child execution. Concurrent
-	* duplicate dispatches share the same in-flight resolution; HITL re-entry
-	* on this executor reuses the resolved config until the child settles. */
 	resolveExecutionConfig(config, execution, context) {
 		if (isGraphSubagentConfig(config) || config.agentInputs != null) return Promise.resolve(config);
 		const resolver = config.resolveAgentInputs;
@@ -368,12 +353,6 @@ var SubagentExecutor = class {
 			agentInputs
 		})), context.childSignal);
 	}
-	/**
-	* Keeps the original child thread as an immutable resume source once a
-	* different parent Run reconstructs it. Each rebuilt parent gets a private
-	* checkpoint fork, while the persisted child run ID remains stable for
-	* activity and usage correlation across the interrupt boundary.
-	*/
 	async resolveChildExecutionIdentity(execution) {
 		return execution.resolveIdentity(async () => {
 			const preparation = await this.createChildExecutionIdentity(execution);
@@ -501,7 +480,6 @@ var SubagentExecutor = class {
 		for await (const _tuple of this.checkpointer.list({ configurable: { thread_id: threadId } }, { limit: 1 })) return true;
 		return false;
 	}
-	/** Captures one exact checkpoint head per namespace for a child thread. */
 	async getLatestCheckpointSnapshot(threadId) {
 		if (this.checkpointer == null) return [];
 		const checkpointsByNamespace = /* @__PURE__ */ new Map();
@@ -512,7 +490,6 @@ var SubagentExecutor = class {
 		}
 		return [...checkpointsByNamespace.values()].sort((left, right) => left.checkpointNs.localeCompare(right.checkpointNs));
 	}
-	/** Copies exact checkpoint lineages, including pending task writes. */
 	async forkCheckpointSnapshot(sources, targetThreadId) {
 		if (this.checkpointer == null || sources.length === 0 || sources.every((source) => source.threadId === targetThreadId)) return;
 		for (const source of sources) {
@@ -822,13 +799,6 @@ var SubagentExecutor = class {
 	}
 	async executeOnce(params, execution, executableConfig) {
 		const { description, subagentType, threadId, parentToolCallId } = params;
-		/** Captured ONCE per execution, preferring the controller the parent
-		* tool batch captured at ITS entry (before PreToolUse hooks): a failed
-		* run's graph reset replaces the live controller, and resolving it here
-		* — after the hook awaits — would bind this child to the NEW run's
-		* un-aborted controller: reviving old-run work, or worse, tripping the
-		* new run's breaker from an old child's stream-limit breach. Signal and
-		* trip target both bind to this capture. */
 		const childBreaker = params.breaker ?? this.resolveBreakerController();
 		const childSignal = this.composeChildSignal(childBreaker, params.signal);
 		const { parentToolCallId: executionSuffix } = execution.address;
@@ -880,15 +850,6 @@ var SubagentExecutor = class {
 		}
 		const parentRegistry = this.getParentHandlerRegistry();
 		const forwardingEnabled = parentRegistry != null;
-		/**
-		* Keep `toolDefinitions` only when the host has actually wired an
-		* `ON_TOOL_EXECUTE` handler. `Run` always constructs a `HandlerRegistry`,
-		* so treating any registry as "forwarding enabled" would leak
-		* `toolDefinitions` into children whose hosts cannot execute them — the
-		* child's `ToolNode` batch promise would hang forever with no handler to
-		* resolve/reject. Gating on the tool-execute handler preserves the
-		* recoverable "no tools" path for registry-but-no-handler configs.
-		*/
 		const hasToolExecuteHandler = parentRegistry?.getHandler("on_tool_execute") != null;
 		const childPlan = createChildGraphPlan({
 			config,
@@ -931,14 +892,6 @@ var SubagentExecutor = class {
 			streamLimits: this.streamLimits,
 			subagentScope: true,
 			subagentExecutionContext: childExecutionContext,
-			/**
-			* Forwarded so the child graph's own `SubagentExecutor` (created in
-			* its `createAgentNode` when `allowNested` keeps subagentConfigs)
-			* reports nested-child usage through the same host sink. Each nesting
-			* level attaches its own capture callback — `workflow.invoke` replaces
-			* the inherited callback chain, so a single top-level handler would
-			* never see grandchild model calls.
-			*/
 			subagentUsageSink
 		};
 		let childGraph = cachedChildRun?.graph;
@@ -986,32 +939,8 @@ var SubagentExecutor = class {
 				checkpointNodeId: childPlan.checkpointNodeId,
 				childRunId
 			});
-			/**
-			* When `parentHandlerRegistry` is provided (forwarding mode), attach a
-			* lightweight callback that intercepts the child's `on_custom_event`
-			* dispatches and routes them to the parent's registry — either as
-			* operational events (ON_TOOL_EXECUTE) or wrapped ON_SUBAGENT_UPDATE
-			* envelopes. Native LangChain streaming events (on_chat_model_stream,
-			* etc.) still do NOT propagate to the parent's outer streamEvents
-			* iterator — the `callbacks` array REPLACES the inherited chain, so
-			* parent handlers won't receive child stream chunks and raise "No
-			* agent context found" lookups on the parent's agentContexts map.
-			*
-			* When no registry is provided (legacy isolation), `callbacks: []`
-			* fully detaches the child.
-			*
-			* `runName` gives the child a distinct LangSmith trace root (avoids
-			* nested trace pollution).
-			*/
 			const callbackHandlers = [];
 			if (forwarder) callbackHandlers.push(forwarder);
-			/**
-			* Usage capture rides the same detached callbacks array. Because
-			* `callbacks` REPLACES the inherited chain (see above), the host's
-			* `CHAT_MODEL_END` handler never observes the child's model calls —
-			* this handler is the child-side equivalent of `ModelEndHandler`,
-			* reporting per-call usage to the host's sink for billing.
-			*/
 			if (this.usageSink) callbackHandlers.push(createUsageCaptureHandler({
 				sink: this.usageSink,
 				subagentType,
@@ -1023,19 +952,6 @@ var SubagentExecutor = class {
 				memberInputs: childPlan.memberInputs
 			}));
 			const callbacks = callbackHandlers;
-			/**
-			* Inherit the parent's host `configurable` while binding LangGraph's
-			* checkpoint identity to a stable child id derived from the durable
-			* parent thread and checkpoint fork. The parent thread id cannot be
-			* reused here: parent and child share one checkpointer when nested HITL
-			* is enabled, and root checkpoint namespaces are normalized by
-			* LangGraph, so a shared `thread_id` would collide with the parent.
-			*
-			* `run_id` still propagates as the parent run id, which is the key used
-			* for session-scoped hook lookup. Child hook inputs therefore retain
-			* the parent policy scope while their `threadId` truthfully identifies
-			* the independently checkpointed child execution.
-			*/
 			const inheritedConfigurable = sanitizeChildConfigurable(params.parentConfigurable);
 			const { resumeAttemptId } = execution.address;
 			if (cachedChildRun == null && resumeExecution != null) childGraph.restoreSubagentResumeState(resumeExecution.graphState, currentHookSessionId);
@@ -1055,8 +971,6 @@ var SubagentExecutor = class {
 			};
 			activeChildRun.invokeConfig = childInvokeConfig;
 			if (cachedChildRun == null && this.humanInTheLoop?.enabled === true) {
-				/** Rehydrate child-owned interrupt state when a host rebuilds Run
-				* around the same durable checkpointer after a process boundary. */
 				const persistedState = await workflow.getState(childInvokeConfig);
 				const checkpointMessages = getCheckpointMessages(persistedState.values?.messages);
 				const persistedHookSessionId = getSubagentHookSessionId(checkpointMessages);
@@ -1132,11 +1046,7 @@ var SubagentExecutor = class {
 					label: `Subagent "${subagentType}" started`
 				});
 				let childResult;
-				if (this.humanInTheLoop?.enabled === true)
- /** Execute as an independently checkpointed root instead of inheriting
-				* the parent's Pregel namespace. Parent decisions are routed explicitly
-				* by interrupt id, so concurrent children keep isolated resume state. */
-				childResult = await AsyncLocalStorageProviderSingleton.runWithConfig(childInvokeConfig, () => workflow.invoke(childInput, childInvokeConfig));
+				if (this.humanInTheLoop?.enabled === true) childResult = await AsyncLocalStorageProviderSingleton.runWithConfig(childInvokeConfig, () => workflow.invoke(childInput, childInvokeConfig));
 				else childResult = await workflow.invoke(childInput, childInvokeConfig);
 				const childInterrupts = isInterrupted(childResult) ? childResult[INTERRUPT] : void 0;
 				if (childInterrupts != null && childInterrupts.length > 0) throw new GraphInterrupt(childInterrupts);
@@ -1158,13 +1068,6 @@ var SubagentExecutor = class {
 					parent_tool_call_id: parentToolCallId
 				}, resumeManifest));
 			}
-			/** Aborted before any observational work below: parallel siblings — in
-			* this executor and, via the graph-scoped breaker, under other
-			* parallel agent nodes — stream on the composed child signal, and
-			* awaiting forwarding.drain() first would let them consume provider
-			* quota for that entire interval. Trips the ENTRY-captured controller:
-			* after a reset, a straggler must break its own dead run, not the
-			* current one. */
 			if (error instanceof StreamLimitExceededError) childBreaker.abort(error);
 			const errorMessage = truncateErrorMessage(error);
 			if (forwarding) {
@@ -1183,13 +1086,6 @@ var SubagentExecutor = class {
 			}
 			this.clearChildGraph(childGraph);
 			execution.markFailed();
-			/**
-			* A tripped stream circuit breaker is a safety abort, not a recoverable
-			* subagent failure: converting it into a tool result would let the
-			* parent keep generating (or spawn another child) after the limit
-			* fired. Rethrown here and passed through ToolNode's error conversion,
-			* so the parent run rejects with the child's limit error.
-			*/
 			if (error instanceof StreamLimitExceededError) throw error;
 			return {
 				content: `Subagent error: ${errorMessage}`,
@@ -1198,14 +1094,7 @@ var SubagentExecutor = class {
 		}
 		if (result == null) throw new Error("Subagent completed without producing graph state.");
 		const filteredContent = childPlan.kind === "graph" ? filterGraphSubagentResult(result, childPlan.resultAgentId) : filterSubagentResult(result.messages);
-		if (!childAlreadyCompleted && this.hookRegistry?.hasHookFor("SubagentStop", currentHookSessionId) === true)
- /**
-		* Awaited (not fire-and-forget) for deterministic test synchronization
-		* and consistency with PostCompact. The parent is already waiting on the
-		* tool result, so the small extra latency is acceptable. Errors are
-		* swallowed — SubagentStop is observational.
-		*/
-		await executeHooks({
+		if (!childAlreadyCompleted && this.hookRegistry?.hasHookFor("SubagentStop", currentHookSessionId) === true) await executeHooks({
 			registry: this.hookRegistry,
 			input: {
 				hook_event_name: "SubagentStop",
@@ -1243,11 +1132,6 @@ var SubagentExecutor = class {
 		execution.markCompleted(completedResult);
 		return completedResult;
 	}
-	/**
-	* Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
-	* parent's handler registry. Silent no-op when no parent registry is set.
-	* Errors are swallowed — update events are observational.
-	*/
 	async emitSubagentUpdate(parentRegistry, args) {
 		const handler = parentRegistry.getHandler("on_subagent_update");
 		if (!handler) return;
@@ -1269,18 +1153,6 @@ var SubagentExecutor = class {
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
 	}
-	/**
-	* Builds a BaseCallbackHandler that intercepts the child graph's custom
-	* events. Routing rules:
-	*   - `ON_TOOL_EXECUTE` → forwarded as-is to the parent's ON_TOOL_EXECUTE
-	*     handler (so event-driven tools work identically for child and parent).
-	*   - `ON_RUN_STEP` / `ON_RUN_STEP_DELTA` / `ON_RUN_STEP_COMPLETED` /
-	*     `ON_MESSAGE_DELTA` / `ON_REASONING_DELTA` → wrapped in a
-	*     {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope with a human-readable
-	*     label, delivered to the parent's subagent-update handler.
-	*   - Everything else → ignored (keeps parent's UI scoped to the events it
-	*     cares about; host apps can extend by registering more phases).
-	*/
 	createForwarderCallback(args) {
 		const { parentRegistry, subagentType, subagentKind, subagentAgentId, graphMemberInputs, childRunId, parentToolCallId, executionContext } = args;
 		const immediateParentRunId = this.parentRunId;
@@ -1361,10 +1233,6 @@ var SubagentExecutor = class {
 			if (eventName === "on_tool_execute") {
 				const toolHandler = parentRegistry.getHandler("on_tool_execute");
 				if (toolHandler) await toolHandler.handle("on_tool_execute", data);
-				/**
-				* We also surface a short notice in the subagent-update stream so
-				* the UI can show "calling <tool>" for each tool the child spawns.
-				*/
 				scheduleWrap(eventName, "run_step", data, memberAgentId);
 				return;
 			}
@@ -1393,15 +1261,6 @@ var SubagentExecutor = class {
 				return;
 			}
 		} });
-		/**
-		* `awaitHandlers = true` is required so the child's `ToolNode` actually
-		* blocks on the parent's `ON_TOOL_EXECUTE` handler until it resolves
-		* the batch request. Observational `ON_SUBAGENT_UPDATE` calls are queued
-		* behind a bounded sequential dispatcher so host UI publication cannot
-		* backpressure each child emission or run unbounded concurrent publishes.
-		* The executor drains this queue before terminal stop/error envelopes to
-		* preserve phase ordering.
-		*/
 		handler.awaitHandlers = true;
 		return {
 			handler,
@@ -1409,31 +1268,9 @@ var SubagentExecutor = class {
 		};
 	}
 };
-/**
-* Builds the child-run equivalent of a host `CHAT_MODEL_END` handler: a
-* callback that joins per-call model identity (captured from
-* `ls_model_name` at chat-model start) with the usage metadata reported at
-* LLM end, and emits a {@link SubagentUsageEvent} through the host's sink.
-*
-* Attached to the child `workflow.invoke` callbacks array, so it observes
-* every model call inside the child graph — the agent loop and any
-* auxiliary calls (e.g. child-side summarization). It does NOT observe
-* deeper subagent levels: each nesting level replaces the callback chain
-* and attaches its own capture handler via the forwarded
-* `subagentUsageSink` on the child graph's input.
-*/
 function createUsageCaptureHandler(args) {
 	const { sink, subagentType, subagentKind, subagentRunId, subagentAgentId, parentRunId, executionContext, memberInputs } = args;
 	const defaultMember = memberInputs.size === 1 ? memberInputs.entries().next().value : void 0;
-	/**
-	* Per-call attribution keyed by LangChain callback runId. `model` joins
-	* `ls_model_name` (provider-reported) with `INVOKED_MODEL` (stamped by
-	* `tryFallbackProviders` from the fallback's client options); `provider`
-	* is `INVOKED_PROVIDER`, stamped by `attemptInvoke` with the SDK enum of
-	* the provider that ACTUALLY served the call — correct for
-	* fallback-served calls, where the static config provider would mis-tag
-	* pricing/cache semantics.
-	*/
 	const callInfoByCallId = /* @__PURE__ */ new Map();
 	const handler = BaseCallbackHandler.fromMethods({
 		handleChatModelStart: (_llm, _messages, runId, _parentRunId, _extraParams, _tags, metadata) => {
@@ -1454,24 +1291,9 @@ function createUsageCaptureHandler(args) {
 			const memberInput = (memberAgentId == null ? void 0 : memberInputs.get(memberAgentId)) ?? defaultMember?.[1];
 			const model = callInfo?.model ?? (memberInput == null ? void 0 : extractConfiguredModel(memberInput));
 			const callProvider = callInfo?.provider ?? memberInput?.provider;
-			for (const generationGroup of output.generations)
- /**
-			* At most ONE event per generation group: each group is one
-			* provider request (the outer array is per-prompt for batched
-			* calls), and with multiple completions (`n > 1`) every choice in
-			* a group repeats the request-level `usage_metadata` — emitting
-			* per choice would multiply billed tokens.
-			*/
-			for (const generation of generationGroup) {
+			for (const generationGroup of output.generations) for (const generation of generationGroup) {
 				const usage = (generation?.message)?.usage_metadata;
 				if (usage == null) continue;
-				/**
-				* Awaited so async host sinks (billing/persistence) complete
-				* before the model call resolves — `awaitHandlers` only waits on
-				* `handleLLMEnd` itself, so a dropped promise here would let the
-				* parent run finish before usage is recorded and would turn sink
-				* rejections into unhandled rejections.
-				*/
 				try {
 					await sink({
 						usage,
@@ -1495,11 +1317,6 @@ function createUsageCaptureHandler(args) {
 			callInfoByCallId.delete(runId);
 		}
 	});
-	/**
-	* Dispatch usage synchronously with each model call so all entries are
-	* sunk before `workflow.invoke` resolves — hosts read their accumulator
-	* right after the parent run completes.
-	*/
 	handler.awaitHandlers = true;
 	return handler;
 }
@@ -1529,11 +1346,6 @@ function getGraphEventMemberAgentId({ data, metadata, memberInputs, memberAgentI
 	const metadataAgentId = asNonEmptyString(metadata?.agentId);
 	return metadataAgentId != null && memberInputs.has(metadataAgentId) ? metadataAgentId : void 0;
 }
-/**
-* Best-effort read of the configured model from a subagent's client
-* options. Providers disagree on the key (`model` vs `modelName`), and the
-* value is only a fallback for calls that carry no `ls_model_name`.
-*/
 function extractConfiguredModel(agentInputs) {
 	const clientOptions = agentInputs.clientOptions;
 	if (typeof clientOptions?.model === "string" && clientOptions.model !== "") return clientOptions.model;
@@ -1759,11 +1571,6 @@ function assignString(target, key, value) {
 function assignNumber(target, key, value) {
 	if (typeof value === "number") target[key] = value;
 }
-/**
-* Produces a short single-line label for an arbitrary forwarded child event.
-* Used to populate {@link SubagentUpdateEvent.label} so the host UI can show
-* a compact status ticker without parsing the raw payload.
-*/
 function summarizeEvent(eventName, data) {
 	if (eventName === "on_tool_execute") {
 		const names = (data.toolCalls ?? []).map((c) => c.name).filter((n) => typeof n === "string");
@@ -1791,29 +1598,12 @@ function summarizeEvent(eventName, data) {
 	if (eventName === "on_message_delta") return "Streaming…";
 	return eventName;
 }
-/**
-* Reads only the result member captured by MultiAgentGraph. Worker output is
-* never used as a fallback when the designated result member is textless.
-*/
 function filterGraphSubagentResult(state, resultAgentId) {
 	const result = state.subagentResult;
 	if (result == null || result.agentId !== resultAgentId) return `Error: Graph subagent result agent "${resultAgentId}" did not produce a result.`;
 	if (result.message == null) return "Task completed";
 	return filterSubagentResult([result.message]);
 }
-/**
-* Walk messages from last to first, returning the text content of the most
-* recent AIMessage that has any. Non-text blocks (tool_use, thinking,
-* redacted_thinking, tool_result) are stripped. If the last AIMessage is
-* pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
-* continues to earlier AIMessages so partial progress is salvaged — this
-* matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
-* Consecutive streamed text-delta blocks with the same provider index are
-* coalesced without adding whitespace. Annotation-only text blocks are
-* ignored; complete text blocks and distinct delta indexes remain separated.
-* Returns "Task completed" only when no AIMessage in the history contains
-* any text.
-*/
 function filterSubagentResult(messages) {
 	for (let i = messages.length - 1; i >= 0; i--) {
 		if (messages[i]._getType() !== "ai") continue;