@librechat/agents 3.7.8 → 3.7.10

package/src/hooks/types.ts

@@ -22,6 +22,7 @@ export const HOOK_EVENTS = [
   'SubagentStart',
   'SubagentStop',
   'Stop',
+  'StopFinalize',
   'StopFailure',
   'PreCompact',
   'PostCompact',
@@ -209,7 +210,34 @@ export interface StopHookInput extends BaseHookInput {
   hook_event_name: 'Stop';
   messages: BaseMessage[];
   stopReason?: string;
+  /** True after this hook has already kept the current Run warm once. */
   stopHookActive: boolean;
+  /** Number of terminal continuations already admitted in this Run. */
+  continuationCount: number;
+  /**
+   * Remaining continuations the SDK can honor. A host that durably claims
+   * queued work MUST seal admission instead when this reaches zero.
+   */
+  continuationBudgetRemaining: number;
+}
+
+/**
+ * Serialized terminal admission phase. Unlike ordinary `Stop` hooks (which
+ * execute in parallel), this fires after their outputs have been folded so a
+ * durable host can make one final claim-or-seal decision with full knowledge
+ * of whether another hook already kept the Run warm.
+ */
+export interface StopFinalizeHookInput extends BaseHookInput {
+  hook_event_name: 'StopFinalize';
+  messages: BaseMessage[];
+  stopReason?: string;
+  stopHookActive: boolean;
+  continuationCount: number;
+  continuationBudgetRemaining: number;
+  /** A regular Stop hook already supplied a valid warm continuation. */
+  continuationPlanned: boolean;
+  /** A halt reason or Stop output forbids another graph segment. */
+  continuationPrevented: boolean;
 }
 
 export interface StopFailureHookInput extends BaseHookInput {
@@ -259,6 +287,7 @@ export type HookInput =
   | SubagentStartHookInput
   | SubagentStopHookInput
   | StopHookInput
+  | StopFinalizeHookInput
   | StopFailureHookInput
   | PreCompactHookInput
   | PostCompactHookInput;
@@ -276,6 +305,7 @@ export type HookInputByEvent = {
   SubagentStart: SubagentStartHookInput;
   SubagentStop: SubagentStopHookInput;
   Stop: StopHookInput;
+  StopFinalize: StopFinalizeHookInput;
   StopFailure: StopFailureHookInput;
   PreCompact: PreCompactHookInput;
   PostCompact: PostCompactHookInput;
@@ -298,10 +328,11 @@ export interface BaseHookOutput {
    * mid-run steering message). Accumulated across hooks in registration
    * order.
    *
-   * Consumed at exactly two dispatch sites, both of which run the same
-   * converter so the emitted shapes cannot drift: `PostToolBatch` (the tool
-   * boundary) and `PreemptBoundary` (a cooperative mid-generation seal).
-   * Every other event ignores the field.
+   * Consumed at three dispatch sites, all of which run the same converter so
+   * the emitted shapes cannot drift: `PostToolBatch` (the tool boundary),
+   * `PreemptBoundary` (a cooperative mid-generation seal), and a blocking
+   * `Stop` hook (terminal Run continuation). Every other event ignores the
+   * field.
    */
   injectedMessages?: InjectedMessage[];
   /** True to prevent the next model turn. Any hook can set this. */
@@ -435,10 +466,18 @@ export interface SubagentStartHookOutput extends BaseHookOutput {
 export type SubagentStopHookOutput = BaseHookOutput;
 
 export interface StopHookOutput extends BaseHookOutput {
+  /**
+   * `block` keeps a naturally terminal Run warm only when the output also
+   * supplies non-empty `injectedMessages` or `additionalContext`. The SDK
+   * starts another graph segment inside the same `processStream` call; no
+   * RunStart/UserPromptSubmit hooks or terminal cleanup occur between them.
+   */
   decision?: StopDecision;
   reason?: string;
 }
 
+export type StopFinalizeHookOutput = StopHookOutput;
+
 export type StopFailureHookOutput = BaseHookOutput;
 
 export type PreCompactHookOutput = BaseHookOutput;
@@ -458,6 +497,7 @@ export type HookOutputByEvent = {
   SubagentStart: SubagentStartHookOutput;
   SubagentStop: SubagentStopHookOutput;
   Stop: StopHookOutput;
+  StopFinalize: StopFinalizeHookOutput;
   StopFailure: StopFailureHookOutput;
   PreCompact: PreCompactHookOutput;
   PostCompact: PostCompactHookOutput;
@@ -476,6 +516,7 @@ export type HookOutput =
   | SubagentStartHookOutput
   | SubagentStopHookOutput
   | StopHookOutput
+  | StopFinalizeHookOutput
   | StopFailureHookOutput
   | PreCompactHookOutput
   | PostCompactHookOutput;
@@ -593,6 +634,8 @@ export interface AggregatedHookResult {
    * `preventContinuation` do not overwrite the reason.
    */
   stopReason?: string;
+  /** True when any hook failed, including internal hooks with hidden diagnostics. */
+  hasHookFailures?: true;
   /** Error messages from hooks that threw; always present (possibly empty). */
   errors: string[];
 }

package/src/langfuse.ts

@@ -79,6 +79,8 @@ type LangfuseHandlerParams = {
    *  only adopted when stamped with the same run (see
    *  `LangfuseRuntimeContext.runId`). */
   runId?: string;
+  /** Keep this root open while one processStream call executes graph segments. */
+  deferRootRunId?: string;
   /** The run's resolved tool-output policy — for multi-agent streams the
    *  conservative aggregate across agents, which `this.langfuse` (the
    *  primary agent's config) cannot reproduce. Applied when a foreign
@@ -293,9 +295,19 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
   private readonly agentId?: string;
   private readonly parentSpanContext?: SpanContext;
   private readonly runId?: string;
+  private readonly deferredRootRunId?: string;
   private readonly identity: HandlerIdentity;
   private readonly toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
   private readonly trackedRunIds = new Set<string>();
+  private deferredRootStarted = false;
+  private deferredRootOutcome:
+    | {
+      type: 'end';
+      output: Parameters<CallbackHandler['handleChainEnd']>[0];
+      parentRunId?: string;
+    }
+    | { type: 'error'; error: Error; parentRunId?: string }
+    | undefined;
 
   constructor(params?: AgentLangfuseHandlerParams) {
     const {
@@ -306,6 +318,7 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
       parentSpanContext,
       inheritTraceIdentity,
       runId,
+      deferRootRunId,
       toolOutputTracing,
       traceName,
       ...handlerParams
@@ -326,6 +339,10 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     this.agentId = agentId;
     this.parentSpanContext = parentSpanContext;
     this.runId = runId;
+    this.deferredRootRunId = deferRootRunId;
+    if (deferRootRunId != null) {
+      this.awaitHandlers = true;
+    }
     this.toolOutputTracing = toolOutputTracing;
     this.identity = {
       userId: inheritTraceIdentity === true ? undefined : handlerParams.userId,
@@ -528,6 +545,17 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
   override handleChainStart(
     ...args: Parameters<CallbackHandler['handleChainStart']>
   ): ReturnType<CallbackHandler['handleChainStart']> {
+    const [, , runId, parentRunId] = args;
+    if (
+      runId === this.deferredRootRunId &&
+      parentRunId == null &&
+      this.deferredRootStarted
+    ) {
+      return Promise.resolve();
+    }
+    if (runId === this.deferredRootRunId && parentRunId == null) {
+      this.deferredRootStarted = true;
+    }
     return this.withRuntimeContext(
       () => super.handleChainStart(...args),
       this.startsDetachedRun(args[2], args[3]),
@@ -539,6 +567,13 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     ...args: Parameters<CallbackHandler['handleChainError']>
   ): ReturnType<CallbackHandler['handleChainError']> {
     const [error, runId, parentRunId] = args;
+    if (runId === this.deferredRootRunId && parentRunId == null) {
+      this.deferredRootOutcome = {
+        type: 'error',
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+      return Promise.resolve();
+    }
     if (error != null && parentRunId != null && isGraphInterrupt(error)) {
       return super.handleChainEnd(
         GRAPH_INTERRUPT_CONTROL_FLOW,
@@ -556,6 +591,36 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     return super.handleChainError(...args);
   }
 
+  override handleChainEnd(
+    ...args: Parameters<CallbackHandler['handleChainEnd']>
+  ): ReturnType<CallbackHandler['handleChainEnd']> {
+    const [output, runId, parentRunId] = args;
+    if (runId === this.deferredRootRunId && parentRunId == null) {
+      this.deferredRootOutcome = { type: 'end', output };
+      return Promise.resolve();
+    }
+    return super.handleChainEnd(...args);
+  }
+
+  async finishDeferredRoot(): Promise<void> {
+    const runId = this.deferredRootRunId;
+    const outcome = this.deferredRootOutcome;
+    if (!this.deferredRootStarted || runId == null || outcome == null) {
+      return;
+    }
+    this.deferredRootStarted = false;
+    this.deferredRootOutcome = undefined;
+    if (outcome.type === 'error') {
+      await super.handleChainError(
+        outcome.error,
+        runId,
+        outcome.parentRunId
+      );
+      return;
+    }
+    await super.handleChainEnd(outcome.output, runId, outcome.parentRunId);
+  }
+
   override handleAgentAction(
     ...args: Parameters<CallbackHandler['handleAgentAction']>
   ): ReturnType<CallbackHandler['handleAgentAction']> {
@@ -792,6 +857,7 @@ export function createLangfuseHandler({
   parentSpanContext,
   inheritTraceIdentity,
   runId,
+  deferRootRunId,
   toolOutputTracing,
   traceName,
 }: AgentLangfuseHandlerParams): CallbackHandler | undefined {
@@ -813,6 +879,7 @@ export function createLangfuseHandler({
     parentSpanContext,
     inheritTraceIdentity,
     runId,
+    deferRootRunId,
     toolOutputTracing,
     traceName,
   });
@@ -865,6 +932,9 @@ export function isLangfuseCallbackHandler(value: unknown): boolean {
 }
 
 export async function disposeLangfuseHandler(value: unknown): Promise<void> {
+  if (value instanceof ScopedLangfuseCallbackHandler) {
+    await value.finishDeferredRoot();
+  }
   if (
     value == null ||
     parseBooleanEnv(process.env[LANGFUSE_FORCE_FLUSH_ON_DISPOSE]) !== true

package/src/llm/invoke.ts

@@ -27,6 +27,12 @@ import {
   STREAM_LIMIT_REDISPATCH_KEY,
   STREAM_LIMIT_ATTEMPT_KEY,
 } from '@/llm/streamLimits';
+import {
+  inspectProviderMessageProjection,
+  ProviderMessageProjectionInvariantError,
+  resolveProviderMessageProjectionInvariantMode,
+  modifyDeltaProperties,
+} from '@/messages';
 import {
   assertPreparedProviderRequestFor,
   prepareProviderRequest,
@@ -38,15 +44,10 @@ import {
 import { ChatModelStreamHandler, dispatchesChatModelStream } from '@/stream';
 import { Constants, ContentTypes, GraphEvents, Providers } from '@/common';
 import { assertNotTruncatedToolCall } from '@/llm/truncation';
+import { resolveClientOptionsModel } from '@/llm/request';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { getContextOverflowInfo } from '@/utils/errors';
 import { appendCallbacks } from '@/utils/callbacks';
-import {
-  inspectProviderMessageProjection,
-  ProviderMessageProjectionInvariantError,
-  resolveProviderMessageProjectionInvariantMode,
-  modifyDeltaProperties,
-} from '@/messages';
 import { canSealPreempt } from '@/llm/preempt';
 import { initializeModel } from '@/llm/init';
 
@@ -715,8 +716,7 @@ async function attemptInvokeBody(
     resolveProviderMessageProjectionInvariantMode();
   let sealedRunId: string | undefined;
   let invocationConfig = config;
-  const captureModelRunId =
-    model.stream != null && context?.preemption != null;
+  const captureModelRunId = model.stream != null && context?.preemption != null;
   if (projectionInvariantMode !== 'off' || captureModelRunId) {
     invocationConfig = withModelStartHandler({
       config,
@@ -934,7 +934,10 @@ async function attemptInvokeBody(
     return { messages: [finalChunk as AIMessageChunk] };
   }
 
-  const finalMessage = await model.invoke(messagesForProvider, invocationConfig);
+  const finalMessage = await model.invoke(
+    messagesForProvider,
+    invocationConfig
+  );
   if ((finalMessage.tool_calls?.length ?? 0) > 0) {
     finalMessage.tool_calls = finalMessage.tool_calls?.filter(
       (tool_call: ToolCall) => !!tool_call.name
@@ -997,25 +1000,6 @@ export function getFallbackOverflowCandidates(
   return [...(fallbackOverflowCandidates.get(error) ?? [])];
 }
 
-/**
- * Best-effort read of the configured model name from client options.
- * Providers disagree on the key (`model` vs `modelName`).
- */
-function extractClientOptionsModel(
-  clientOptions: t.ClientOptions | undefined
-): string | undefined {
-  const options = clientOptions as
-    | { model?: unknown; modelName?: unknown }
-    | undefined;
-  if (typeof options?.model === 'string' && options.model !== '') {
-    return options.model;
-  }
-  if (typeof options?.modelName === 'string' && options.modelName !== '') {
-    return options.modelName;
-  }
-  return undefined;
-}
-
 /**
  * Attempts each fallback provider in order until one succeeds.
  *
@@ -1106,7 +1090,7 @@ export async function tryFallbackProviders({
        * `ls_model_name`. The serving provider is stamped uniformly by
        * `attemptInvoke` (`INVOKED_PROVIDER`).
        */
-      const fbModelName = extractClientOptionsModel(fb.clientOptions);
+      const fbModelName = resolveClientOptionsModel(fb.clientOptions);
       const fbConfig: RunnableConfig | undefined =
         fbModelName == null
           ? config

package/src/llm/request.ts

@@ -43,6 +43,30 @@ export function isThinkingEnabled(
   return false;
 }
 
+/**
+ * Model configured on client options, under whichever of the two keys carries
+ * it. LangChain accepts `modelName` as an alias for `model` and this package
+ * writes both (see `buildSummarizationClientConfig`), while hosts configure
+ * agents through either. Reading only one key therefore does not fail loudly:
+ * it reports an unconfigured model, and every caller here treats that as a cue
+ * to fall back to a default, so a Claude agent configured through the alias is
+ * silently handled as something else.
+ */
+export function resolveClientOptionsModel(
+  clientOptions: t.ClientOptions | undefined
+): string | undefined {
+  const options = clientOptions as
+    | { model?: unknown; modelName?: unknown }
+    | undefined;
+  if (typeof options?.model === 'string' && options.model !== '') {
+    return options.model;
+  }
+  if (typeof options?.modelName === 'string' && options.modelName !== '') {
+    return options.modelName;
+  }
+  return undefined;
+}
+
 /**
  * Returns the correct key for setting max output tokens on the model
  * constructor options.  Google/Vertex use `maxOutputTokens`, all others