@librechat/agents 3.7.7 → 3.7.9

package/dist/types/hooks/types.d.ts

@@ -8,7 +8,7 @@ import type { InjectedMessage } from '@/types/tools';
  * `docs/hooks-design-report.md` §3.2 for the mapping to existing
  * `@librechat/agents` emission points.
  */
-export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreemptBoundary", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreemptBoundary", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFinalize", "StopFailure", "PreCompact", "PostCompact"];
 export declare const TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY = "__librechat_tool_approval_execution_scope";
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
@@ -174,7 +174,33 @@ 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 {
     hook_event_name: 'StopFailure';
@@ -203,7 +229,7 @@ export interface PostCompactHookInput extends BaseHookInput {
     messagesAfterCount: number;
 }
 /** Discriminated union of every hook input shape. */
-export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PreemptBoundaryHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
+export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PreemptBoundaryHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFinalizeHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
 /** Compile-time map from event name to its input shape. */
 export type HookInputByEvent = {
     RunStart: RunStartHookInput;
@@ -217,6 +243,7 @@ export type HookInputByEvent = {
     SubagentStart: SubagentStartHookInput;
     SubagentStop: SubagentStopHookInput;
     Stop: StopHookInput;
+    StopFinalize: StopFinalizeHookInput;
     StopFailure: StopFailureHookInput;
     PreCompact: PreCompactHookInput;
     PostCompact: PostCompactHookInput;
@@ -238,10 +265,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. */
@@ -362,9 +390,16 @@ 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;
 export type PostCompactHookOutput = BaseHookOutput;
@@ -381,12 +416,13 @@ export type HookOutputByEvent = {
     SubagentStart: SubagentStartHookOutput;
     SubagentStop: SubagentStopHookOutput;
     Stop: StopHookOutput;
+    StopFinalize: StopFinalizeHookOutput;
     StopFailure: StopFailureHookOutput;
     PreCompact: PreCompactHookOutput;
     PostCompact: PostCompactHookOutput;
 };
 /** Superset output shape used by the executor's fold loop. */
-export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PostToolBatchHookOutput | PreemptBoundaryHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
+export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PostToolBatchHookOutput | PreemptBoundaryHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFinalizeHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
 /**
  * A hook callback is a plain async function registered against a specific
  * event. The `signal` is always supplied by `executeHooks` and combines the
@@ -494,6 +530,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/dist/types/langfuse.d.ts

@@ -25,6 +25,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
@@ -51,7 +53,7 @@ export declare function createLangfuseTraceMetadata({ messageId, parentMessageId
 export declare function getLangfuseTraceName(traceMetadata?: LangfuseTraceMetadata, fallback?: string): string;
 export declare function shouldCreateLangfuseHandler(langfuse?: t.LangfuseConfig): boolean;
 export declare function createLegacyLangfuseHandler(params: LangfuseHandlerParams): CallbackHandler;
-export declare function createLangfuseHandler({ langfuse, userId, sessionId, traceMetadata, tags, traceIdSeed, traceAnchor, agentId, parentSpanContext, inheritTraceIdentity, runId, toolOutputTracing, traceName, }: AgentLangfuseHandlerParams): CallbackHandler | undefined;
+export declare function createLangfuseHandler({ langfuse, userId, sessionId, traceMetadata, tags, traceIdSeed, traceAnchor, agentId, parentSpanContext, inheritTraceIdentity, runId, deferRootRunId, toolOutputTracing, traceName, }: AgentLangfuseHandlerParams): CallbackHandler | undefined;
 export declare function withLangfuseAttributes<T>(params: LangfuseAttributeParams, action: () => T): T;
 export declare function hasExplicitLangfuseConfig(contexts: Iterable<{
     langfuse?: t.LangfuseConfig;

package/dist/types/llm/fake.d.ts

@@ -11,15 +11,25 @@ export declare class FakeChatModel extends FakeListChatModel {
     private splitStrategy;
     private toolCalls;
     private addedToolCalls;
-    constructor({ responses, sleep, emitCustomEvent, splitStrategy, toolCalls, }: {
+    /**
+     * Attached to the last streamed chunk of every response, mirroring a real
+     * provider's terminal `finish_reason`/`stop_reason` on `generationInfo`.
+     * Lets truncation-path tests (`getTruncationStopReason`) drive a genuine
+     * `Run`/`StandardGraph` without a live provider. `undefined` (the
+     * default) reproduces the previous behavior exactly: no metadata on any
+     * chunk.
+     */
+    private finalChunkGenerationInfo?;
+    constructor({ responses, sleep, emitCustomEvent, splitStrategy, toolCalls, finalChunkGenerationInfo, }: {
         responses: string[];
         sleep?: number;
         emitCustomEvent?: boolean;
         splitStrategy?: SplitStrategy;
         toolCalls?: ToolCall[];
+        finalChunkGenerationInfo?: Record<string, unknown>;
     });
     private splitText;
-    _createResponseChunk(text: string, tool_call_chunks?: ToolCallChunk[]): ChatGenerationChunk;
+    _createResponseChunk(text: string, tool_call_chunks?: ToolCallChunk[], responseMetadata?: Record<string, unknown>): ChatGenerationChunk;
     _streamResponseChunks(_messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
 export declare function createFakeStreamingLLM({ responses, sleep, splitStrategy, toolCalls, }: {

package/dist/types/llm/request.d.ts

@@ -5,6 +5,16 @@ import type * as t from '@/types';
  * and OpenAI-compat (modelKwargs.thinking).
  */
 export declare function isThinkingEnabled(provider: t.ProviderName, clientOptions?: t.ClientOptions): boolean;
+/**
+ * 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 declare function resolveClientOptionsModel(clientOptions: t.ClientOptions | undefined): string | undefined;
 /**
  * Returns the correct key for setting max output tokens on the model
  * constructor options.  Google/Vertex use `maxOutputTokens`, all others

package/dist/types/messages/format.d.ts

@@ -1,7 +1,7 @@
 import { AIMessage, ToolMessage, BaseMessage, HumanMessage, SystemMessage } from '@langchain/core/messages';
 import type { MessageContentImageUrl } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { MessageContentComplex, TPayload, ProviderName } from '@/types';
+import type { MessageContentComplex, TPayload, ProviderName, CompactionSemanticIndex, CompactionSemanticIndexSnapshot } from '@/types';
 import { Providers } from '@/common';
 interface MediaMessageParams {
     message: {
@@ -89,7 +89,7 @@ interface LangChainMessage {
  * @returns - The formatted LangChain message.
  */
 export declare const formatFromLangChain: (message: LangChainMessage) => Record<string, any>;
-interface FormatAgentMessagesOptions {
+export interface FormatAgentMessagesOptions {
     provider?: ProviderName;
     /** Emit flattenable text content as the joined string the legacy-content
      *  projection would produce, so the per-request `formatContentStrings` pass
@@ -105,6 +105,17 @@ interface FormatAgentMessagesOptions {
      *  historical `skill` tool_calls are not reconstructed into a HumanMessage,
      *  so the same SKILL.md body is not injected twice in one request. */
     skipSkillBodyNames?: Set<string>;
+    /** Derive bounded compaction guidance during the formatter's existing
+     *  persisted-content analysis. Tool intents are accepted only for names
+     *  the host identifies as semantic-label fields; business `intent`
+     *  parameters must remain ordinary tool input. */
+    compactionSemanticIndex?: {
+        /** Previously committed, serializable guidance to evolve with entries
+         *  derived from this payload. The formatter snapshots and validates
+         *  caller-owned data before scanning the new messages. */
+        baseSnapshot?: CompactionSemanticIndexSnapshot;
+        intentToolNames?: ReadonlySet<string>;
+    };
 }
 /**
  * Groups content parts by agent and formats them with agent labels
@@ -148,6 +159,10 @@ export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap
     /** When a positional summary boundary sliced content from a message, the token
      *  count was proportionally reduced. Returned so the caller can log it. */
     boundaryTokenAdjustment?: SummaryTokenAdjustment;
+    /** Bounded semantic guidance derived during persisted-content analysis. */
+    compactionSemanticIndex?: CompactionSemanticIndex;
+    /** Serializable continuation state for incrementally evolving the index. */
+    compactionSemanticIndexSnapshot?: CompactionSemanticIndexSnapshot;
 };
 /**
  * Adds a value at key 0 for system messages and shifts all key indices by one in an indexTokenCountMap.

package/dist/types/run.d.ts

@@ -1,5 +1,5 @@
-import { Command } from '@langchain/langgraph';
 import { BaseMessage } from '@langchain/core/messages';
+import { Command } from '@langchain/langgraph';
 import type { MessageContentComplex } from '@langchain/core/messages';
 import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -19,6 +19,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private toolExecution?;
     private subagentUsageSink?;
     private preemption?;
+    private maxStopContinuations;
     private streamLimits?;
     private subagentTasks?;
     private indexTokenCountMap?;
@@ -134,6 +135,15 @@ export declare class Run<_T extends t.BaseGraphState> {
      */
     getPreemptStats(): t.PreemptStats;
     getToolCount(): number;
+    /**
+     * True when the run's last turn ended at `END` because the provider hit
+     * its output token ceiling while producing plain text/reasoning — no tool
+     * call, so `assertNotTruncatedToolCall` never sees it and the graph reads
+     * the turn as an ordinary completion. Hosts check this alongside
+     * `getPreemptStats()` / `getHaltReason()` to decide whether to persist the
+     * response as unfinished instead of a silently truncated "complete" one.
+     */
+    getOutputTruncated(): boolean;
     /**
      * Creates a custom event callback handler that intercepts custom events
      * and processes them through our handler registry instead of EventStreamCallbackHandler
@@ -175,13 +185,16 @@ export declare class Run<_T extends t.BaseGraphState> {
      */
     getInterrupt<TPayload = t.HumanInterruptPayload>(): t.RunInterruptResult<TPayload> | undefined;
     /**
-     * Returns the reason a hook halted the run via
-     * `preventContinuation: true`, or `undefined` if no hook halted.
+     * Returns why the run ended without a natural completion, or `undefined`
+     * when it completed normally. Reasons include hook- and prompt-driven
+     * halts, `preempt_incomplete` when a cooperative seal ended the turn
+     * without continuation content, and `output_truncated` when the provider
+     * stopped a plain-text/reasoning response at its output-token ceiling.
      *
      * Hosts inspect this after `processStream` returns to distinguish a
-     * natural completion (`undefined`) from a hook-driven halt (a
-     * truthy string). Independent from `getInterrupt()` — a halted run
-     * has no interrupt; an interrupted run has no halt reason.
+     * natural completion from a terminal partial response. Independent from
+     * `getInterrupt()` — a halted run has no interrupt; an interrupted run has
+     * no halt reason.
      */
     getHaltReason(): string | undefined;
     /**

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

@@ -1,4 +1,10 @@
 import type { SummarizationTrigger } from '@/types';
+/**
+ * The summary-boundary seam a caller compacting outside a run needs. The two
+ * default prompts stay out of it: LibreChat's manual flow deliberately words
+ * its own, so exporting these would publish an API with no consumer.
+ */
+export { buildSummarizationInstruction, buildSummaryCarrierText, separateSummarizationParameters, } from './shared';
 /** For tests only. Resets the dedup set so warnings can be observed again. */
 export declare function _resetUnrecognizedTriggerWarnings(): void;
 /**

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

@@ -0,0 +1,21 @@
+import type { BaseMessage } from '@langchain/core/messages';
+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;
+    entryCount: number;
+    charCount: number;
+    omittedEntryCount: number;
+};
+/** Captures caller-owned data before graph execution can cross an await. */
+export declare function snapshotCompactionSemanticIndex(index: CompactionSemanticIndex | undefined): CompactionSemanticIndex | undefined;
+/**
+ * Produces a deterministic, bounded compaction appendix. Invalid, stale,
+ * pending, redacted, conflicting, and out-of-range entries fail closed.
+ */
+export declare function renderCompactionSemanticIndex(index: CompactionSemanticIndex | undefined, messagesToRefine: BaseMessage[]): RenderedCompactionSemanticIndex;

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/graph.d.ts

@@ -4,7 +4,7 @@ import type { START, StateGraph, StateGraphArgs } from '@langchain/langgraph';
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { SummarizationNodeInput, SummarizeCompleteEvent, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
+import type { SummarizationNodeInput, SummarizeCompleteEvent, CompactionSemanticIndex, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
 import type { RunStep, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecutionConfig, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
@@ -693,6 +693,14 @@ interface AgentInputFields {
     discoveredTools?: string[];
     summarizationEnabled?: boolean;
     summarizationConfig?: SummarizationConfig;
+    /**
+     * Optional host-supplied, user-visible guidance for compaction. The SDK
+     * validates, bounds, and scopes entries to the messages being compacted;
+     * raw conversation messages remain authoritative. Captured when the
+     * AgentContext is constructed; labels committed later in the same run are
+     * outside this construction-time interface.
+     */
+    compactionSemanticIndex?: CompactionSemanticIndex;
     /** Cross-run summary from a previous run, forwarded from formatAgentMessages.
      *  Injected into the dynamic system tail via AgentContext. */
     initialSummary?: {

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

@@ -29,6 +29,45 @@ export type RetainRecentConfig = {
      */
     tokens?: number;
 };
+export type CompactionSemanticIndexStatus = 'committed' | 'pending';
+type CompactionSemanticIndexEntryBase = {
+    /** Persisted message that owns the indexed content. */
+    sourceMessageId: string;
+    /** Zero-based content-part index within the persisted source message. */
+    sourceContentIndex: number;
+    /** Monotonic host revision for this logical entry. */
+    revision: number;
+    /** Only committed entries may guide compaction. */
+    status: CompactionSemanticIndexStatus;
+    /** User-visible semantic guidance. Hidden reasoning must never be supplied. */
+    text: string;
+    /** Omits the entry entirely when host policy redacts its source. */
+    redacted?: boolean;
+};
+export type CompactionToolSemanticIndexEntry = CompactionSemanticIndexEntryBase & {
+    type: 'tool_intent' | 'tool_outcome';
+    toolCallId: string;
+};
+export type CompactionActivitySemanticIndexEntry = CompactionSemanticIndexEntryBase & {
+    type: 'activity_phase';
+};
+export type CompactionReasoningSemanticIndexEntry = CompactionSemanticIndexEntryBase & {
+    type: 'reasoning_label';
+    /** Stable identity shared by every user-visible label revision. */
+    reasoningStepId: string;
+};
+/**
+ * Source-addressed navigation hints for the compaction model. Entries remain
+ * advisory: raw messages are always sent and remain authoritative.
+ */
+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;
@@ -86,6 +125,10 @@ export interface SummarizeStartEvent {
     messagesToRefineCount: number;
     /** Which summarization cycle this is (1-based, increments each time summarization fires) */
     summaryVersion: number;
+    /** Committed, source-valid semantic hints included in the request. */
+    semanticIndexEntryCount?: number;
+    /** Serialized semantic-index characters included in the request. */
+    semanticIndexCharCount?: number;
 }
 export interface SummarizeDeltaEvent {
     id: string;
@@ -99,3 +142,4 @@ export interface SummarizeCompleteEvent {
     summary?: SummaryContentBlock;
     error?: string;
 }
+export {};

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.7",
+  "version": "3.7.9",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -221,6 +221,7 @@
     "bench:provider-derivation": "tsx ./src/scripts/bench-provider-derivation.ts",
     "bench:provider-projection": "tsx ./src/scripts/bench-provider-request-projection.ts",
     "bench:execution-world": "tsx ./src/scripts/bench-execution-world.ts",
+    "bench:compaction-semantic-index": "tsx ./src/scripts/bench-compaction-semantic-index.ts",
     "probe:overflow": "tsx -r dotenv/config ./src/scripts/context-overflow-probe.ts",
     "subagent": "tsx -r dotenv/config ./src/scripts/multi-agent-subagent.ts",
     "subagent:events": "tsx -r dotenv/config ./src/scripts/subagent-event-driven-debug.ts",