@librechat/agents 3.7.7 → 3.7.8

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.7",
+  "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);

package/src/graphs/Graph.ts

@@ -153,10 +153,10 @@ import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
 import { SUBAGENT_REPLAY_CONTROLLER } from '@/tools/subagent/SubagentReplay';
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { createContextPressureMeter } from '@/llm/contextPressureMeter';
-import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { prepareProviderRequest } from '@/llm/prepareProviderRequest';
 import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
+import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { providerRequiresStrictAlternation } from '@/llm/providers';
 import { buildSubagentToolParams } from '@/tools/SubagentTool';
 import { initializeLangfuseTracing } from '@/instrumentation';
@@ -164,6 +164,7 @@ import { shouldTriggerSummarization } from '@/summarization';
 import { isRunStepResumeState } from '@/tools/runStepResume';
 import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createSummarizeNode } from '@/summarization/node';
+import { getTruncationStopReason } from '@/llm/truncation';
 import { messagesStateReducer } from '@/messages/reducer';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
@@ -1425,6 +1426,21 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * hosts persist it as unfinished rather than complete.
    */
   preemptIncomplete = false;
+  /**
+   * 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 = false;
   /**
    * `stopReason` from a `PreemptBoundary` hook that halted the turn.
    *
@@ -1702,6 +1718,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.preemptEmptyBoundaries = 0;
     this.preemptIncomplete = false;
     this.preemptHaltReason = undefined;
+    this.outputTruncatedIncomplete = false;
   }
 
   /**
@@ -2801,9 +2818,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       provider,
       clientOptions,
       tools,
-      isDeferred: makeIsDeferred(
-        agentContext.getEffectiveToolDefinitions()
-      ),
+      isDeferred: makeIsDeferred(agentContext.getEffectiveToolDefinitions()),
     });
   }
 
@@ -3030,9 +3045,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           messagesToRefine.length > 0;
 
         if (hasPrunedMessages) {
-          const shouldSkip = agentContext.shouldSkipSummarization(
-            messages.length
-          );
+          const shouldSkip =
+            agentContext.summarizationExhausted ||
+            agentContext.shouldSkipSummarization(messages.length);
           const triggerResult =
             !shouldSkip &&
             shouldTriggerSummarization({
@@ -3089,6 +3104,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                 messageCount: messages.length,
                 messagesToRefineCount: messagesToRefine.length,
                 contextLength: context.length,
+                summarizationFailures: agentContext.summarizationFailures,
+                summarizationExhausted: agentContext.summarizationExhausted,
               },
               { runId: this.runId, agentId }
             );
@@ -4818,11 +4835,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (state.summarizationRequest != null) {
         return summarizeNode;
       }
-      return toolsCondition(
+      const decision = toolsCondition(
         state as t.BaseGraphState,
         toolNode,
         this.invokedToolIds
       );
+      /**
+       * `toolsCondition` only looks at `tool_calls` — a plain-text/reasoning
+       * turn cut off by the output token ceiling has none, so it reads as an
+       * ordinary finished turn and routes here to END. Flag it so hosts can
+       * tell a genuinely finished answer from one the model never got to
+       * complete. See `outputTruncatedIncomplete` for why this stays clear
+       * of the preempt/seal halt fields.
+       */
+      if (decision === END) {
+        const { messages } = state as t.BaseGraphState;
+        const lastMessage = messages[messages.length - 1];
+        if (getTruncationStopReason(lastMessage) != null) {
+          this.outputTruncatedIncomplete = true;
+        }
+      }
+      return decision;
     };
 
     const StateAnnotation = Annotation.Root({

package/src/langfuseTraceShaping.ts

@@ -35,6 +35,11 @@ const DEPRECATED_TRACE_INPUT_ATTRIBUTE = 'langfuse.trace.input';
 const DEPRECATED_TRACE_OUTPUT_ATTRIBUTE = 'langfuse.trace.output';
 const OBSERVATION_METADATA_LANGGRAPH_NODE = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langgraph_node`;
 const OBSERVATION_METADATA_OPERATION = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.${LANGFUSE_OPERATION_METADATA_KEY}`;
+const OBSERVATION_METADATA_COMPACTION_SEMANTIC_INDEX_ENTRIES = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.compaction_semantic_index_entries`;
+const COMPACTION_SEMANTIC_INDEX_OPEN = '<compaction-semantic-index>';
+const COMPACTION_SEMANTIC_INDEX_CLOSE = '</compaction-semantic-index>';
+const REDACTED_COMPACTION_SEMANTIC_INDEX =
+  '<compaction-semantic-index redacted="true" />\n\n';
 
 type MutableSpan = ReadableSpan & {
   name: string;
@@ -66,6 +71,94 @@ function parseAttributeValue(value: unknown): unknown {
   }
 }
 
+type CompactionSemanticIndexRedaction = {
+  value: unknown;
+  redacted: boolean;
+};
+
+function redactCompactionSemanticIndexText(
+  value: string
+): CompactionSemanticIndexRedaction {
+  if (!value.startsWith(COMPACTION_SEMANTIC_INDEX_OPEN)) {
+    return { value, redacted: false };
+  }
+  const start = 0;
+  const close = value.indexOf(COMPACTION_SEMANTIC_INDEX_CLOSE, start);
+  if (close < 0) {
+    return { value, redacted: false };
+  }
+  let end = close + COMPACTION_SEMANTIC_INDEX_CLOSE.length;
+  while (end < value.length && /\s/.test(value[end])) {
+    end++;
+  }
+  return {
+    value:
+      value.slice(0, start) +
+      REDACTED_COMPACTION_SEMANTIC_INDEX +
+      value.slice(end),
+    redacted: true,
+  };
+}
+
+function redactCompactionSemanticIndexValue(
+  value: unknown
+): CompactionSemanticIndexRedaction {
+  if (typeof value === 'string') {
+    return redactCompactionSemanticIndexText(value);
+  }
+  if (Array.isArray(value)) {
+    for (let index = value.length - 1; index >= 0; index--) {
+      const nested = redactCompactionSemanticIndexValue(value[index]);
+      if (nested.redacted) {
+        const result = [...value];
+        result[index] = nested.value;
+        return { value: result, redacted: true };
+      }
+    }
+    return { value, redacted: false };
+  }
+  if (!isRecord(value)) {
+    return { value, redacted: false };
+  }
+  const entries = Object.entries(value);
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const [key, nestedValue] = entries[index];
+    const nested = redactCompactionSemanticIndexValue(nestedValue);
+    if (nested.redacted) {
+      return {
+        value: { ...value, [key]: nested.value },
+        redacted: true,
+      };
+    }
+  }
+  return { value, redacted: false };
+}
+
+function redactCompactionSemanticIndexInput(span: MutableSpan): void {
+  const entryCount =
+    span.attributes[
+      OBSERVATION_METADATA_COMPACTION_SEMANTIC_INDEX_ENTRIES
+    ];
+  const numericEntryCount = Number(entryCount);
+  if (!Number.isFinite(numericEntryCount) || numericEntryCount <= 0) {
+    return;
+  }
+  const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+  const input = span.attributes[inputKey];
+  if (input == null) {
+    return;
+  }
+  const parsed = parseAttributeValue(input);
+  const redaction = redactCompactionSemanticIndexValue(parsed);
+  if (!redaction.redacted) {
+    return;
+  }
+  span.attributes[inputKey] =
+    typeof redaction.value === 'string' && parsed === input
+      ? redaction.value
+      : JSON.stringify(redaction.value);
+}
+
 function getMessageArray(
   value: unknown
 ): Record<string, unknown>[] | undefined {
@@ -594,6 +687,7 @@ export function shapeLangfuseSpan(span: ReadableSpan): void {
   const mutable = span as MutableSpan;
   delete mutable.attributes[DEPRECATED_TRACE_INPUT_ATTRIBUTE];
   delete mutable.attributes[DEPRECATED_TRACE_OUTPUT_ATTRIBUTE];
+  redactCompactionSemanticIndexInput(mutable);
   const isGraphObservation = isGraphSpan(mutable);
   if (mutable.name.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)) {
     shapeAgentNodeSpan(mutable);

package/src/llm/fake.ts

@@ -14,6 +14,15 @@ export class FakeChatModel extends FakeListChatModel {
   private splitStrategy: SplitStrategy;
   private toolCalls: ToolCall[] = [];
   private addedToolCalls: boolean = false;
+  /**
+   * 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?: Record<string, unknown>;
 
   constructor({
     responses,
@@ -21,16 +30,19 @@ export class FakeChatModel extends FakeListChatModel {
     emitCustomEvent,
     splitStrategy = { type: 'regex', value: /(?<=\s+)|(?=\s+)/ },
     toolCalls = [],
+    finalChunkGenerationInfo,
   }: {
     responses: string[];
     sleep?: number;
     emitCustomEvent?: boolean;
     splitStrategy?: SplitStrategy;
     toolCalls?: ToolCall[];
+    finalChunkGenerationInfo?: Record<string, unknown>;
   }) {
     super({ responses, sleep, emitCustomEvent });
     this.splitStrategy = splitStrategy;
     this.toolCalls = toolCalls;
+    this.finalChunkGenerationInfo = finalChunkGenerationInfo;
   }
 
   private splitText(text: string): string[] {
@@ -47,14 +59,16 @@ export class FakeChatModel extends FakeListChatModel {
   }
   _createResponseChunk(
     text: string,
-    tool_call_chunks?: ToolCallChunk[]
+    tool_call_chunks?: ToolCallChunk[],
+    responseMetadata?: Record<string, unknown>
   ): ChatGenerationChunk {
     return new ChatGenerationChunk({
       text,
-      generationInfo: {},
+      generationInfo: responseMetadata ?? {},
       message: new AIMessageChunk({
         content: text,
         tool_call_chunks,
+        response_metadata: responseMetadata,
         additional_kwargs: tool_call_chunks
           ? {
             tool_calls: tool_call_chunks.map((toolCall) => ({
@@ -87,14 +101,31 @@ export class FakeChatModel extends FakeListChatModel {
     }
 
     const chunks = this.splitText(response);
-    for await (const chunk of chunks) {
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i];
       await this._sleepIfRequested();
 
       if (options.thrownErrorString != null && options.thrownErrorString) {
         throw new Error(options.thrownErrorString);
       }
 
-      const responseChunk = super._createResponseChunk(chunk);
+      /**
+       * Only the true terminal chunk of the response gets the metadata: when
+       * this response also appends a trailing tool-call chunk below, THAT
+       * chunk is terminal instead (not currently exercised by any test —
+       * a caller wanting truncated-tool-call metadata should attach it
+       * there).
+       */
+      const isTerminalChunk =
+        i === chunks.length - 1 && this.toolCalls.length === 0;
+      const responseChunk =
+        isTerminalChunk && this.finalChunkGenerationInfo != null
+          ? this._createResponseChunk(
+            chunk,
+            undefined,
+            this.finalChunkGenerationInfo
+          )
+          : super._createResponseChunk(chunk);
       yield responseChunk;
       void runManager?.handleLLMNewToken(chunk);
     }