@librechat/agents 3.7.8 → 3.7.10

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/tools/search/metrics.d.ts

@@ -0,0 +1,15 @@
+import type * as t from './types';
+export declare const classifyFailure: (message?: string) => string;
+/**
+ * Creates the counter set for one `web_search` call.
+ *
+ * The pipeline reranks once per scraped source and scrapes once per link, so
+ * logging at those points scales the log with the result count. Every phase
+ * records into fixed-width counters instead and {@link t.SearchMetrics.flush}
+ * emits one line per phase, at the highest severity that phase reached.
+ *
+ * @param autoFlush emit on every record, for a caller with no enclosing search
+ * to fold into (a reranker used directly). Recording is synchronous, so the
+ * record/flush/reset cycle can never interleave with a concurrent call.
+ */
+export declare const createSearchMetrics: (logger: t.Logger, autoFlush?: boolean) => t.SearchMetrics;

package/dist/types/tools/search/rerankers.d.ts

@@ -2,11 +2,33 @@ import type * as t from './types';
 export declare abstract class BaseReranker {
     protected apiKey: string | undefined;
     protected logger: t.Logger;
+    /** Public so a caller that fails before reaching `rerank` can still
+     * attribute the attempt to the configured reranker. */
+    abstract readonly provider: string;
+    private ownMetrics?;
     constructor(logger?: t.Logger);
-    abstract rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+    /**
+     * A search reranks once per scraped source, so nothing here logs per call:
+     * every exit records one observation through `metrics` and the enclosing
+     * search emits a single summary. `metrics` is optional only for direct use
+     * of a reranker, which falls back to an auto-flushing collector.
+     */
+    abstract rerank(query: string, documents: string[], topK?: number, metrics?: t.SearchMetrics): Promise<t.Highlight[]>;
     protected getDefaultRanking(documents: string[], topK: number): t.Highlight[];
+    /** A direct caller has no enclosing search to fold into, so one
+     * auto-flushing collector per instance emits that call's summary on its
+     * own; record and flush run synchronously, so concurrent calls on the same
+     * instance cannot share a total. */
+    private localMetrics;
+    /** Opens the per-call state every exit path records against. */
+    protected beginRerank(documents: string[], topK: number, metrics?: t.SearchMetrics): t.RerankRun;
+    private record;
+    protected complete(run: t.RerankRun, highlights: t.Highlight[]): t.Highlight[];
+    /** Records the call as a fallback and returns the candidates' input order. */
+    protected fallback(run: t.RerankRun, reason: t.RerankFallback, error?: t.SafeErrorLog): t.Highlight[];
 }
 export declare class JinaReranker extends BaseReranker {
+    readonly provider = "jina";
     private apiUrl;
     private timeout;
     private httpAgent?;
@@ -17,9 +39,10 @@ export declare class JinaReranker extends BaseReranker {
         timeout?: number;
         logger?: t.Logger;
     } & t.HttpAgentConfig);
-    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+    rerank(query: string, documents: string[], topK?: number, metrics?: t.SearchMetrics): Promise<t.Highlight[]>;
 }
 export declare class CohereReranker extends BaseReranker {
+    readonly provider = "cohere";
     private timeout;
     private httpAgent?;
     private httpsAgent?;
@@ -28,7 +51,7 @@ export declare class CohereReranker extends BaseReranker {
         timeout?: number;
         logger?: t.Logger;
     } & t.HttpAgentConfig);
-    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+    rerank(query: string, documents: string[], topK?: number, metrics?: t.SearchMetrics): Promise<t.Highlight[]>;
 }
 /**
  * Calls the public `danny-avila/rag_api` `/v1/rerank` endpoint (the
@@ -40,6 +63,7 @@ export declare class CohereReranker extends BaseReranker {
  * to the candidates' original order via {@link BaseReranker.getDefaultRanking}.
  */
 export declare class RagApiReranker extends BaseReranker {
+    readonly provider = "rag-api";
     private baseUrl?;
     private tokenSupplier?;
     private profile;
@@ -53,11 +77,12 @@ export declare class RagApiReranker extends BaseReranker {
         timeout?: number;
         logger?: t.Logger;
     } & t.HttpAgentConfig);
-    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+    rerank(query: string, documents: string[], topK?: number, metrics?: t.SearchMetrics): Promise<t.Highlight[]>;
 }
 export declare class InfinityReranker extends BaseReranker {
+    readonly provider = "infinity";
     constructor(logger?: t.Logger);
-    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+    rerank(query: string, documents: string[], topK?: number, metrics?: t.SearchMetrics): Promise<t.Highlight[]>;
 }
 /**
  * Creates the appropriate reranker based on type and configuration

package/dist/types/tools/search/tool.d.ts

@@ -24,7 +24,7 @@ export declare function resolveSearchOutcome(data: t.SearchResultData, query: st
  * Executes parallel searches and merges the results,
  * deduplicating top stories by link
  */
