@librechat/agents 3.7.8 → 3.7.9

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

@@ -6,10 +6,6 @@ import type { HookRegistry } from '@/hooks';
 import type { OnChunk } from '@/llm/invoke';
 import type * as t from '@/types';
 import { type PromptCacheTtl } from '@/messages/cache';
-/** Structured checkpoint prompt for fresh summarization (no prior summary). */
-export declare const DEFAULT_SUMMARIZATION_PROMPT = "Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.\n\nDon't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.\n\n## Checkpoint\n\n## Goal\nWhat I asked you to do and any sub-goals you identified.\n\n## Constraints & Preferences\nAny rules, preferences, or configuration I established.\n\n## Progress\n### Done\n- What you completed and the outcomes\n\n### In Progress\n- What you're currently working on\n\n## Key Decisions\nDecisions you made and why.\n\n## Next Steps\nConcrete task actions remaining, in priority order.\n\n## Critical Context\nExact identifiers, names, error messages, URLs, and details you need to preserve verbatim.\n\nRules:\n- Record what you did and observed, don't judge or re-evaluate it\n- For each tool call: the tool name, key inputs, and the outcome\n- Preserve exact identifiers, names, errors, and references verbatim\n- Short declarative sentences\n- Skip empty sections";
-/** Prompt for re-compaction when a prior summary exists. */
-export declare const DEFAULT_UPDATE_SUMMARIZATION_PROMPT = "Hold on again, update your checkpoint. Merge the new messages into your existing checkpoint and give me a single consolidated replacement.\n\nKeep it roughly the same length as your last checkpoint. Compress older details to make room for what's new, don't just append. Give recent actions more detail, compress older items to one-liners.\n\nDon't fact-check or second-guess anything, your tool results are ground truth. If a tool result appears truncated, that's just a display artifact: the tool executed fully. Only the checkpoint, don't respond to me or continue the conversation.\n\nRules:\n- Merge new progress into existing sections, don't duplicate headers\n- Compress older completed items into one-line entries\n- Move items from \"In Progress\" to \"Done\" when you completed them\n- Update \"Next Steps\" to reflect current task priorities.\n- For each new tool call: the tool name, key inputs, and the outcome\n- Preserve exact identifiers, names, errors, and references verbatim\n- Skip empty sections";
 interface CreateSummarizeNodeParams {
     agentContext: AgentContext;
     graph: {

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

@@ -3,6 +3,8 @@ import type { CompactionSemanticIndex } from '@/types';
 export { COMPACTION_SEMANTIC_INDEX_LIMITS } from '@/common';
 /** Records producer-side omissions without retaining the discarded entries. */
 export declare function setCompactionSemanticIndexProvidedEntryCount(index: CompactionSemanticIndex, providedEntryCount: number): void;
+/** Reads producer-side cardinality without exposing snapshot bookkeeping. */
+export declare function getCompactionSemanticIndexProvidedEntryCount(index: CompactionSemanticIndex): number;
 export type RenderedCompactionSemanticIndex = {
     appendix: string;
     providedEntryCount: number;

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

@@ -0,0 +1,25 @@
+/**
+ * Summarization primitives shared by the in-run summarize node and by callers
+ * that compact a conversation outside a run. Kept apart from `node.ts` so the
+ * package can export them without exporting the graph node itself.
+ */
+/**
+ * Wraps a persisted summary in the carrier it is re-injected as, ahead of the
+ * messages that survived compaction.
+ *
+ * A stored summary costs what this returns, not what its body costs, so a
+ * caller budgeting for one measures this rather than adding a remembered
+ * constant to the bare text. The wrapper alone is ~48 tokens on `o200k_base`
+ * and more on Anthropic: too much to leave out of a context calculation, and
+ * too easy to get wrong from memory once the instruction is edited.
+ */
+export declare function buildSummaryCarrierText(summaryText: string): string;
+/** Structured checkpoint prompt for fresh summarization (no prior summary). */
+export declare const DEFAULT_SUMMARIZATION_PROMPT = "Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.\n\nDon't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.\n\n## Checkpoint\n\n## Goal\nWhat I asked you to do and any sub-goals you identified.\n\n## Constraints & Preferences\nAny rules, preferences, or configuration I established.\n\n## Progress\n### Done\n- What you completed and the outcomes\n\n### In Progress\n- What you're currently working on\n\n## Key Decisions\nDecisions you made and why.\n\n## Next Steps\nConcrete task actions remaining, in priority order.\n\n## Critical Context\nExact identifiers, names, error messages, URLs, and details you need to preserve verbatim.\n\nRules:\n- Record what you did and observed, don't judge or re-evaluate it\n- For each tool call: the tool name, key inputs, and the outcome\n- Preserve exact identifiers, names, errors, and references verbatim\n- Short declarative sentences\n- Skip empty sections";
+/** Prompt for re-compaction when a prior summary exists. */
+export declare const DEFAULT_UPDATE_SUMMARIZATION_PROMPT = "Hold on again, update your checkpoint. Merge the new messages into your existing checkpoint and give me a single consolidated replacement.\n\nKeep it roughly the same length as your last checkpoint. Compress older details to make room for what's new, don't just append. Give recent actions more detail, compress older items to one-liners.\n\nDon't fact-check or second-guess anything, your tool results are ground truth. If a tool result appears truncated, that's just a display artifact: the tool executed fully. Only the checkpoint, don't respond to me or continue the conversation.\n\nRules:\n- Merge new progress into existing sections, don't duplicate headers\n- Compress older completed items into one-line entries\n- Move items from \"In Progress\" to \"Done\" when you completed them\n- Update \"Next Steps\" to reflect current task priorities.\n- For each new tool call: the tool name, key inputs, and the outcome\n- Preserve exact identifiers, names, errors, and references verbatim\n- Skip empty sections";
+export declare function separateSummarizationParameters(parameters: Record<string, unknown>): {
+    llmParams: Record<string, unknown>;
+    maxSummaryTokens?: number;
+};
+export declare function buildSummarizationInstruction(promptText: string, updatePromptText: string | undefined, priorSummaryText?: string, semanticIndexAppendix?: string): string;

package/dist/types/types/run.d.ts

@@ -233,6 +233,14 @@ export type RunConfig = {
      * block to prevent leaks.
      */
     hooks?: HookRegistry;
+    /**
+     * Maximum number of times a `Stop` hook may keep this Run warm by returning
+     * `decision: 'block'` with messages to inject. Defaults to
+     * `DEFAULT_MAX_STOP_CONTINUATIONS`; non-finite values use the default and
+     * values at or below zero disable terminal continuation while preserving the
+     * final Stop notification.
+     */
+    maxStopContinuations?: number;
     /**
      * Opt-in cooperative preemption for this run. Requires a `hooks` registry
      * with a `PreemptBoundary` matcher — the seal only stops the stream, the

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

@@ -87,6 +87,12 @@ export interface RunStepResumeState {
     version: 1;
     revision: number;
     nextIndex: number;
+    /** Warm terminal continuations already admitted for this execution. */
+    stopContinuationCount?: number;
+    /** Identifies the fresh execution that owns this continuation lifecycle. */
+    stopContinuationExecutionId?: string;
+    /** Distinguishes LangGraph event keys when a warm continuation restarts steps. */
+    streamSegment?: number;
     toolCallSteps: Array<{
         toolCallId: string;
         stepId: string;

package/dist/types/types/summarize.d.ts

@@ -62,6 +62,12 @@ export type CompactionReasoningSemanticIndexEntry = CompactionSemanticIndexEntry
  */
 export type CompactionSemanticIndexEntry = CompactionToolSemanticIndexEntry | CompactionActivitySemanticIndexEntry | CompactionReasoningSemanticIndexEntry;
 export type CompactionSemanticIndex = readonly CompactionSemanticIndexEntry[];
+/** Serializable continuation state for a bounded compaction semantic index. */
+export type CompactionSemanticIndexSnapshot = {
+    entries: CompactionSemanticIndex;
+    /** Cumulative entries supplied before validation and bounded retention. */
+    providedEntryCount: number;
+};
 export type SummarizationConfig = {
     provider?: ProviderName;
     model?: string;

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

@@ -69,6 +69,15 @@ export declare function getTokenCountForMessage(message: BaseMessage, getTokenCo
  * computed as a single rounded product of the summed raw counts.
  */
 export declare function apportionTokenCounts(rawCounts: Record<string, number>, multiplier: number, targetTotal: number): Record<string, number>;
+/**
+ * Encoding a counter measures in, for counters built here.
+ *
+ * `undefined` for a counter the host supplied itself: unknown, not wrong. A
+ * caller that needs a count in a specific encoding can therefore tell "counts
+ * in the encoding I need" from "counts in a different one" without treating
+ * every foreign counter as suspect.
+ */
+export declare function encodingOfTokenCounter(tokenCounter: (message: BaseMessage) => number): EncodingName | undefined;
 /**
  * Creates a token counter function using the specified encoding.
  * Lazily loads the encoding data on first use via dynamic import.

package/package.json

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

package/src/agents/AgentContext.ts

@@ -52,6 +52,7 @@ import {
 import { isTokenCounterCacheCompatible } from '@/llm/tokenCounterCacheCompatibility';
 import { snapshotCompactionSemanticIndex } from '@/summarization/semanticIndex';
 import { createExactTokenCountCache } from '@/llm/contextPressureMeter';
+import { buildSummaryCarrierText } from '@/summarization/shared';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { apportionTokenCounts } from '@/utils/tokens';
 import { isThinkingEnabled } from '@/llm/request';
@@ -967,11 +968,7 @@ export class AgentContext {
   private buildSummaryHumanMessage(
     promptCacheProvider: PromptCacheProvider | undefined
   ): HumanMessage {
-    const wrappedSummary =
-      '<summary>\n' +
-      (this.summaryText as string) +
-      '\n</summary>\n\n' +
-      'This is your own checkpoint: you wrote it to preserve context after compaction. Pick up where you left off based on the summary above. Do not repeat prior tasks, information or acknowledge this checkpoint message directly.';
+    const wrappedSummary = buildSummaryCarrierText(this.summaryText as string);
 
     if (promptCacheProvider !== Providers.ANTHROPIC) {
       return new HumanMessage(wrappedSummary);

package/src/common/constants.ts

@@ -20,6 +20,14 @@ export const DEFAULT_TOOL_TOKEN_MULTIPLIER = 1.4;
  */
 export const DEFAULT_MAX_SEALS = 8;
 
+/**
+ * Default ceiling on Stop-hook continuations within one Run. A blocking Stop
+ * hook can keep a naturally terminal run warm by injecting another user turn;
+ * the ceiling prevents a faulty hook or continuously arriving input from
+ * keeping one processStream call alive forever.
+ */
+export const DEFAULT_MAX_STOP_CONTINUATIONS = 8;
+
 /**
  * Per-hook timeout for `PreemptBoundary`, deliberately far above
  * `DEFAULT_HOOK_TIMEOUT_MS`. A host drain has already popped its queue and

package/src/graphs/Graph.ts

@@ -771,6 +771,9 @@ export abstract class Graph<
   contentData: t.RunStep[] = [];
   protected nextContentIndex = 0;
   protected runStepStateRevision = 0;
+  protected stopContinuationCount = 0;
+  protected stopContinuationExecutionId = '';
+  protected streamSegment = 0;
   stepKeyIds: Map<string, string[]> = new Map<string, string[]>();
   contentIndexMap: Map<string, number> = new Map();
   toolCallStepIds: Map<string, string> = new Map();
@@ -900,6 +903,9 @@ export abstract class Graph<
     this.contentData = [];
     this.nextContentIndex = 0;
     this.runStepStateRevision = 0;
+    this.stopContinuationCount = 0;
+    this.stopContinuationExecutionId = '';
+    this.streamSegment = 0;
     this.contentIndexMap = new Map();
     this.stepKeyIds = new Map();
     this.toolCallStepIds.clear();
@@ -1537,6 +1543,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.cachedRunMessages = undefined;
     this.cachedDiscoveredTools = undefined;
     this.config = resetIfNotEmpty(this.config, undefined);
+    this.stopContinuationCount = 0;
+    this.stopContinuationExecutionId = '';
+    this.streamSegment = 0;
     if (keepContent !== true) {
       this.contentData = resetIfNotEmpty(this.contentData, []);
       this.nextContentIndex = 0;
@@ -1835,6 +1844,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       version: 1,
       revision: this.runStepStateRevision,
       nextIndex: this.nextContentIndex,
+      stopContinuationCount: this.stopContinuationCount,
+      ...(this.stopContinuationExecutionId === ''
+        ? {}
+        : {
+          stopContinuationExecutionId: this.stopContinuationExecutionId,
+        }),
+      streamSegment: this.streamSegment,
       toolCallSteps: [...this.toolCallStepIds].map(([toolCallId, stepId]) => ({
         toolCallId,
         stepId,
@@ -1854,6 +1870,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
     this.nextContentIndex = state.nextIndex;
     this.runStepStateRevision = state.revision;
+    this.stopContinuationCount = state.stopContinuationCount ?? 0;
+    this.stopContinuationExecutionId =
+      state.stopContinuationExecutionId ?? '';
+    this.streamSegment = state.streamSegment ?? 0;
     for (const { toolCallId, stepId } of state.toolCallSteps) {
       this.toolCallStepIds.set(toolCallId, stepId);
     }
@@ -1888,6 +1908,30 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     return undefined;
   }
 
+  getStopContinuationCount(): number {
+    return this.stopContinuationCount;
+  }
+
+  setStopContinuationCount(count: number): void {
+    this.stopContinuationCount = count;
+  }
+
+  getStopContinuationExecutionId(): string {
+    return this.stopContinuationExecutionId;
+  }
+
+  startStopContinuationExecution(executionId: string): void {
+    this.stopContinuationExecutionId = executionId;
+  }
+
+  getStreamSegment(): number {
+    return this.streamSegment;
+  }
+
+  advanceStreamSegment(): void {
+    this.streamSegment += 1;
+  }
+
   /**
    * Derives the same lane key `dispatchRunStep` stamps as `runStep.agentId`.
    * The multi-agent check gates the lookup because `getAgentContext` signals
@@ -2336,6 +2380,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       metadata.langgraph_node as string,
       metadata.langgraph_step as number,
       checkpointNs,
+      this.streamSegment,
     ];
 
     return keyList;

package/src/hooks/HookRegistry.ts

@@ -43,7 +43,9 @@ type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
 /**
  * Events whose hooks can change a tool call's input or output. Presence of
  * any of these disables eager tool execution and early completion emission;
- * observation-only events (`PostToolBatch`, `Stop`, telemetry hooks) do not.
+ * hooks that cannot rewrite a tool result (`PostToolBatch`, `Stop`, telemetry
+ * hooks) do not. A Stop hook may continue the Run, but only after every tool
+ * result in the terminal graph segment is already authoritative.
  */
 const RESULT_ALTERING_HOOK_EVENTS = [
   'PreToolUse',

package/src/hooks/executeHooks.ts

@@ -313,6 +313,9 @@ function applyAggregatedResult(
   target.additionalContexts.push(...source.additionalContexts);
   target.injectedMessages.push(...source.injectedMessages);
   target.errors.push(...source.errors);
+  if (source.hasHookFailures === true) {
+    target.hasHookFailures = true;
+  }
   if (source.decision != null) {
     applyToolDecision(target, source.decision, source.reason);
   }
@@ -347,6 +350,19 @@ function combineAggregatedResults(
   return combined;
 }
 
+/** Deterministically fold results from serialized hook phases. */
+export function mergeAggregatedHookResults(
+  ...results: Array<AggregatedHookResult | undefined>
+): AggregatedHookResult | undefined {
+  let combined: AggregatedHookResult | undefined;
+  for (const result of results) {
+    if (result != null) {
+      combined = combineAggregatedResults(combined, result);
+    }
+  }
+  return combined;
+}
+
 function createPendingApprovalReplay(
   approvalResult: AggregatedHookResult,
   pendingApproval: AggregatedHookResult | undefined,
@@ -377,6 +393,7 @@ function fold(outcomes: readonly HookOutcome[]): {
   for (const outcome of outcomes) {
     const isOnceMatcher = outcome.matcher.once === true;
     if (outcome.error !== null) {
+      aggregated.hasHookFailures = true;
       if (outcome.matcher.internal !== true) {
         aggregated.errors.push(outcome.error);
       }
@@ -455,8 +472,9 @@ function fold(outcomes: readonly HookOutcome[]): {
  * ## Internal matchers
  *
  * A matcher with `internal: true` is excluded from both the `errors` array
- * and the logger output. Use it for infrastructure hooks whose failures
- * should not pollute user-visible diagnostics.
+ * and the logger output. `hasHookFailures` still records that the call was
+ * not fully successful, so fail-closed infrastructure boundaries can reject
+ * without exposing the suppressed diagnostic.
  *
  * ## Once semantics — atomic at-most-once
  *

package/src/hooks/index.ts

@@ -9,7 +9,11 @@
 // `StandardGraph.createCallModel` (PreemptBoundary).
 export { HookRegistry } from './HookRegistry';
 export type { HookHaltSignal } from './HookRegistry';
-export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
+export {
+  executeHooks,
+  mergeAggregatedHookResults,
+  DEFAULT_HOOK_TIMEOUT_MS,
+} from './executeHooks';
 /**
  * Feature probe for hosts: hook outputs support `injectedMessages`
  * (per-message graph-state injection at the `PostToolBatch` boundary).
@@ -28,6 +32,11 @@ export const HOOK_INJECTED_MESSAGES_CAPABLE = true;
  * the user as a dead button rather than as an unsupported feature.
  */
 export const HOOK_PREEMPT_BOUNDARY_CAPABLE = true;
+/**
+ * Feature probe for hosts: a blocking `Stop` hook can inject queued messages
+ * and continue within the same `Run.processStream` lifecycle.
+ */
+export const HOOK_STOP_CONTINUATION_CAPABLE = true;
 export {
   matchesQuery,
   hasNestedQuantifier,
@@ -71,6 +80,7 @@ export type {
   SubagentStartHookInput,
   SubagentStopHookInput,
   StopHookInput,
+  StopFinalizeHookInput,
   StopFailureHookInput,
   PreCompactHookInput,
   PostCompactHookInput,
@@ -85,6 +95,7 @@ export type {
   SubagentStartHookOutput,
   SubagentStopHookOutput,
   StopHookOutput,
+  StopFinalizeHookOutput,
   StopFailureHookOutput,
   PreCompactHookOutput,
   PostCompactHookOutput,

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