@librechat/agents 3.7.15 → 3.7.17

package/src/session/JsonlSessionStore.ts

@@ -26,6 +26,7 @@ import type {
   SessionRunEventEntry,
   SessionSummaryEntry,
   SessionStateEntry,
+  SessionFadingState,
   SessionTreeNode,
 } from './types';
 import {
@@ -82,6 +83,16 @@ function parseLine(line: string): SessionHeader | SessionEntry | undefined {
   }
 }
 
+/** A `session_state` line may carry `data: null`; only an object can hold fading state. */
+function hasFadingStateField(entry: SessionStateEntry): boolean {
+  const data: unknown = entry.data;
+  return (
+    data != null &&
+    typeof data === 'object' &&
+    Object.prototype.hasOwnProperty.call(data, 'fadingState')
+  );
+}
+
 function createHeader(options: CreateSessionFileOptions): SessionHeader {
   return {
     type: 'session',
@@ -374,6 +385,66 @@ export class JsonlSessionStore {
     });
   }
 
+  getFadingStates(
+    mainThreadId?: string,
+    maxAlternateStates = Number.POSITIVE_INFINITY
+  ): SessionFadingState[] {
+    const states = new Map<string, SessionFadingState>();
+    const alternateLimit = Number.isFinite(maxAlternateStates)
+      ? Math.max(0, Math.floor(maxAlternateStates))
+      : Number.POSITIVE_INFINITY;
+    let alternateCount = 0;
+    let mainFound = mainThreadId == null;
+    for (let i = this.entries.length - 1; i >= 0; i--) {
+      const entry = this.entries[i];
+      if (entry.type !== 'session_state' || !hasFadingStateField(entry)) {
+        continue;
+      }
+      if (entry.data.fadingState == null) {
+        break;
+      }
+      const state = entry.data.fadingState;
+      const scopeKey = JSON.stringify([
+        state.threadId,
+        state.checkpointNs ?? '',
+      ]);
+      if (states.has(scopeKey)) {
+        continue;
+      }
+      if (
+        state.threadId === mainThreadId &&
+        (state.checkpointNs ?? '') === ''
+      ) {
+        states.set(scopeKey, state);
+        mainFound = true;
+      } else if (alternateCount < alternateLimit) {
+        states.set(scopeKey, state);
+        alternateCount += 1;
+      }
+      if (mainFound && alternateCount >= alternateLimit) {
+        break;
+      }
+    }
+    return [...states.values()];
+  }
+
+  hasFadingState(): boolean {
+    return this.entries.some(
+      (entry) => entry.type === 'session_state' && hasFadingStateField(entry)
+    );
+  }
+
+  async appendFadingState(
+    fadingState: SessionStateEntry['data']['fadingState']
+  ): Promise<SessionStateEntry> {
+    const leafId = this.getLeafEntry()?.id ?? null;
+    return this.appendEntry<SessionStateEntry>({
+      type: 'session_state',
+      parentId: leafId,
+      data: { leafId, fadingState },
+    });
+  }
+
   async appendEntryForCompaction(params: {
     text: string;
     tokenCount?: number;

package/src/session/types.ts

@@ -116,10 +116,20 @@ export type SessionRunEventEntry = SessionEntryBase<
   }
 >;
 
+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;
   }
 >;
 

package/src/tools/subagent/SubagentExecutor.ts

