@librechat/agents 3.7.6 → 3.7.8

package/dist/types/eventActor/types.d.ts

@@ -62,12 +62,129 @@ export type EventActorTerminalResult<TResult extends EventActorEvent> = {
     status: 'completed_no_action';
     result?: TResult;
 };
+/** JSON-safe interrupt descriptor retained with a suspended invocation fork. */
+export interface EventActorInterrupt<TPayload extends EventActorEvent = EventActorEvent> {
+    id: string;
+    payload: TPayload;
+}
+/**
+ * Nonterminal adapter outcome. The checkpoint must already contain the pause;
+ * the SDK publishes its authority through `suspend` before exposing it.
+ */
+export interface EventActorAdapterSuspendedResult<TPayload extends EventActorEvent = EventActorEvent> {
+    status: 'suspended';
+    checkpoint: EventActorCheckpointFork;
+    interrupt: EventActorInterrupt<TPayload>;
+}
+export type EventActorAdapterInvocationResult<TResult extends EventActorEvent, TPayload extends EventActorEvent = EventActorEvent> = EventActorTerminalResult<TResult> | EventActorAdapterSuspendedResult<TPayload>;
+/**
+ * Authenticated, versioned, JSON-safe evidence for one nonterminal invocation.
+ * Integrity does not make this evidence one-shot; the host's durable current
+ * suspension record is the replay and ownership fence. Hosts must capability-
+ * route each exact version during rolling deploys and drain or migrate current
+ * evidence before rotating away from its signing key.
+ */
+export interface EventActorSuspension<TPayload extends EventActorEvent = EventActorEvent> {
+    version: 1;
+    suspensionId: string;
+    attempt: number;
+    issuedAt: number;
+    expiresAt: number;
+    invocation: EventActorInvocationReference;
+    checkpoint: EventActorCheckpointFork;
+    interrupt: EventActorInterrupt<TPayload>;
+    suspensionDigest: string;
+}
+export interface EventActorSuspendedResult<TPayload extends EventActorEvent = EventActorEvent> {
+    status: 'suspended';
+    suspension: EventActorSuspension<TPayload>;
+}
+export interface EventActorSuspendRequest {
+    suspension: EventActorSuspension;
+    /** CAS predecessor required when a claimed resume pauses again. */
+    previous?: {
+        suspensionId: string;
+        attempt: number;
+        resumeAttemptId: string;
+    };
+}
+export type EventActorSuspendResult = {
+    status: 'stored';
+} | {
+    status: 'stale';
+};
+export interface EventActorAdapterResumeRequest {
+    suspension: EventActorSuspension;
+    resumeAttemptId: string;
+    value: EventActorEvent;
+}
+export type EventActorAdapterResumeResult<TResult extends EventActorEvent> = {
+    status: 'claimed';
+    result: EventActorAdapterInvocationResult<TResult>;
+} | {
+    /** The host proved no action before returning this claimed failure. */
+    status: 'claimed_failed';
+    error: Error;
+} | {
+    status: 'stale';
+};
+export interface EventActorResumeRequest {
+    suspension: EventActorSuspension;
+    resumeAttemptId: string;
+    value: EventActorEvent;
+    signal?: AbortSignal;
+}
+export interface EventActorCancelSuspensionRequest {
+    suspension: EventActorSuspension;
+    cancelAttemptId: string;
+    reason?: 'cancelled' | 'expired';
+    signal?: AbortSignal;
+}
+export interface EventActorAdapterCancelSuspensionRequest {
+    suspension: EventActorSuspension;
+    cancelAttemptId: string;
+    reason: 'cancelled' | 'expired';
+}
+export type EventActorCancelSuspensionResult = {
+    status: 'cancelled';
+} | EventActorIndeterminateResult<EventActorEvent>;
+export type EventActorAdapterCancelSuspensionResult = {
+    status: 'cancelled';
+} | {
+    status: 'stale';
+};
+export interface EventActorSettleSuspensionRequest {
+    suspensionId: string;
+    attempt: number;
+    resumeAttemptId: string;
+    status: 'completed_no_action' | 'failed';
+}
+export type EventActorSettleSuspensionResult = {
+    status: 'settled';
+} | {
+    status: 'stale';
+};
 export type EventActorAppliedResult<TResult extends EventActorEvent> = Extract<EventActorTerminalResult<TResult>, {
     status: 'applied';
 }> & {
-    /** Executor-issued one-shot settlement for the invocation that produced this action. */
+    /** Executor-issued settlement for the invocation that produced this action. */
     invocation: EventActorInvocationReference;
+    /** Authenticated cross-executor authority for a resumed terminal action. */
+    settlementAuthority?: EventActorSettlementAuthority;
 };
