@librechat/agents 3.7.0 → 3.7.1

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

@@ -91,6 +91,12 @@ interface LangChainMessage {
 export declare const formatFromLangChain: (message: LangChainMessage) => Record<string, any>;
 interface FormatAgentMessagesOptions {
     provider?: ProviderName;
+    /** Emit flattenable text content as the joined string the legacy-content
+     *  projection would produce, so the per-request `formatContentStrings` pass
+     *  finds nothing to convert and every history message keeps its identity —
+     *  which is what lets exact-count reuse skip re-tokenizing it. Set this if
+     *  and only if the run's provider uses legacy string content. */
+    legacyContent?: boolean;
     /** Reconstruct hidden `reasoning_content` from `THINK` parts onto prior
      *  tool-call messages. Explicit opt-in for OpenAI-compatible endpoints that
      *  replay reasoning across turns; defaults to on for DeepSeek thinking-mode. */

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

@@ -16,3 +16,4 @@ export * from './reducer';
 export * from './recency';
 export * from './assistantPhase';
 export * from './provenance';
+export * from './projectionInvariant';

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

@@ -0,0 +1,25 @@
+import type { BaseMessage } from '@langchain/core/messages';
+export type ProviderMessageProjectionInvariantMode = 'off' | 'observe' | 'assert';
+export type ProviderMessageProjectionIssueCode = 'absent_provenance' | 'invalid_provenance' | 'unsourced_non_synthetic_part';
+export interface ProviderMessageProjectionInvariantIssue {
+    readonly code: ProviderMessageProjectionIssueCode;
+    readonly messageIndex: number;
+    readonly messageType: string;
+}
+export interface ProviderMessageProjectionInvariantReport {
+    readonly valid: boolean;
+    readonly messageCount: number;
+    readonly sourceBackedMessageCount: number;
+    readonly syntheticMessageCount: number;
+    readonly gapMessageCount: number;
+    readonly issues: readonly ProviderMessageProjectionInvariantIssue[];
+}
+/** Resolves the opt-in provider projection invariant without enabling it for
+ * unrecognized values. */
+export declare function resolveProviderMessageProjectionInvariantMode(value?: string | undefined): ProviderMessageProjectionInvariantMode;
+/** Inspects provider-bound lineage without reading message content or source ids. */
+export declare function inspectProviderMessageProjection(messages: readonly BaseMessage[]): ProviderMessageProjectionInvariantReport;
+export declare class ProviderMessageProjectionInvariantError extends Error {
+    readonly report: ProviderMessageProjectionInvariantReport;
+    constructor(report: ProviderMessageProjectionInvariantReport);
+}

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

@@ -73,6 +73,16 @@ export declare function hasBijectiveProviderContentPartMapping(parts: readonly P
 export declare function getProviderSourceMessageIds(message: BaseMessage): string[];
 /** Replaces typed provenance and synchronizes its stable plural source ids. */
 export declare function setProviderMessageProvenance(message: BaseMessage, parts: readonly ProviderMessageProvenancePart[]): void;
+/**
+ * {@link setProviderMessageProvenance} for a message the caller itself just
+ * constructed from locally built plain objects. Such a message cannot carry
+ * proxies, accessors, or foreign aliases in `additional_kwargs`/`lc_kwargs`,
+ * so the publication skips the hardened descriptor walks while producing the
+ * same end state: fresh replacement objects on both slots, with the
+ * serialization mirror aliasing the live kwargs. Never call this with a
+ * message received across a seam — that is what the hardened variant is for.
+ */
+export declare function setFreshProviderMessageProvenance(message: BaseMessage, parts: readonly ProviderMessageProvenancePart[]): void;
 /** Publishes the canonical fail-closed marker for malformed provenance. */
 export declare function setInvalidProviderMessageProvenance(message: BaseMessage): void;
 /** Marks a provider-visible runtime message as host-generated context. */

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

@@ -1,20 +1,21 @@
 import type { BaseMessage } from '@langchain/core/messages';
 export declare const DEFAULT_RETAIN_RECENT_TURNS = 2;
+export declare const DEFAULT_INTRA_TURN_RETAIN_RATIO = 0.16;
 /**
  * Configuration for splitting a message list into a head (to be summarized)
  * and a tail (to be preserved verbatim).
  */
 export interface RecencyWindowOptions {
     /**
-     * Maximum number of recent user-led turns to keep in the tail.  A "turn"
-     * begins at a HumanMessage and includes every following AIMessage and
-     * ToolMessage up to (but not including) the next HumanMessage.  Cutting
-     * at turn boundaries guarantees that tool_use / tool_result pairs are
-     * never split across the head/tail divide.
+     * Maximum number of recent user-led turns to keep in the tail. A "turn"
+     * begins at a user-authored HumanMessage and includes every following
+     * AIMessage and tool result up to the next user-authored HumanMessage.
+     * Provider-native HumanMessages containing only tool results remain in the
+     * current turn, so the boundary cannot split them from their calls.
      *
-     * The most recent turn is always preserved regardless of this value or
-     * the token cap, so that a single oversized first message is never
-     * destroyed by summarization.
+     * The most recent turn is preserved unless `intraTurnTokens` enables the
+     * pairing-balanced fallback for a tool-heavy history. A lone oversized user
+     * message is never eligible for that fallback.
      *
      * Defaults to `2`.  A value of `0` disables the recency window (head =
      * everything, tail = empty), restoring the pre-recency-window behavior.
@@ -32,29 +33,40 @@ export interface RecencyWindowOptions {
     tokens?: number;
     /** Token-counter used to evaluate the optional `tokens` cap. */
     tokenCounter?: (m: BaseMessage) => number;
+    /**
+     * Minimum token budget to retain when the turn window would otherwise make
+     * the whole history indivisible. When set with `tokenCounter`, older closed
+     * tool-call/result units may be summarized from within the earliest retained
+     * turn. A lone user payload and open tool units remain indivisible.
+     */
+    intraTurnTokens?: number;
 }
 export interface RecencySplit {
     /** Older messages eligible for summarization.  Empty when nothing to summarize. */
     head: BaseMessage[];
-    /** Recent messages preserved verbatim.  Always contains the most recent turn when any HumanMessage exists. */
+    /** Recent messages preserved verbatim, beginning at a pairing-balanced boundary. */
     tail: BaseMessage[];
     /** Number of user-led turns retained in the tail (0 if no HumanMessage exists). */
     tailTurnCount: number;
     /** Index in the original `messages` array where the tail begins. */
     tailStartIndex: number;
+    /** True when the pairing-balanced fallback selected the boundary. */
+    usedIntraTurnFallback: boolean;
 }
+export declare function resolveIntraTurnRetainTokens({ tokens, maxContextTokens, }: {
+    tokens?: number;
+    maxContextTokens?: number;
+}): number | undefined;
 /**
  * Splits `messages` into a head (older, to summarize) and a tail (recent,
- * to preserve verbatim) at user-message boundaries.  The most recent
- * user-led turn is always included in the tail; additional older turns
- * are added subject to `turns` and `tokens` caps.
+ * to preserve verbatim), preferring user-message boundaries. The most recent
+ * user-led turn is normally included in the tail; additional older turns are
+ * added subject to `turns` and `tokens` caps.
  *
- * Cutting strictly at HumanMessage boundaries ensures that:
- * - tool_use ↔ tool_result pairs are never split (they always live within
- *   the same turn);
- * - the first user message is never replaced by a summary, addressing
- *   the "first turn destruction" failure mode where a single large
- *   user-pasted payload would otherwise be replaced by a generic summary.
+ * When that policy exposes no compactable head, `intraTurnTokens` may select
+ * a boundary after older closed tool-call/result units. This keeps runaway
+ * first-turn tool loops compactable without splitting parallel calls from
+ * their results. A user payload without a completed tool unit stays intact.
  *
  * When `messages` contains no HumanMessage (degenerate state — e.g. system
  * + assistant messages from a programmatic preamble), everything is

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

@@ -0,0 +1,11 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { SessionEntry } from './types';
+export interface DerivedSessionMessages {
+    initialSummary?: {
+        text: string;
+        tokenCount: number;
+    };
+    messages: BaseMessage[];
+}
+/** Derives the active model context from one append-only session-log path. */
+export declare function deriveMessages(entries: readonly SessionEntry[]): DerivedSessionMessages;

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

@@ -1,5 +1,7 @@
 export { AgentSession, createAgentSession } from './AgentSession';
+export { deriveMessages } from './deriveMessages';
 export { JsonlSessionStore, SessionManager } from './JsonlSessionStore';
 export { createRunHandlers } from './handlers';
 export { serializeMessage, deserializeMessage, extractTextFromContent, } from './messageSerialization';
 export type { AgentSessionConfig, AgentSessionCheckpointLookupOptions, AgentSessionCheckpointReference, AgentSessionCheckpointing, AgentSessionCheckpointingOptions, AgentSessionHandlersResult, AgentSessionInput, AgentSessionRunOptions, AgentSessionRunResult, AgentSessionStream, AgentSessionStreamEvent, AgentSessionUsage, CreateSessionFileOptions, JsonObject, JsonPrimitive, JsonValue, SerializedSessionMessage, SessionBranchOptions, SessionCompactOptions, SessionCheckpointEntry, SessionCompactionEntry, SessionEntry, SessionEntryBase, SessionEntryType, SessionForkOptions, SessionHeader, SessionLabelEntry, SessionListItem, SessionMessageEntry, SessionPosition, SessionRunEventEntry, SessionStateEntry, SessionSummaryEntry, SessionTreeNode, } from './types';
+export type { DerivedSessionMessages } from './deriveMessages';

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

@@ -1,8 +1,9 @@
-import type { SubagentTaskClaim, SubagentTaskControlCommand, SubagentTaskControlResult, SubagentTaskSnapshot, SubagentTaskStartRequest, SubagentTaskStartResult, SubagentTaskStore } from '@/types';
+import type { SubagentTaskClaim, SubagentTaskControlCommand, SubagentTaskControlReceipt, SubagentTaskControlResult, SubagentTaskSnapshot, SubagentTaskStartRequest, SubagentTaskStartResult, SubagentTaskStore } from '@/types';
 export interface InMemorySubagentTaskStoreOptions {
     completedTtlMs?: number;
     maxControlMessageChars?: number;
     maxControlsPerTask?: number;
+    maxControlReceiptsPerTask?: number;
     maxErrorChars?: number;
     maxResultChars?: number;
     maxRunningPerScope?: number;
@@ -25,6 +26,14 @@ export declare class InMemorySubagentTaskStore implements SubagentTaskStore {
     private runningTasks;
     private totalTasks;
     constructor(options?: InMemorySubagentTaskStoreOptions);
+    /**
+     * Payload-free transition seam for hosts that durably project authoritative
+     * receipts. Implementations must return synchronously, must not reproduce
+     * task-store transition rules, and cannot veto task-store state transitions:
+     * hook failures are deliberately isolated by the caller.
+     */
+    protected onControlReceipt(_scopeId: string, _taskId: string, _receipt: SubagentTaskControlReceipt): void;
+    private emitControlReceipt;
     start(request: SubagentTaskStartRequest): SubagentTaskStartResult;
     get(scopeId: string, taskId: string): SubagentTaskSnapshot | undefined;
     list(scopeId: string): SubagentTaskSnapshot[];
@@ -37,6 +46,9 @@ export declare class InMemorySubagentTaskStore implements SubagentTaskStore {
     private sweepBucket;
     private removeTask;
     private dropEmptyBucket;
+    private makeRoomForControlReceipt;
+    private transitionControl;
+    private failPendingControls;
     private scheduleExpiry;
     private clearTaskExpiry;
     private clearTaskTimeout;

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

@@ -452,7 +452,7 @@ export type ExecutableSubagentConfig = ResolvedSubagentConfig | LazySingleAgentS
 /** Graph-aware config accepted by the executor. Graph configs stay eager. */
 export type ExecutableSubagentConfigEntry = ExecutableSubagentConfig | GraphSubagentConfig;
 /** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
-export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'run_step_closed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
+export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'run_step_closed' | 'message_delta' | 'reasoning_delta' | 'control' | 'stop' | 'error';
 export interface SubagentAncestryEntry {
     readonly subagentRunId: string;
     readonly subagentType: string;

package/dist/types/types/subagentTasks.d.ts

@@ -5,6 +5,22 @@ import type { InjectedMessage } from './tools';
 export type SubagentTaskStatus = 'running' | 'completed' | 'error' | 'cancelled';
 /** Where a pending parent message may enter the child run. */
 export type SubagentTaskBoundary = 'preempt' | 'tool' | 'turn';
+/**
+ * Lifecycle of one parent-to-child message after the task store accepts it.
+ * Hosts may render a transient `submitted` state before this authoritative
+ * receipt exists; that transport state is intentionally not persisted here.
+ */
+export type SubagentTaskControlReceiptStatus = 'accepted' | 'applied' | 'rejected' | 'failed';
+/** Bounded authoritative receipt for one steer, queue, or interrupt command. */
+export interface SubagentTaskControlReceipt {
+    controlId: string;
+    action: 'steer' | 'queue' | 'interrupt';
+    status: SubagentTaskControlReceiptStatus;
+    createdAt: number;
+    updatedAt: number;
+    boundary?: SubagentTaskBoundary;
+    reason?: 'withdrawn' | 'task_completed' | 'task_cancelled' | 'task_failed';
+}
 /** Parent-to-child control operations accepted while a task is running. */
 export type SubagentTaskControlCommand = {
     action: 'steer' | 'queue' | 'interrupt';
@@ -39,6 +55,12 @@ export interface SubagentTaskSnapshot {
     resultAvailable: boolean;
     resultClaimed: boolean;
     pendingControls: number;
+    /**
+     * Bounded receipts emitted by stores that support authoritative control
+     * tracking. Optional so legacy and custom stores remain compatible during
+     * rolling upgrades.
+     */
+    controlReceipts?: SubagentTaskControlReceipt[];
     progress?: SubagentTaskProgress;
     error?: string;
 }

package/dist/types/types/summarize.d.ts

@@ -5,25 +5,27 @@ export type SummarizationTrigger = {
     value: number;
 };
 /**
- * Controls how many recent messages are preserved verbatim during
- * compaction.  The most recent user-led turn is always preserved
- * regardless of these caps, so a single oversized first message is
- * never destroyed by summarization.
+ * Controls how much recent context is preserved verbatim during compaction.
+ * User-turn boundaries are preferred. Under context pressure, older closed
+ * tool units inside an otherwise indivisible turn may be summarized while a
+ * token-priced recent tail is retained. A lone user payload stays intact.
  */
 export type RetainRecentConfig = {
     /**
-     * Maximum number of recent user-led turns to keep in the tail.  A turn
-     * begins at a HumanMessage and includes every following AIMessage and
-     * ToolMessage up to (but not including) the next HumanMessage.  Cutting
-     * at turn boundaries guarantees tool_use / tool_result pairs are never
-     * split.  Set to `0` to disable the recency window (legacy behavior:
-     * summarize everything).  Defaults to `2`.
+     * Maximum number of recent user-led turns to keep in the tail. A turn begins
+     * at a user-authored HumanMessage and includes every following AIMessage and
+     * tool result up to the next user-authored HumanMessage. Provider-native
+     * HumanMessages containing only tool results remain in the current turn.
+     * Set to `0` to disable the recency window (legacy behavior: summarize
+     * everything). Defaults to `2`.
      */
     turns?: number;
     /**
-     * Optional cap on retained-recent tokens beyond the most recent turn.
-     * Older turns are added whole only while cumulative tokens stay below
-     * the cap.  Defaults to undefined (no cap; bounded only by `turns`).
+     * Optional retained-recent token budget. Older turns are added whole only
+     * while cumulative tokens stay below the cap. If a tool-heavy history has
+     * no compactable turn-level head, this is also the minimum recent tail kept
+     * behind a pairing-balanced intra-turn cut. When omitted, that fallback
+     * retains 16% of the configured context window.
      */
     tokens?: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.7.0",
+  "version": "3.7.1",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -218,7 +218,9 @@
     "tool_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search.ts",
     "bench:cache": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-prompt-cache.ts",
     "bench:context-pressure": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-context-pressure-cache.ts",
+    "bench:compaction-range": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-compaction-range.ts",
     "bench:provider-derivation": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-provider-derivation.ts",
+    "bench:provider-projection": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-provider-request-projection.ts",
     "bench:execution-world": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-execution-world.ts",
     "probe:overflow": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/context-overflow-probe.ts",
     "subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",

package/src/agents/AgentContext.ts

@@ -357,6 +357,8 @@ export class AgentContext {
    * - `'none'`: no summary present
    */
   private _summaryLocation: 'system_prompt' | 'user_message' | 'none' = 'none';
+  /** Whether a mid-run summary must appear before every retained message. */
+  private summaryPrecedesMessages: boolean = false;
   /**
    * Durable summary that survives reset() calls. Set from initialSummary
    * during fromConfig() and updated by setSummary() so that the latest
@@ -365,6 +367,7 @@ export class AgentContext {
    */
   private _durableSummaryText?: string;
   private _durableSummaryTokenCount: number = 0;
+  private durableSummaryPrecedesMessages: boolean = false;
   /** Number of summarization cycles that have occurred for this agent context */
   private _summaryVersion: number = 0;
   /**
@@ -989,10 +992,10 @@ export class AgentContext {
       return messages;
     }
 
-    const tailIndex = this.getPromptCacheDynamicTailIndex(
-      messages,
-      promptCacheProvider
-    );
+    const tailIndex =
+      this._summaryLocation === 'user_message' && this.summaryPrecedesMessages
+        ? 0
+        : this.getPromptCacheDynamicTailIndex(messages, promptCacheProvider);
     const stablePrefix = messages.slice(0, tailIndex);
     const trailingMessages = messages.slice(tailIndex);
     const cacheablePrefix = this.addStablePromptCacheMarkers(
@@ -1204,6 +1207,7 @@ export class AgentContext {
 
     this.summaryText = this._durableSummaryText;
     this.summaryTokenCount = this._durableSummaryTokenCount;
+    this.summaryPrecedesMessages = this.durableSummaryPrecedesMessages;
     this._lastSummarizationMsgCount = 0;
     this.lastCallUsage = undefined;
     this.totalTokensFresh = false;
@@ -1461,12 +1465,18 @@ export class AgentContext {
     }
   }
 
-  setSummary(text: string, tokenCount: number): void {
+  setSummary(
+    text: string,
+    tokenCount: number,
+    options?: { precedesMessages?: boolean }
+  ): void {
     this.summaryText = text;
     this.summaryTokenCount = tokenCount;
     this._summaryLocation = 'user_message';
+    this.summaryPrecedesMessages = options?.precedesMessages === true;
     this._durableSummaryText = text;
     this._durableSummaryTokenCount = tokenCount;
+    this.durableSummaryPrecedesMessages = this.summaryPrecedesMessages;
     this._summaryVersion += 1;
     this.systemRunnableStale = true;
     this.pruneMessages = undefined;
@@ -1477,8 +1487,10 @@ export class AgentContext {
     this.summaryText = text;
     this.summaryTokenCount = tokenCount;
     this._summaryLocation = 'system_prompt';
+    this.summaryPrecedesMessages = false;
     this._durableSummaryText = text;
     this._durableSummaryTokenCount = tokenCount;
+    this.durableSummaryPrecedesMessages = false;
     this._summaryVersion += 1;
     this.systemRunnableStale = true;
   }
@@ -1683,6 +1695,8 @@ export class AgentContext {
       this.summaryTokenCount = 0;
       this._durableSummaryText = undefined;
       this._durableSummaryTokenCount = 0;
+      this.summaryPrecedesMessages = false;
+      this.durableSummaryPrecedesMessages = false;
       this._summaryLocation = 'none';
       this.systemRunnableStale = true;
     }

package/src/graphs/Graph.ts

@@ -68,6 +68,7 @@ import {
   makeIsDeferred,
   partitionAndMarkAnthropicToolCache,
   DEFAULT_RETAIN_RECENT_TURNS,
+  resolveIntraTurnRetainTokens,
   splitAtRecencyBoundary,
   convertInjectedMessages,
   coalesceAdjacentUserTurns,
@@ -3936,6 +3937,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          */
         const estimatedPromptTokens = getEstimatedPromptTokens(contextUsage);
 
+        const recencyTokenCounter =
+          agentContext.contextPressureTokenCounts?.count ??
+          agentContext.tokenCounter;
         const canSummarizeOverflow =
           agentContext.summarizationEnabled === true &&
           splitAtRecencyBoundary(messages, {
@@ -3943,7 +3947,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               agentContext.summarizationConfig?.retainRecent?.turns ??
               DEFAULT_RETAIN_RECENT_TURNS,
             tokens: agentContext.summarizationConfig?.retainRecent?.tokens,
-            tokenCounter: agentContext.tokenCounter,
+            tokenCounter: recencyTokenCounter,
+            intraTurnTokens: resolveIntraTurnRetainTokens({
+              tokens: agentContext.summarizationConfig?.retainRecent?.tokens,
+              maxContextTokens: agentContext.maxContextTokens,
+            }),
           }).head.length > 0;
 
         const getLocalProviderOverflowMeasurement = (

package/src/llm/invoke.ts

@@ -1,5 +1,6 @@
 import { concat } from '@langchain/core/utils/stream';
 import { AIMessageChunk } from '@langchain/core/messages';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { getCallbackManagerForConfig } from '@langchain/core/runnables';
 import {
   CallbackManager,
@@ -40,7 +41,12 @@ import { assertNotTruncatedToolCall } from '@/llm/truncation';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { getContextOverflowInfo } from '@/utils/errors';
 import { appendCallbacks } from '@/utils/callbacks';
-import { modifyDeltaProperties } from '@/messages';
+import {
+  inspectProviderMessageProjection,
+  ProviderMessageProjectionInvariantError,
+  resolveProviderMessageProjectionInvariantMode,
+  modifyDeltaProperties,
+} from '@/messages';
 import { canSealPreempt } from '@/llm/preempt';
 import { initializeModel } from '@/llm/init';
 
@@ -106,6 +112,79 @@ export type OnChunk = (
 /** Unique per-model-attempt sequence; see the stamp in `attemptInvoke`. */
 let streamLimitAttemptSeq = 0;
 
+function createModelStartHandler({
+  config,
+  mode,
+  provider,
+  captureRunId,
+}: {
+  config: RunnableConfig;
+  mode: ReturnType<typeof resolveProviderMessageProjectionInvariantMode>;
+  provider: t.ProviderName;
+  captureRunId?: (runId: string) => void;
+}): BaseCallbackHandler {
+  let inspected = false;
+  const handler = BaseCallbackHandler.fromMethods({
+    handleChatModelStart: async (
+      _llm: Serialized,
+      messageBatches: BaseMessage[][],
+      runId: string
+    ): Promise<void> => {
+      captureRunId?.(runId);
+      if (mode === 'off' || inspected) {
+        return;
+      }
+      inspected = true;
+      const report = inspectProviderMessageProjection(messageBatches[0] ?? []);
+      if (report.valid) {
+        return;
+      }
+      if (mode === 'assert') {
+        throw new ProviderMessageProjectionInvariantError(report);
+      }
+      try {
+        const callbackManager = await getCallbackManagerForConfig(config);
+        await callbackManager?.handleCustomEvent?.(
+          GraphEvents.ON_AGENT_LOG,
+          {
+            level: 'warn',
+            scope: 'projection',
+            message: 'Provider message projection has provenance gaps',
+            data: { provider, report },
+            runId,
+          } satisfies t.AgentLogEvent,
+          runId
+        );
+      } catch {
+        return;
+      }
+    },
+  });
+  handler.name = 'provider-message-projection-invariant';
+  handler.raiseError = mode === 'assert';
+  handler.awaitHandlers = true;
+  return handler;
+}
+
+function withModelStartHandler({
+  config,
+  mode,
+  provider,
+  captureRunId,
+}: {
+  config: RunnableConfig;
+  mode: ReturnType<typeof resolveProviderMessageProjectionInvariantMode>;
+  provider: t.ProviderName;
+  captureRunId?: (runId: string) => void;
+}): RunnableConfig {
+  return {
+    ...config,
+    callbacks: appendCallbacks(config.callbacks, [
+      createModelStartHandler({ config, mode, provider, captureRunId }),
+    ]),
+  };
+}
+
 function getManualToolStreamNormalizationProvider(
   provider: t.ProviderName
 ): t.ProviderName {
@@ -632,6 +711,24 @@ async function attemptInvokeBody(
   config: RunnableConfig
 ): Promise<Partial<t.BaseGraphState>> {
   const { model, messages: messagesForProvider, provider } = request;
+  const projectionInvariantMode =
+    resolveProviderMessageProjectionInvariantMode();
+  let sealedRunId: string | undefined;
+  let invocationConfig = config;
+  const captureModelRunId =
+    model.stream != null && context?.preemption != null;
+  if (projectionInvariantMode !== 'off' || captureModelRunId) {
+    invocationConfig = withModelStartHandler({
+      config,
+      mode: projectionInvariantMode,
+      provider,
+      captureRunId: captureModelRunId
+        ? (runId: string): void => {
+          sealedRunId ??= runId;
+        }
+        : undefined,
+    });
+  }
 
   /**
    * Stamp the provider that is ACTUALLY serving this invocation onto the
@@ -647,28 +744,10 @@ async function attemptInvokeBody(
      * Observed, not dictated. `handleChatModelStart` fires with the chat
      * model's real run id before the first chunk, which is the only way to
      * name the run a seal has to close — pinning `config.runId` does not
-     * survive the bound runnable. Installed only when preemption is
-     * configured, so a run that cannot seal carries no extra handler.
+     * survive the bound runnable. The same handler owns the opt-in projection
+     * invariant so enabled diagnostics do not stack a second model callback.
      */
-    let sealedRunId: string | undefined;
-    const streamConfig =
-      context?.preemption == null
-        ? config
-        : {
-          ...config,
-          callbacks: appendCallbacks(config.callbacks, [
-            {
-              handleChatModelStart: (
-                _llm: Serialized,
-                _messages: BaseMessage[][],
-                runId: string
-              ): void => {
-                sealedRunId ??= runId;
-              },
-            },
-          ]),
-        };
-    const stream = await model.stream(messagesForProvider, streamConfig);
+    const stream = await model.stream(messagesForProvider, invocationConfig);
     let finalChunk: AIMessageChunk | undefined;
     let preempted = false;
     const registeredStreamHandler =
@@ -855,7 +934,7 @@ async function attemptInvokeBody(
     return { messages: [finalChunk as AIMessageChunk] };
   }
 
-  const finalMessage = await model.invoke(messagesForProvider, config);
+  const finalMessage = await model.invoke(messagesForProvider, invocationConfig);
   if ((finalMessage.tool_calls?.length ?? 0) > 0) {
     finalMessage.tool_calls = finalMessage.tool_calls?.filter(
       (tool_call: ToolCall) => !!tool_call.name

package/src/messages/content.ts

@@ -22,6 +22,20 @@ export const isLegacyConvertible = (message: BaseMessage): boolean => {
   return message.content.every((block) => block.type === ContentTypes.TEXT);
 };
 
+/** Joins the text of {@link isLegacyConvertible} content blocks into the exact
+ *  string {@link formatContentStrings} has always produced for them. */
+export const flattenLegacyContent = (
+  blocks: MessageContentComplex[]
+): string => {
+  const content = blocks.reduce((acc, curr) => {
+    if (curr.type === ContentTypes.TEXT) {
+      return `${acc}${curr[ContentTypes.TEXT] ?? ''}\n`;
+    }
+    return acc;
+  }, '');
+  return content.trim();
+};
+
 /**
  * Formats an array of messages for LangChain, making sure all content fields are strings
  * @param {Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>} payload - The array of messages to format.
@@ -39,16 +53,12 @@ export const formatContentStrings = (
       continue;
     }
 
-    // Reduce text types to a single string
-    const blocks = message.content as MessageContentComplex[];
-    const content = blocks.reduce((acc, curr) => {
-      if (curr.type === ContentTypes.TEXT) {
-        return `${acc}${curr[ContentTypes.TEXT] ?? ''}\n`;
-      }
-      return acc;
-    }, '');
-
-    result.push(cloneMessage(message, content.trim()));
+    result.push(
+      cloneMessage(
+        message,
+        flattenLegacyContent(message.content as MessageContentComplex[])
+      )
+    );
   }
 
   return result;