-export declare function executeParallelSearches({ searchAPI, query, date, country, safeSearch, images, videos, news, logger, }: {
+export declare function executeParallelSearches({ searchAPI, query, date, country, safeSearch, images, videos, news, logger, provider, metrics, }: {
     searchAPI: ReturnType<typeof createSearchAPI>;
     query: string;
     date?: DATE_RANGE;
@@ -34,5 +34,11 @@ export declare function executeParallelSearches({ searchAPI, query, date, countr
     videos: boolean;
     news: boolean;
     logger: t.Logger;
+    /** Labels the provider in the run summary. Optional so the pre-existing
+     * call contract still holds for callers outside this package. */
+    provider?: string;
+    /** Collector owned by the caller. Without one, this call opens and flushes
+     * its own, so a direct caller still gets the single summary line. */
+    metrics?: t.SearchMetrics;
 }): Promise<t.SearchResult>;
 export declare const createSearchTool: (config?: t.SearchToolConfig) => DynamicStructuredTool;

package/dist/types/tools/search/types.d.ts

@@ -291,7 +291,9 @@ export interface JinaRerankerResult {
 }
 export interface JinaRerankerResponse {
     model: string;
-    usage: {
+    /** Telemetry only, and absent from some Jina-compatible endpoints — never
+     * dereference it on a path that would discard a usable ranking. */
+    usage?: {
         total_tokens: number;
     };
     results: JinaRerankerResult[];
@@ -303,12 +305,13 @@ export interface CohereRerankerResult {
 export interface CohereRerankerResponse {
     results: CohereRerankerResult[];
     id: string;
-    meta: {
-        api_version: {
+    /** Telemetry only; see {@link JinaRerankerResponse.usage}. */
+    meta?: {
+        api_version?: {
             version: string;
             is_experimental: boolean;
         };
-        billed_units: {
+        billed_units?: {
             search_units: number;
         };
     };
@@ -343,6 +346,81 @@ export interface RagApiRerankResponse {
 }
 export type SafeSearchLevel = 0 | 1 | 2;
 export type Logger = WinstonLogger;
+/** Compact, redacted view of a thrown error, safe to hand to a logger. */
+export interface SafeErrorLog {
+    message: string;
+    name?: string;
+    code?: string;
+    status?: number;
+    method?: string;
+    url?: string;
+    responseDataSummary?: string;
+    value?: string;
+}
+/** Why a rerank returned the candidates' original order instead of a ranking. */
+export type RerankFallback = 'no_api_key' | 'no_base_url' | 'no_token_supplier' | 'bad_response' | 'invalid_results' | 'chunk_error' | 'placeholder' | 'error';
+/** One provider query. `results` is the row count that query contributed. */
+export interface SearchObservation {
+    provider: string;
+    type: string;
+    results: number;
+    durationMs: number;
+    error?: string;
+    /** The query rejected rather than reporting failure in its response. Those
+     * were logged at error level before they were aggregated, so the summary
+     * has to carry the distinction to keep that severity. */
+    thrown?: boolean;
+}
+/** One scraped link. A failure carries `error`; a success carries the sizes
+ * the scrape produced, so the summary can report both without a second pass. */
+export interface ScrapeObservation {
+    url: string;
+    chars?: number;
+    highlights?: number;
+    error?: string;
+}
+/** One reranker round trip. A search reranks once per scraped source, so
+ * these fold into a single summary rather than logging per source. */
+export interface RerankObservation {
+    provider: string;
+    chunks: number;
+    results: number;
+    durationMs: number;
+    model?: string;
+    /** Provider-reported usage: Jina tokens, Cohere billed search units. */
+    units?: number;
+    /** Chunks a provider candidate cap dropped before submission. */
+    dropped?: number;
+    /** Set only when a provider cap reduced the requested result count, so a
+     * search returning fewer highlights than configured says why. */
+    topK?: number;
+    topKLimit?: number;
+    reason?: RerankFallback;
+    error?: SafeErrorLog;
+}
+/** Per-rerank state threaded from the start of a call to whichever exit it
+ * takes, so every path records exactly one observation. */
+export interface RerankRun {
+    metrics: SearchMetrics;
+    documents: string[];
+    topK: number;
+    startedAt: number;
+    model?: string;
+    units?: number;
+    dropped?: number;
+    topKLimit?: number;
+}
+/**
+ * Fold-as-you-go counters for one `web_search` call. Recording is O(1) and
+ * allocation-free past a bounded reason map; {@link SearchMetrics.flush}
+ * emits at most one line per phase that actually ran.
+ */
+export interface SearchMetrics {
+    recordSearch(observation: SearchObservation): void;
+    recordScrape(observation: ScrapeObservation): void;
+    recordRerank(observation: RerankObservation): void;
+    flush(): void;
+}
 export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
     tavilyScraperOptions?: TavilyScraperConfig;
     crwScraperOptions?: CrwScraperConfig;
@@ -572,6 +650,9 @@ export interface FirecrawlScraperConfig extends BaseSearchProviderConfig {
     onlyMainContent?: boolean;
     changeTrackingOptions?: object;
 }
+/** Result kind a parallel sub-search covers; `web` is the untyped main
+ * search, which every provider serves without a `type` parameter. */
+export type SubSearchType = 'web' | 'images' | 'videos' | 'news';
 export type GetSourcesParams = {
     query: string;
     date?: DATE_RANGE;
@@ -870,6 +951,9 @@ export type ProcessSourcesFields = {
     news: boolean;
     proMode: boolean;
     onGetHighlights: SearchToolConfig['onGetHighlights'];
+    /** Collector owned by the caller; when omitted, one is created and flushed
+     * for this call so a direct `processSources` still summarizes itself. */
+    metrics?: SearchMetrics;
 };
 export interface SearchToolSchema {
     type: 'object';

package/dist/types/tools/search/utils.d.ts

@@ -1,14 +1,6 @@
+import type { SafeErrorLog } from './types';
 import type * as t from './types';
-export interface SafeErrorLog {
-    message: string;
-    name?: string;
-    code?: string;
-    status?: number;
-    method?: string;
-    url?: string;
-    responseDataSummary?: string;
-    value?: string;
-}
+export type { SafeErrorLog } from './types';
 /**
  * Creates a default logger that maps to console methods
  * Uses a singleton pattern to avoid creating multiple instances

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.10",
   "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,