+/**
+ * Authenticated fence that binds a resumed terminal result to its claimed
+ * suspension. The host must consume it atomically with the actor-head CAS.
+ */
+export interface EventActorSettlementAuthority {
+    version: 1;
+    suspensionId: string;
+    attempt: number;
+    resumeAttemptId: string;
+    issuedAt: number;
+    expiresAt: number;
+    settlementDigest: string;
+}
 export interface EventActorIndeterminateResult<TResult extends EventActorEvent> {
     /** Applied handling cannot be proven safe to retry; retain its fork. */
     status: 'commit_indeterminate';
@@ -75,7 +192,7 @@ export interface EventActorIndeterminateResult<TResult extends EventActorEvent>
     checkpoint: EventActorCheckpointFork;
     error: Error;
 }
-export type EventActorInvocationResult<TResult extends EventActorEvent> = EventActorAppliedResult<TResult> | EventActorIndeterminateResult<TResult> | Extract<EventActorTerminalResult<TResult>, {
+export type EventActorInvocationResult<TResult extends EventActorEvent> = EventActorAppliedResult<TResult> | EventActorIndeterminateResult<TResult> | EventActorSuspendedResult | Extract<EventActorTerminalResult<TResult>, {
     status: 'completed_no_action';
 }>;
 export interface EventActorInvocationContext {
@@ -101,6 +218,8 @@ export interface EventActorCommitRequest<TResult extends EventActorEvent> {
     expectedHead: EventActorHead;
     checkpoint: EventActorCheckpointFork;
     result: TResult;
+    /** Host must consume this suspension fence atomically with the head CAS. */
+    settlementAuthority?: EventActorSettlementAuthority;
     retention: {
         committedCheckpoints: 2;
         dormantCheckpointTtlMs: number;
@@ -123,7 +242,11 @@ export interface EventActorDiscardRequest {
 /**
  * Host adapter for durable actor state and the concrete agent invocation.
  * `commit` must compare both the expected generation and checkpoint identity
- * atomically before advancing the logical actor head. The host mailbox
+ * atomically before advancing the logical actor head. When settlement authority
+ * is present, that same transaction must also verify and close the exact
+ * suspension/resume-attempt fence, including stale-head outcomes. Retrying an
+ * ambiguous acknowledgement must return the durable outcome rather than apply
+ * the same terminal transition again. The host mailbox
  * deduplicates the logical `invocationId` before entering this seam, while each
  * SDK execution attempt receives a distinct checkpoint namespace. Preparation
  * methods own rollback until they return a ready invocation and must treat the
@@ -137,11 +260,28 @@ export interface EventActorDiscardRequest {
  * fork: the SDK retains and surfaces it as `commit_conflict` for host
  * reconciliation. `discard` must be idempotent for the same invocation because
  * an ambiguous cleanup failure can be retried through the public lifecycle.
+ *
+ * Suspension-capable hosts implement all optional suspension methods. `suspend`
+ * publishes an initial suspension only while its logical invocation is current;
+ * with `previous`, it atomically replaces only the exact claimed predecessor.
+ * `resume` atomically claims the current suspension before applying its value to
+ * the declared interrupt and rejects duplicate or competing claims as `stale`.
+ * It must return `claimed_failed` only when it can prove no qualifying action;
+ * any failure after an action returns `applied`. `settleSuspension` atomically
+ * discards the claimed fork and closes its fence for definite no-action
+ * outcomes. `cancelSuspension`
+ * atomically claims, discards, and closes current state, including expired
+ * evidence; expiration alone never implies a safe action outcome.
  */
 export interface EventActorHostAdapter<TEvent extends EventActorEvent, TResult extends EventActorEvent> {
     prepare(request: EventActorAdapterPrepareRequest<TEvent>, context: EventActorPreparationContext): Promise<EventActorAdapterPreparation<TEvent>>;
     coldContinue(request: EventActorAdapterPrepareRequest<TEvent>, head: EventActorHead, context: EventActorPreparationContext): Promise<EventActorInvocation<TEvent>>;
-    invoke(invocation: EventActorInvocation<TEvent>, context: EventActorInvocationContext): Promise<EventActorTerminalResult<TResult>>;
+    invoke(invocation: EventActorInvocation<TEvent>, context: EventActorInvocationContext): Promise<EventActorAdapterInvocationResult<TResult>>;
+    suspend?(request: EventActorSuspendRequest): Promise<EventActorSuspendResult>;
+    resume?(request: EventActorAdapterResumeRequest, context: EventActorInvocationContext): Promise<EventActorAdapterResumeResult<TResult>>;
+    /** Atomically claims, discards, and closes the current suspension. */
+    cancelSuspension?(request: EventActorAdapterCancelSuspensionRequest, context: EventActorPreparationContext): Promise<EventActorAdapterCancelSuspensionResult>;
+    settleSuspension?(request: EventActorSettleSuspensionRequest): Promise<EventActorSettleSuspensionResult>;
     commit(request: EventActorCommitRequest<TResult>): Promise<EventActorCommitResult>;
     discard(request: EventActorDiscardRequest): Promise<void>;
 }
@@ -165,7 +305,9 @@ export type EventActorExecutionResult<TResult extends EventActorEvent> = {
 } | {
     status: 'cancelled';
     continuation: 'warm' | 'cold';
-} | {
+} | (EventActorSuspendedResult & {
+    continuation: 'warm' | 'cold';
+}) | {
     /** The action happened, but another head won the CAS. Reconcile; do not retry. */
     status: 'commit_conflict';
     result: TResult;
@@ -190,4 +332,6 @@ export interface EventActorExecutorOptions {
     dormantCheckpointTtlMs?: number;
     /** Stable private key of at least 32 bytes for cross-lifetime handoffs. */
     preparationSigningKey?: string | Uint8Array;
+    /** Maximum UTF-8 byte size of canonical suspension evidence. */
+    maxSuspensionPayloadBytes?: number;
 }

package/dist/types/graphs/Graph.d.ts

@@ -374,6 +374,21 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * hosts persist it as unfinished rather than complete.
      */
     preemptIncomplete: boolean;
+    /**
+     * True when `routeMessage` sent a turn to `END` because the last AI
+     * message carries no tool call, AND the provider reports it stopped for
+     * hitting the output token ceiling (`getTruncationStopReason`). Plain-text
+     * and reasoning turns cut off this way carry no tool call for
+     * `assertNotTruncatedToolCall` to catch, so `toolsCondition` reads them as
+     * an ordinary finished turn otherwise — hosts read this flag to persist
+     * the turn as unfinished instead of a silently truncated "complete" answer.
+     *
+     * Deliberately separate from `preemptIncomplete`/`preemptHaltReason`: this
+     * has no interaction with the preempt/seal machinery (in particular the
+     * `preemptHaltReason` check at each model node's entry), so setting it
+     * cannot suppress an unrelated agent's turn in a multi-agent graph.
+     */
+    outputTruncatedIncomplete: boolean;
     /**
      * `stopReason` from a `PreemptBoundary` hook that halted the turn.
      *

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/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 } from '@/types';
 import { Providers } from '@/common';
 interface MediaMessageParams {
     message: {
@@ -105,6 +105,13 @@ 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?: {
+        intentToolNames?: ReadonlySet<string>;
+    };
 }
 /**
  * Groups content parts by agent and formats them with agent labels
@@ -148,6 +155,8 @@ 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;
 };
 /**
  * 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

@@ -134,6 +134,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 +184,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/semanticIndex.d.ts

@@ -0,0 +1,19 @@
+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;
+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/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/summarize.d.ts

@@ -29,6 +29,39 @@ 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[];
 export type SummarizationConfig = {
     provider?: ProviderName;
     model?: string;
@@ -86,6 +119,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 +136,4 @@ export interface SummarizeCompleteEvent {
     summary?: SummaryContentBlock;
     error?: string;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.7.6",
+  "version": "3.7.8",
   "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",

package/src/agents/AgentContext.ts

@@ -50,6 +50,7 @@ import {
   Providers,
 } from '@/common';
 import { isTokenCounterCacheCompatible } from '@/llm/tokenCounterCacheCompatibility';
+import { snapshotCompactionSemanticIndex } from '@/summarization/semanticIndex';
 import { createExactTokenCountCache } from '@/llm/contextPressureMeter';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { apportionTokenCounts } from '@/utils/tokens';
@@ -74,6 +75,14 @@ type ProgrammaticToolInstructionTarget = {
   executesDirectly: boolean;
 };
 
+/**
+ * Consecutive summarization attempts that may return no usable summary before
+ * the run stops asking. Every such attempt spends a full model call over the
+ * whole history and leaves the message set exactly as it was, so the cap
+ * bounds spend as much as it bounds the compaction loop.
+ */
+const MAX_SUMMARIZATION_FAILURES = 3;
+
 /**
  * Encapsulates agent-specific state that can vary between agents in a multi-agent system
  */
@@ -108,6 +117,7 @@ export class AgentContext {
       discoveredTools,
       summarizationEnabled,
       summarizationConfig,
+      compactionSemanticIndex,
       initialSummary,
       contextPruningConfig,
       maxToolResultChars,
@@ -141,11 +151,18 @@ export class AgentContext {
       discoveredTools,
       summarizationEnabled,
       summarizationConfig,
+      compactionSemanticIndex,
       contextPruningConfig,
       maxToolResultChars,
     });
 
-    agentContext._sourceInputs = agentConfig;
+    agentContext._sourceInputs =
+      compactionSemanticIndex == null
+        ? agentConfig
+        : {
+          ...agentConfig,
+          compactionSemanticIndex: agentContext.compactionSemanticIndex,
+        };
     agentContext.subagentConfigs = subagentConfigs;
     agentContext.maxSubagentDepth = maxSubagentDepth;
     /**
@@ -346,6 +363,8 @@ export class AgentContext {
   summarizationEnabled?: boolean;
   /** Summarization runtime settings used by graph pruning hooks */
   summarizationConfig?: t.SummarizationConfig;
+  /** Host-supplied advisory guidance consumed only when compaction runs. */
+  compactionSemanticIndex?: t.CompactionSemanticIndex;
   /** Current summary text produced by the summarize node, integrated into system message */
   private summaryText?: string;
   /** Token count of the current summary (tracked for token accounting) */
@@ -376,6 +395,13 @@ export class AgentContext {
    * Summarization is allowed to fire again only when new messages appear.
    */
   private _lastSummarizationMsgCount: number = 0;
+  /**
+   * Consecutive summarization attempts that produced no usable summary.
+   * An empty or failed summary leaves the message set exactly as it was, so
+   * the next prune cycle would ask again on identical state. Cleared by
+   * `setSummary` and by `reset()`.
+   */
+  private _summarizationFailures: number = 0;
   /**
    * Forced compactions performed after a provider rejected a prompt as too
    * large. Bounds the recovery loop so a model that keeps refusing cannot
@@ -430,6 +456,7 @@ export class AgentContext {
     discoveredTools,
     summarizationEnabled,
     summarizationConfig,
+    compactionSemanticIndex,
     contextPruningConfig,
     maxToolResultChars,
   }: {
@@ -456,6 +483,7 @@ export class AgentContext {
     discoveredTools?: string[];
     summarizationEnabled?: boolean;
     summarizationConfig?: t.SummarizationConfig;
+    compactionSemanticIndex?: t.CompactionSemanticIndex;
     contextPruningConfig?: t.ContextPruningConfig;
     maxToolResultChars?: number;
   }) {
@@ -495,6 +523,11 @@ export class AgentContext {
     this.useLegacyContent = useLegacyContent ?? false;
     this.summarizationEnabled = summarizationEnabled;
     this.summarizationConfig = summarizationConfig;
+    if (compactionSemanticIndex != null) {
+      this.compactionSemanticIndex = snapshotCompactionSemanticIndex(
+        compactionSemanticIndex
+      );
+    }
     this.contextPruningConfig = contextPruningConfig;
     this.maxToolResultChars = maxToolResultChars;
 
@@ -1209,6 +1242,7 @@ export class AgentContext {
     this.summaryTokenCount = this._durableSummaryTokenCount;
     this.summaryPrecedesMessages = this.durableSummaryPrecedesMessages;
     this._lastSummarizationMsgCount = 0;
+    this._summarizationFailures = 0;
     this.lastCallUsage = undefined;
     this.totalTokensFresh = false;
     this.restoreContextBudgetAfterOverflow();
@@ -1478,6 +1512,7 @@ export class AgentContext {
     this._durableSummaryTokenCount = tokenCount;
     this.durableSummaryPrecedesMessages = this.summaryPrecedesMessages;
     this._summaryVersion += 1;
+    this._summarizationFailures = 0;
     this.systemRunnableStale = true;
     this.pruneMessages = undefined;
   }
@@ -1547,6 +1582,31 @@ export class AgentContext {
     this._lastSummarizationMsgCount = msgCount;
   }
 
+  /**
+   * Records a summarization attempt that produced no usable summary — an
+   * empty model response, or a provider failure the run declined to paper
+   * over with a metadata stub. Cleared by the next successful summary.
+   */
+  recordSummarizationFailure(): void {
+    this._summarizationFailures += 1;
+  }
+
+  get summarizationFailures(): number {
+    return this._summarizationFailures;
+  }
+
+  /**
+   * True once consecutive no-progress attempts reach {@link MAX_SUMMARIZATION_FAILURES}.
+   * A summarizer that has returned nothing this many times in a row will keep
+   * returning nothing: each empty result leaves the history unchanged, so the
+   * next prune cycle re-triggers on the same state and the run burns its
+   * recursion budget on empty summary steps. Summarization stays off for the
+   * remainder of the run; `reset()` restores it for the next one.
+   */
+  get summarizationExhausted(): boolean {
+    return this._summarizationFailures >= MAX_SUMMARIZATION_FAILURES;
+  }
+
   get overflowRecoveryAttempts(): number {
     return this._overflowRecoveryAttempts;
   }

package/src/common/constants.ts

@@ -42,3 +42,14 @@ export const ACTIVITY_LABEL_RUN_NAME = 'StepLabel';
 export const REASONING_LABEL_RUN_NAME = 'ReasoningLabel';
 export const ACTIVITY_PHASE_RUN_NAME = 'MultiStepLabel';
 export const ACTIVITY_PHASE_LABEL_RUN_NAME = 'MultiStepLabelGeneration';
+
+/** Shared admission and rendering bounds for compaction navigation hints. */
+export const COMPACTION_SEMANTIC_INDEX_LIMITS = Object.freeze({
+  maxInputEntries: 256,
+  maxEntries: 64,
+  maxEntryChars: 512,
+  maxTotalChars: 4_096,
+  maxInputTextChars: 4_096,
+  maxIdentityChars: 512,
+  maxSourceContentIndex: 4_095,
+} as const);