@@ -2457,6 +2457,12 @@ export class SubagentExecutor {
       streamLimits: this.streamLimits,
       subagentScope: true,
       subagentExecutionContext: childExecutionContext,
+      ...(resumeExecution?.graphState.fadingTier == null
+        ? {}
+        : { fadingTier: resumeExecution.graphState.fadingTier }),
+      ...(resumeExecution?.graphState.fadingTiers == null
+        ? {}
+        : { fadingTiers: resumeExecution.graphState.fadingTiers }),
       /**
        * Forwarded so the child graph's own `SubagentExecutor` (created in
        * its `createAgentNode` when `allowNested` keeps subagentConfigs)

package/src/tools/subagent/SubagentReplay.ts

@@ -2,7 +2,13 @@ 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';
+import { isFadingTier } from '@/messages/fading';
 import {
   attachRunStepResumeState,
   getRunStepResumeState,
@@ -65,6 +71,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. */
@@ -301,7 +309,12 @@ function isGraphResumeState(value: unknown): value is SubagentGraphResumeState {
     (state.runStepState != null &&
       !isRunStepResumeState(state.runStepState)) ||
     (state.toolOutputReferences != null &&
-      !isToolOutputReferenceState(state.toolOutputReferences))
+      !isToolOutputReferenceState(state.toolOutputReferences)) ||
+    (state.fadingTier != null && !isFadingTier(state.fadingTier)) ||
+    (state.fadingTiers != null &&
+      (typeof state.fadingTiers !== 'object' ||
+        Array.isArray(state.fadingTiers) ||
+        !Object.values(state.fadingTiers).every(isFadingTier)))
   ) {
     return false;
   }

package/src/types/graph.ts

@@ -132,6 +132,27 @@ export interface ContextUsageEvent {
   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,
@@ -346,6 +367,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/src/types/run.ts

@@ -338,6 +338,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/src/utils/errors.ts

@@ -219,6 +219,14 @@ const NON_RECOVERABLE_RE =
 const OUTPUT_LIMIT_RE =
   /max_?(?:completion_?)?tokens\s*(?:must be|is too|cannot|exceeds|too large|greater than)|maximum number of output tokens|max_tokens.*less than or equal/i;
 
+/**
+ * A gateway can report this disjunction without saying whether the prompt or
+ * requested output caused the rejection. Compaction is unsafe in that case:
+ * shrinking a healthy prompt cannot fix an invalid output allowance.
+ */
+const AMBIGUOUS_CONTEXT_OR_OUTPUT_RE =
+  /(?:context window[\s\S]{0,80}\bor\b[\s\S]{0,80}max(?:imum)? output|max(?:imum)? output[\s\S]{0,80}\bor\b[\s\S]{0,80}context window)/i;
+
 /**
  * Recovers the input-only figure from providers that quote a combined total
  * and then break it down — OpenRouter's "(56811 of text input, 16 in the
@@ -441,6 +449,10 @@ export function getContextOverflowInfo(
     return null;
   }
 
+  if (AMBIGUOUS_CONTEXT_OR_OUTPUT_RE.test(haystack)) {
+    return null;
+  }
+
   if (OUTPUT_LIMIT_RE.test(haystack)) {
     return null;
   }
@@ -525,7 +537,11 @@ export function isLikelyContextOverflowError(
     return true;
   }
   const haystack = stripUrls(collectErrorText(error));
-  if (haystack === '' || OUTPUT_LIMIT_RE.test(haystack)) {
+  if (
+    haystack === '' ||
+    AMBIGUOUS_CONTEXT_OR_OUTPUT_RE.test(haystack) ||
+    OUTPUT_LIMIT_RE.test(haystack)
+  ) {
     return false;
   }
   if (NON_RECOVERABLE_RE.test(haystack)) {

package/src/utils/truncation.ts

@@ -152,3 +152,28 @@ export function truncateToolResultContent(
 
   return content.slice(0, headEnd) + indicator + content.slice(tailStart);
 }
+
+/** Absolute hard cap on a single tool-call input (characters). */
+export const HARD_MAX_TOOL_CALL_INPUT_CHARS = 200_000;
+
+/** Smallest JSON value a truncated tool-call input can shrink to. */
+export 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 function calculateMaxToolCallInputChars(
+  maxContextTokens?: number
+): number {
+  if (maxContextTokens == null || maxContextTokens <= 0) {
+    return HARD_MAX_TOOL_CALL_INPUT_CHARS;
+  }
+  return Math.max(
+    MIN_JSON_VALUE_CHARS,
+    Math.min(
+      Math.floor(maxContextTokens * 0.15) * 4,
+      HARD_MAX_TOOL_CALL_INPUT_CHARS
+    )
+  );
+}