@librechat/agents 3.7.15 → 3.7.17

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

@@ -1,5 +1,6 @@
 import { BaseMessage, UsageMetadata } from '@langchain/core/messages';
-import type { ContextPruningConfig } from '@/types/graph';
+import type { ContextPruningConfig, FadingTier } from '@/types/graph';
+import type { FadingCaps } from './fading';
 import type { TokenCounter } from '@/types/run';
 import type { ProviderName } from '@/types';
 import { ContentTypes } from '@/common';
@@ -65,10 +66,29 @@ export type PruneMessagesFactoryParams = {
      * of waiting for the first provider response.  Ignored when <= 0.
      */
     calibrationRatio?: number;
+    /**
+     * Context-fading tier persisted from a previous run's contextMeta. Seeds the
+     * latched cap ladder so historical tool results keep the same truncated
+     * bytes across runs. Invalid values start fresh; valid values clamp to the
+     * current context window without losing their latched provenance.
+     */
+    fadingTier?: FadingTier | null;
     /** Optional diagnostic log callback wired by the graph for observability. */
     log?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>) => void;
 };
 export type PruneMessagesParams = {
+    /**
+     * Immutable graph history corresponding index-for-index with `messages`.
+     * When supplied, provider projections always derive from this source rather
+     * than from an earlier, already-truncated projection.
+     */
+    canonicalMessages?: BaseMessage[];
+    /**
+     * The caller guarantees that an existing canonical prefix cannot have been
+     * rewritten since the previous call. Graph reducers provide this guarantee
+     * by invalidating and recreating the pruner on replacements/removals.
+     */
+    canonicalPrefixStable?: boolean;
     messages: BaseMessage[];
     usageMetadata?: Partial<UsageMetadata>;
     startType?: ReturnType<BaseMessage['getType']>;
@@ -157,18 +177,47 @@ export declare function getMessagesWithinTokenLimit({ messages: _messages, maxCo
     instructionTokens?: number;
 }): PruningResult;
 export declare function checkValidNumber(value: unknown): value is number;
+type FadingApplyParams = {
+    canonicalMessages?: BaseMessage[];
+    messages: BaseMessage[];
+    indexTokenCountMap: Record<string, number | undefined>;
+    tokenCounter: TokenCounter;
+    caps: Pick<FadingCaps, 'resultChars' | 'consumedChars' | 'inputChars'>;
+    /** Whether consumed results shrink to `caps.consumedChars`. */
+    masked: boolean;
+    /** First index to visit for fresh results and tool-call inputs. */
+    fromIndex?: number;
+    /** First consumed index to visit for masking. */
+    maskedFromIndex?: number;
+    /** Original (pre-masking) content keyed by message index, captured for the summarizer. */
+    originalContentStore?: Map<number, string>;
+    /** Called after storing a newly captured entry. */
+    onContentStored?: (index: number, content: string) => void;
+};
+export type FadingApplyResult = {
+    /** Fresh tool results rewritten. */
+    truncated: number;
+    /** Tool-call inputs rewritten. */
+    inputs: number;
+    /** Consumed tool results rewritten. */
+    masked: number;
+    /** Index of the newest AI message with text; tool results before it are consumed. */
+    consumedBoundary: number;
+};
+/**
+ * Applies a fading tier's caps in one forward pass. Consumed results (before
+ * the boundary) shrink to `consumedChars`, fresh results to `resultChars` and
+ * historical tool-call inputs to `inputChars`. Messages already within their
+ * cap keep object identity and token count, so at an unchanged tier the pass
+ * only touches what arrived since the watermarks. Truncation is a pure
+ * function of (content, cap), which is what keeps the bytes of a historical
+ * result identical from call to call.
+ */
+export declare function applyFadingCaps(params: FadingApplyParams): FadingApplyResult;
 /**
  * Observation masking: replaces consumed ToolMessage content with tight
- * head+tail truncations that serve as informative placeholders.
- *
- * A ToolMessage is "consumed" when a subsequent AI message exists that is NOT
- * purely tool calls — meaning the model has already read and acted on the
- * result. Unconsumed results (the latest tool outputs the model hasn't
- * responded to yet) are left intact so the model can still use them.
- *
- * AI messages are never masked — they contain the model's own reasoning and
- * conclusions, which is what prevents the model from repeating work after
- * its tool results are masked.
+ * head+tail truncations that serve as informative placeholders. Fresh results
+ * and tool-call inputs are left alone.
  *
  * @returns The number of tool messages that were masked.
  */
@@ -176,10 +225,11 @@ export declare function maskConsumedToolResults(params: {
     messages: BaseMessage[];
     indexTokenCountMap: Record<string, number | undefined>;
     tokenCounter: TokenCounter;
-    /** Raw-space token budget available for all consumed tool results combined.
-     *  When provided, the budget is distributed across consumed results weighted
-     *  by recency (newest get the most, oldest get MASKED_RESULT_MAX_CHARS min).
-     *  When omitted, falls back to a flat MASKED_RESULT_MAX_CHARS per result. */
+    /** Character cap applied to every consumed result (never below
+     *  MASKED_RESULT_MIN_CHARS, which is also the default). */
+    maxChars?: number;
+    /** @deprecated Aggregate raw-token budget distributed by recency. Prefer
+     *  `maxChars` for byte-stable masking across otherwise identical calls. */
     availableRawBudget?: number;
     /** When provided, original (pre-masking) content is stored here keyed by
      *  message index — only for entries that actually get truncated. */
@@ -189,12 +239,8 @@ export declare function maskConsumedToolResults(params: {
 }): number;
 /**
  * Pre-flight truncation: truncates oversized ToolMessage content before the
- * main backward-iteration pruning runs. Unlike the ingestion guard (which caps
- * at tool-execution time), pre-flight truncation applies per-turn based on the
- * current context window budget (which may have shrunk due to growing conversation).
- *
- * After truncation, recounts tokens via tokenCounter and updates indexTokenCountMap
- * so subsequent pruning works with accurate counts.
+ * main backward-iteration pruning runs, applying one cap derived from
+ * `maxContextTokens` to every tool result.
  *
  * @returns The number of tool messages that were truncated.
  */
@@ -209,10 +255,8 @@ export declare function preFlightTruncateToolResults(params: {
  * invoking user-defined accessors or `toJSON`.
  */
 export declare function serializeToolCallInput(input: unknown, maxChars?: number): string;
-/** Per-input cap: 15% of context at ~4 chars/token, never above 200K chars. */
-export declare function calculateMaxToolCallInputChars(maxContextTokens?: number): number;
 /** Projects all historical tool-call input representations to bounded values. */
-export declare function projectToolCallInputs(messages: BaseMessage[], maxInputChars: number): BaseMessage[];
+export declare function projectToolCallInputs(messages: BaseMessage[], maxInputChars: number, fromIndex?: number): BaseMessage[];
 /**
  * Derives provider-safe tool history in one pass by dropping incomplete stream
  * content and bounding every provider-consumed tool-call input representation.
@@ -234,9 +278,12 @@ export declare function createPruneMessages(factoryParams: PruneMessagesFactoryP
     originalToolContent?: Map<number, string>;
     newOriginalToolContent?: Map<number, string>;
     calibrationRatio?: number;
+    /** Latched fading tier after this call; hosts persist it beside calibrationRatio. */
+    fadingTier: FadingTier;
     resolvedInstructionOverhead?: number;
     /** Usable budget this call: maxTokens minus output reserve */
     contextBudget?: number;
     /** Calibrated instruction overhead actually applied this call */
     effectiveInstructionTokens?: number;
 };
+export {};

package/dist/types/run.d.ts

@@ -24,6 +24,10 @@ export declare class Run<_T extends t.BaseGraphState> {
     private subagentTasks?;
     private indexTokenCountMap?;
     calibrationRatio: number;
+    fadingTier?: t.FadingTier;
+    fadingTiers: t.FadingTiers;
+    private fadingTierReset;
+    private fadingTierResetAgentIds;
     graphRunnable?: t.CompiledStateWorkflow;
     Graph: StandardGraph | MultiAgentGraph | undefined;
     returnContent: boolean;
@@ -127,6 +131,18 @@ export declare class Run<_T extends t.BaseGraphState> {
      * scaling factor instead of the default (1).
      */
     getCalibrationRatio(): number;
+    /**
+     * Returns the default agent's latched context-fading tier. Single-agent hosts
+     * may persist it beside the calibration ratio; multi-agent hosts should use
+     * `getFadingTiers()` so independent agent tiers are retained.
+     */
+    getFadingTier(): t.FadingTier | undefined;
+    /** Returns a defensive snapshot of latched tiers keyed by agent ID. */
+    getFadingTiers(): t.FadingTiers;
+    /** Agent IDs whose canonical history was compacted during this run. */
+    getFadingTierResetAgentIds(): string[];
+    /** Whether the default agent compacted canonical history during this run. */
+    didResetFadingTier(): boolean;
     getResolvedInstructionOverhead(): number | undefined;
     /**
      * Cooperative-preemption counters for this run. `emptyBoundaries` is the one

package/dist/types/session/AgentSession.d.ts

@@ -5,6 +5,13 @@ export declare class AgentSession {
     private runConfig;
     private store;
     private calibrationRatio;
+    private fadingTier;
+    private fadingTiers;
+    /** Reset generations keyed per scope and per tier (`''` for the default). */
+    private fadingGenerations;
+    /** Advances on every explicit history rewrite (branch, compact, restore). */
+    private fadingRewriteEpoch;
+    private alternateThreadFadingState;
     private checkpointing;
     cwd: string;
     threadId: string;
@@ -13,6 +20,14 @@ export declare class AgentSession {
     get sessionPath(): string | undefined;
     getSessionStore(): JsonlSessionStore | undefined;
     getCheckpointer(): BaseCheckpointSaver | undefined;
+    private getFadingState;
+    private setFadingState;
+    private trimAlternateFadingStates;
+    private clearFadingState;
+    private snapshotFadingGenerations;
+    private restoreFadingStateFromStore;
+    private persistFadingState;
+    private captureRunContextState;
     getLatestCheckpoint(options?: AgentSessionCheckpointLookupOptions): Promise<AgentSessionCheckpointReference | undefined>;
     private hasCheckpointState;
     private recordCheckpoint;

package/dist/types/session/JsonlSessionStore.d.ts

@@ -1,5 +1,5 @@
 import type { BaseMessage } from '@langchain/core/messages';
-import type { CreateSessionFileOptions, SessionBranchOptions, SessionEntry, SessionForkOptions, SessionHeader, SessionLabelEntry, SessionListItem, SessionMessageEntry, SessionCheckpointEntry, SessionCompactionEntry, SessionRunEventEntry, SessionSummaryEntry, SessionStateEntry, SessionTreeNode } from './types';
+import type { CreateSessionFileOptions, SessionBranchOptions, SessionEntry, SessionForkOptions, SessionHeader, SessionLabelEntry, SessionListItem, SessionMessageEntry, SessionCheckpointEntry, SessionCompactionEntry, SessionRunEventEntry, SessionSummaryEntry, SessionStateEntry, SessionFadingState, SessionTreeNode } from './types';
 export declare class JsonlSessionStore {
     readonly path: string;
     readonly header: SessionHeader;
@@ -31,6 +31,9 @@ export declare class JsonlSessionStore {
         threadId?: string;
     }): Promise<SessionRunEventEntry>;
     setLeaf(leafId: string | null): Promise<SessionStateEntry>;
+    getFadingStates(mainThreadId?: string, maxAlternateStates?: number): SessionFadingState[];
+    hasFadingState(): boolean;
+    appendFadingState(fadingState: SessionStateEntry['data']['fadingState']): Promise<SessionStateEntry>;
     appendEntryForCompaction(params: {
         text: string;
         tokenCount?: number;

package/dist/types/session/types.d.ts

@@ -74,8 +74,17 @@ export type SessionRunEventEntry = SessionEntryBase<'run_event', {
     threadId?: string;
     payload?: JsonValue;
 }>;
+export interface SessionFadingState {
+    threadId: string;
+    /** LangGraph checkpoint namespace within `threadId`; empty when omitted. */
+    checkpointNs?: string;
+    fadingTier?: t.FadingTier;
+    fadingTiers?: t.FadingTiers;
+}
 export type SessionStateEntry = SessionEntryBase<'session_state', {
     leafId: string | null;
+    /** Latest compact fading state for one checkpoint thread; null clears all. */
+    fadingState?: SessionFadingState | null;
 }>;
 export type SessionEntry = SessionMessageEntry | SessionSummaryEntry | SessionCompactionEntry | SessionCheckpointEntry | SessionLabelEntry | SessionRunEventEntry | SessionStateEntry;
 export interface SessionTreeNode {

package/dist/types/tools/subagent/SubagentReplay.d.ts

@@ -2,7 +2,7 @@ import type { ToolCall, ToolMessage } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
 import type { ToolApprovalReplaySnapshot } from '@/hooks';
-import type { RunStepResumeState, ToolSessionContext } from '@/types';
+import type { FadingTier, FadingTiers, RunStepResumeState, ToolSessionContext } from '@/types';
 export declare const SUBAGENT_RESUME_MANIFEST_CONFIG_KEY = "__librechat_subagent_resume_manifest";
 export declare const SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY = "__librechat_subagent_resume_attempt";
 export declare const SUBAGENT_PARENT_BATCH_CONFIG_KEY = "__librechat_subagent_parent_batch";
@@ -45,6 +45,8 @@ export interface SubagentGraphResumeState {
     eagerToolSuppressions: string[];
     runStepState?: RunStepResumeState;
     toolOutputReferences?: ToolOutputReferenceState;
+    fadingTier?: FadingTier;
+    fadingTiers?: FadingTiers;
 }
 /** Private checkpoint payload linking a parent pause to an exact child state. */
 export interface SubagentResumeExecution {

package/dist/types/types/graph.d.ts

@@ -74,6 +74,25 @@ export interface ContextUsageEvent {
     /** EMA ratio of provider-reported vs locally estimated token counts */
     calibrationRatio?: number;
 }
+/**
+ * Latched context-fading tier. Caps for historical tool results derive from
+ * `(budgetTokens, masked)` only, so carrying the tier across runs keeps their
+ * truncated bytes stable for prefix-based provider prompt caches. Hosts
+ * persist it beside `calibrationRatio` and pass it back via
+ * `RunConfig.fadingTiers[agentId]`.
+ */
+export interface FadingTier {
+    v: 1;
+    /** Token budget the caps derive from, in raw token space. Never grows;
+     *  clamped to the current context window when seeded. */
+    budgetTokens: number;
+    /** Whether observation masking has activated. Never deactivates. */
+    masked: boolean;
+    /** Whether this tier was reduced, masked, or restored from host state. */
+    latched?: true;
+}
+/** Latched fading tiers keyed by agent ID. */
+export type FadingTiers = Record<string, FadingTier>;
 export interface EventHandler {
     handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
@@ -231,6 +250,10 @@ export type StandardGraphInput = {
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;
     calibrationRatio?: number;
+    /** Persisted default-agent tier retained for single-agent compatibility. */
+    fadingTier?: FadingTier | null;
+    /** Persisted fading tiers keyed by agent ID. */
+    fadingTiers?: FadingTiers | null;
     /**
      * Receives a {@link SubagentUsageEvent} for every model call that reports
      * usage metadata inside a subagent child run spawned from this graph

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

@@ -319,6 +319,16 @@ export type RunConfig = {
      * conversation. Without this, the EMA resets to 1 on every new Run instance.
      */
     calibrationRatio?: number;
+    /**
+     * Default-agent fading tier retained for single-agent compatibility. New
+     * multi-agent integrations should use `fadingTiers`.
+     */
+    fadingTier?: g.FadingTier | null;
+    /**
+     * Context-fading tiers keyed by agent ID. Multi-agent hosts should persist
+     * the value returned by `Run.getFadingTiers()` and pass it back here.
+     */
+    fadingTiers?: g.FadingTiers | null;
     /** Skip post-stream cleanup (clearHeavyState) — useful for tests that inspect graph state after processStream */
     skipCleanup?: boolean;
     /**

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

@@ -68,3 +68,12 @@ export declare function truncateToolInput(input: unknown, maxChars: number): {
  * @returns The (possibly truncated) content string.
  */
 export declare function truncateToolResultContent(content: string, maxChars: number): string;
+/** Absolute hard cap on a single tool-call input (characters). */
+export declare const HARD_MAX_TOOL_CALL_INPUT_CHARS = 200000;
+/** Smallest JSON value a truncated tool-call input can shrink to. */
+export declare const MIN_JSON_VALUE_CHARS = 4;
+/**
+ * Computes the max tool-call input size for a context window: 15 % of the
+ * window in estimated characters (~4 chars/token), capped at 200K.
+ */
+export declare function calculateMaxToolCallInputChars(maxContextTokens?: number): number;

package/package.json

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

package/src/agents/AgentContext.ts

@@ -1,10 +1,15 @@
 /* eslint-disable no-console */
 import { RunnableLambda } from '@langchain/core/runnables';
-import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import {
+  HumanMessage,
+  SystemMessage,
+  coerceMessageLikeToMessage,
+} from '@langchain/core/messages';
 import type {
   UsageMetadata,
   BaseMessage,
   BaseMessageFields,
+  BaseMessageLike,
 } from '@langchain/core/messages';
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ExactTokenCountCache } from '@/llm/contextPressureMeter';
@@ -271,10 +276,22 @@ export class AgentContext {
   deferredToolNames: string[] = [];
   /** Running calibration ratio from the pruner — persisted across runs via contextMeta. */
   calibrationRatio: number = 1;
+  /** Latched context-fading tier from the pruner — persisted across runs via contextMeta. */
+  fadingTier?: t.FadingTier;
   /** Provider-observed instruction overhead from the pruner's best-variance turn. */
   resolvedInstructionOverhead?: number;
   private _pendingOriginalToolContent?: Map<number, string>;
   private pendingOriginalToolContentChars = 0;
+  /** Provider-bound projection for this Run; graph messages remain canonical. */
+  private providerProjectedMessages?: BaseMessage[];
+  /** Canonical object identities corresponding to the projected slots. */
+  private providerProjectionSources?: BaseMessage[];
+  /** Canonical messages by ID, used to distinguish identity replay from replacement. */
+  private providerProjectionSourcesById?: Map<string, BaseMessage>;
+  /** Conservative counts retained by canonical identity across a rebuild. */
+  private providerProjectionRecountFloors?: WeakMap<BaseMessage, number>;
+  /** Recount after discarding a projection whose token map contains capped sizes. */
+  private providerProjectionRequiresRecount = false;
   /** Pre-masking tool content keyed by message index, consumed by the summarize node. */
   get pendingOriginalToolContent(): Map<number, string> | undefined {
     return this._pendingOriginalToolContent;
@@ -390,6 +407,8 @@ export class AgentContext {
   private durableSummaryPrecedesMessages: boolean = false;
   /** Number of summarization cycles that have occurred for this agent context */
   private _summaryVersion: number = 0;
+  /** Whether this run compacted canonical history and reset its fading tier. */
+  private _fadingTierReset: boolean = false;
   /**
    * Message count at the time summarization was last triggered.
    * Used to prevent re-summarizing the same unchanged message set.
@@ -1214,6 +1233,7 @@ export class AgentContext {
    * Reset context for a new run
    */
   reset(options?: { preserveOriginalToolContent?: boolean }): void {
+    this._fadingTierReset = false;
     this.systemMessageTokens = 0;
     this.dynamicInstructionTokens = 0;
     this.toolSchemaTokens = 0;
@@ -1225,6 +1245,7 @@ export class AgentContext {
     this.indexTokenCountMap = { ...this.baseIndexTokenCountMap };
     this.currentUsage = undefined;
     this.pruneMessages = undefined;
+    this.clearProviderProjection(false);
     this.lastStreamCall = undefined;
     this.tokenTypeSwitch = undefined;
     this.reasoningTransitionCount = 0;
@@ -1509,9 +1530,12 @@ export class AgentContext {
     this._durableSummaryTokenCount = tokenCount;
     this.durableSummaryPrecedesMessages = this.summaryPrecedesMessages;
     this._summaryVersion += 1;
+    this._fadingTierReset = true;
     this._summarizationFailures = 0;
     this.systemRunnableStale = true;
     this.pruneMessages = undefined;
+    this.fadingTier = undefined;
+    this.clearProviderProjection(false);
   }
 
   /** Sets a cross-run summary that is injected into the system prompt. */
@@ -1525,6 +1549,9 @@ export class AgentContext {
     this.durableSummaryPrecedesMessages = false;
     this._summaryVersion += 1;
     this.systemRunnableStale = true;
+    this.pruneMessages = undefined;
+    this.fadingTier = undefined;
+    this.clearProviderProjection(false);
   }
 
   /**
@@ -1558,6 +1585,10 @@ export class AgentContext {
     return this._summaryVersion;
   }
 
+  get fadingTierReset(): boolean {
+    return this._fadingTierReset;
+  }
+
   /**
    * Returns true when the message count hasn't changed since the last
    * summarization — re-summarizing would produce an identical result.
@@ -1678,6 +1709,7 @@ export class AgentContext {
       this.maxContextTokens = budgetTokens;
     }
     this.pruneMessages = undefined;
+    this.clearProviderProjection(true);
     this._lastSummarizationMsgCount = 0;
     this._lastOverflowPromptTokens =
       promptTokens != null
@@ -1686,6 +1718,147 @@ export class AgentContext {
     this._overflowRecoveryAttempts += 1;
   }
 
+  /**
+   * Returns the mutable provider projection for this Run while preserving the
+   * graph-owned messages as the canonical history. Appends are synchronized
+   * incrementally so the pruner's watermarks remain valid. Any rewritten or
+   * compacted canonical prefix starts a fresh projection and pruner.
+   */
+  getProviderProjectedMessages(messages: BaseMessage[]): BaseMessage[] {
+    const sources = this.providerProjectionSources;
+    let projection = this.providerProjectedMessages;
+    const priorLength = sources?.length ?? 0;
+    const prefixChanged =
+      sources != null &&
+      (messages.length < sources.length ||
+        (messages.length === priorLength
+          ? sources.some((source, index) => messages[index] !== source)
+          : priorLength > 0 &&
+            messages[priorLength - 1] !== sources[priorLength - 1]));
+
+    if (projection == null || sources == null || prefixChanged) {
+      if (prefixChanged) {
+        this.pruneMessages = undefined;
+        /** The originals map is keyed by index; a rewritten prefix would let
+         * the summarizer restore one tool's bytes onto another message. */
+        this.pendingOriginalToolContent = undefined;
+        this.prepareProviderProjectionRecount(sources);
+      }
+      projection = messages.map((message) =>
+        Array.isArray(message.content)
+          ? cloneMessage(message, [...message.content])
+          : message
+      );
+      this.providerProjectedMessages = projection;
+      this.providerProjectionSources = [...messages];
+      this.providerProjectionSourcesById = new Map(
+        messages.flatMap((message) =>
+          message.id == null ? [] : [[message.id, message] as const]
+        )
+      );
+      if (this.providerProjectionRequiresRecount && this.tokenCounter != null) {
+        const recounted: Record<string, number> = {};
+        for (let i = 0; i < messages.length; i++) {
+          const localCount = this.tokenCounter(messages[i]);
+          const conservativeFloor =
+            this.providerProjectionRecountFloors?.get(messages[i]);
+          recounted[i] =
+            conservativeFloor == null
+              ? localCount
+              : Math.max(localCount, conservativeFloor);
+        }
+        this.indexTokenCountMap = recounted;
+        this.providerProjectionRequiresRecount = false;
+        this.providerProjectionRecountFloors = undefined;
+      }
+      return projection;
+    }
+
+    for (let i = sources.length; i < messages.length; i++) {
+      const message = messages[i];
+      sources.push(message);
+      if (message.id != null) {
+        this.providerProjectionSourcesById?.set(message.id, message);
+      }
+      projection.push(
+        Array.isArray(message.content)
+          ? cloneMessage(message, [...message.content])
+          : message
+      );
+    }
+    return projection;
+  }
+
+  /**
+   * Invalidates the provider projection when a graph reducer update rewrites
+   * canonical history. Reducer updates expose replacements and removals before
+   * they are folded into a potentially longer array, avoiding a prefix scan on
+   * the normal append-only path.
+   */
+  invalidateProviderProjectionForMessageUpdates(
+    updates:
+      | BaseMessage
+      | BaseMessageLike
+      | Array<BaseMessage | BaseMessageLike | null | undefined>
+      | null
+      | undefined
+  ): void {
+    if (this.providerProjectionSources == null) {
+      return;
+    }
+    const updateList = (Array.isArray(updates) ? updates : [updates]) as Array<
+      BaseMessageLike | null | undefined
+    >;
+    for (const rawUpdate of updateList) {
+      if (rawUpdate == null) {
+        continue;
+      }
+      const update = coerceMessageLikeToMessage(rawUpdate);
+      const priorSource =
+        update.id == null
+          ? undefined
+          : this.providerProjectionSourcesById?.get(update.id);
+      if (
+        update.getType() === 'remove' ||
+        (priorSource != null && priorSource !== update)
+      ) {
+        this.pruneMessages = undefined;
+        this.pendingOriginalToolContent = undefined;
+        this.clearProviderProjection(true);
+        return;
+      }
+    }
+  }
+
+  private clearProviderProjection(recountOnNextUse: boolean): void {
+    if (recountOnNextUse) {
+      this.prepareProviderProjectionRecount(this.providerProjectionSources);
+    } else {
+      this.providerProjectionRequiresRecount = false;
+      this.providerProjectionRecountFloors = undefined;
+    }
+    this.providerProjectedMessages = undefined;
+    this.providerProjectionSources = undefined;
+    this.providerProjectionSourcesById = undefined;
+  }
+
+  private prepareProviderProjectionRecount(
+    sources: BaseMessage[] | undefined
+  ): void {
+    this.providerProjectionRequiresRecount = true;
+    if (sources == null) {
+      return;
+    }
+    const floors = new WeakMap<BaseMessage, number>();
+    for (let i = 0; i < sources.length; i++) {
+      const count = this.indexTokenCountMap[i];
+      if (count != null && Number.isFinite(count) && count >= 0) {
+        floors.set(sources[i], count);
+      }
+    }
+    this.providerProjectionRecountFloors = floors;
+  }
+
   /** Applies token calibration only when the observation came from this provider. */
   applyObservedOverflowCalibration(
     provider: t.ProviderName | undefined,
@@ -1904,6 +2077,7 @@ export class AgentContext {
       summarizationEnabled: this.summarizationEnabled,
       reserveRatio: this.summarizationConfig?.reserveRatio,
       calibrationRatio: opts?.calibrationRatio ?? this.calibrationRatio,
+      fadingTier: this.fadingTier,
       getInstructionTokens: () => this.instructionTokens,
     });
     const {

package/src/agents/projection.ts

@@ -13,6 +13,8 @@ export interface ProjectAgentContextUsageParams {
   indexTokenCountMap?: Record<string, number>;
   /** Provider-calibrated ratio from a prior snapshot, applied as a static seed. */
   calibrationRatio?: number;
+  /** Persisted fading tier for this agent, applied to the projected branch. */
+  fadingTier?: t.FadingTier;
   /** Execution backend used to synthesize the live effective tool registry. */
   toolExecution?: t.ToolExecutionConfig;
   runId?: string;
@@ -34,6 +36,7 @@ export async function projectAgentContextUsage({
   tokenCounter,
   indexTokenCountMap,
   calibrationRatio,
+  fadingTier,
   toolExecution,
   runId,
   agentId,
@@ -44,6 +47,7 @@ export async function projectAgentContextUsage({
     indexTokenCountMap,
     toolExecution
   );
+  context.fadingTier = fadingTier;
   await context.tokenCalculationPromise;
   return context.projectContextUsage(messages, {
     runId,