@librechat/agents 3.6.16 → 3.7.1

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/dist/types/utils/llm.d.ts

@@ -1,4 +1,14 @@
 import type { ProviderName } from '@/types';
+/** Walks the constructor chain for LangChain's `lc_name` serialization ids.
+ *  Constructor identity is unusable across lazily loaded module formats — the
+ *  CJS and ESM builds carry distinct classes — so guards match on the ids the
+ *  relevant classes declare instead of on `instanceof`. */
+export declare function constructorChainHasLcName(model: unknown, names: ReadonlySet<string>): boolean;
+/** Matches exactly the instances that were `instanceof` this package's
+ *  `ChatOpenAI`/`AzureChatOpenAI`: only those classes declare the
+ *  `LibreChatOpenAI`/`LibreChatAzureOpenAI` ids, their subclasses keep them in
+ *  the chain, and upstream `@langchain/openai` classes never carry them. */
+export declare function isLibreChatOpenAIModel(model: unknown): model is import('@/llm/openai').ChatOpenAI | import('@/llm/openai').AzureChatOpenAI;
 export declare function isOpenAILike(provider?: ProviderName): boolean;
 export declare function isGoogleLike(provider?: ProviderName): boolean;
 /** Returns true for native Anthropic or Bedrock running a Claude model. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.6.16",
+  "version": "3.7.1",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -78,6 +78,41 @@
       "types": "./dist/types/langchain/utils/env.d.ts",
       "import": "./dist/esm/langchain/utils/env.mjs",
       "require": "./dist/cjs/langchain/utils/env.cjs"
+    },
+    "./llm/openai": {
+      "types": "./dist/types/llm/openai/index.d.ts",
+      "import": "./dist/esm/llm/openai/index.mjs",
+      "require": "./dist/cjs/llm/openai/index.cjs"
+    },
+    "./llm/mistral": {
+      "types": "./dist/types/llm/mistral/index.d.ts",
+      "import": "./dist/esm/llm/mistral/index.mjs",
+      "require": "./dist/cjs/llm/mistral/index.cjs"
+    },
+    "./llm/anthropic": {
+      "types": "./dist/types/llm/anthropic/index.d.ts",
+      "import": "./dist/esm/llm/anthropic/index.mjs",
+      "require": "./dist/cjs/llm/anthropic/index.cjs"
+    },
+    "./llm/google": {
+      "types": "./dist/types/llm/google/index.d.ts",
+      "import": "./dist/esm/llm/google/index.mjs",
+      "require": "./dist/cjs/llm/google/index.cjs"
+    },
+    "./llm/bedrock": {
+      "types": "./dist/types/llm/bedrock/index.d.ts",
+      "import": "./dist/esm/llm/bedrock/index.mjs",
+      "require": "./dist/cjs/llm/bedrock/index.cjs"
+    },
+    "./llm/vertexai": {
+      "types": "./dist/types/llm/vertexai/index.d.ts",
+      "import": "./dist/esm/llm/vertexai/index.mjs",
+      "require": "./dist/cjs/llm/vertexai/index.cjs"
+    },
+    "./llm/openrouter": {
+      "types": "./dist/types/llm/openrouter/index.d.ts",
+      "import": "./dist/esm/llm/openrouter/index.mjs",
+      "require": "./dist/cjs/llm/openrouter/index.cjs"
     }
   },
   "typesVersions": {
@@ -96,6 +131,27 @@
       ],
       "responses": [
         "dist/types/responses/index.d.ts"
+      ],
+      "llm/openai": [
+        "./dist/types/llm/openai/index.d.ts"
+      ],
+      "llm/mistral": [
+        "./dist/types/llm/mistral/index.d.ts"
+      ],
+      "llm/anthropic": [
+        "./dist/types/llm/anthropic/index.d.ts"
+      ],
+      "llm/google": [
+        "./dist/types/llm/google/index.d.ts"
+      ],
+      "llm/bedrock": [
+        "./dist/types/llm/bedrock/index.d.ts"
+      ],
+      "llm/vertexai": [
+        "./dist/types/llm/vertexai/index.d.ts"
+      ],
+      "llm/openrouter": [
+        "./dist/types/llm/openrouter/index.d.ts"
       ]
     }
   },
@@ -162,6 +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

@@ -53,9 +53,8 @@ import {
   cloneMessage,
   CALIBRATION_RATIO_MAX,
   createPruneMessages,
-  projectToolCallInputs,
+  projectToolMessagesForProvider,
   calculateMaxToolCallInputChars,
-  projectToolStreamContentForProvider,
   syncBudgetDerivedFields,
   addTailCacheControl,
   resolvePromptCacheTtl,
@@ -69,6 +68,7 @@ import {
   makeIsDeferred,
   partitionAndMarkAnthropicToolCache,
   DEFAULT_RETAIN_RECENT_TURNS,
+  resolveIntraTurnRetainTokens,
   splitAtRecencyBoundary,
   convertInjectedMessages,
   coalesceAdjacentUserTurns,
@@ -3178,15 +3178,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       const maxProviderToolResultChars =
         agentContext.maxToolResultChars ??
         calculateMaxToolResultChars(agentContext.maxContextTokens);
-      const beforeToolStreamProjection = finalMessages;
-      finalMessages = trackProviderMessageOrigins(
-        beforeToolStreamProjection,
-        projectToolStreamContentForProvider(beforeToolStreamProjection)
-      );
       const beforeToolInputProjection = finalMessages;
       finalMessages = trackProviderMessageOrigins(
         beforeToolInputProjection,
-        projectToolCallInputs(
+        projectToolMessagesForProvider(
           beforeToolInputProjection,
           calculateMaxToolCallInputChars(agentContext.maxContextTokens)
         )
@@ -3942,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, {
@@ -3949,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/index.ts

@@ -70,8 +70,9 @@ export type { Interrupt } from '@langchain/langgraph';
 
 /* LLM */
 export { markTokenCounterCacheCompatible } from './llm/tokenCounterCacheCompatibility';
-export { CustomOpenAIClient } from './llm/openai';
-export { ChatOpenRouter } from './llm/openrouter';
+/** Provider chat-model classes moved off the root barrel: importing any of them here
+ *  forced every host to pay that provider SDK's module init at boot. They remain
+ *  available from their own entries, e.g. `@librechat/agents/llm/openai`. */
 export type {
   OpenRouterReasoning,
   OpenRouterReasoningEffort,
@@ -83,7 +84,6 @@ export type {
   ProviderFamily,
   ProviderRegistrationOptions,
 } from './provider-registration';
-export { CustomChatMistralAI } from './llm/mistral';
 export {
   smoothStream,
   resolveStreamDelay,

package/src/lazyRequire.ts

@@ -0,0 +1,67 @@
+import { createRequire } from 'node:module';
+
+/**
+ * Synchronous on-demand module loading: provider SDKs and other heavy dependencies
+ * load with their first request instead of at import time. This is the only module
+ * that touches `import.meta`; jest maps it to `test/stubs/lazyRequire.ts` so suites
+ * resolve source modules through their own resolver (the same precedent as the
+ * `@langchain/mistralai` stub).
+ *
+ * Internal modules load as format-matched siblings — `.cjs` neighbors from the CJS
+ * build and `.mjs` neighbors from the ESM build (Node's `require(esm)`, safe on the
+ * declared `>=24` engine) — so a lazily resolved provider shares one LangChain class
+ * graph with the code that requested it. Under a source-mode runner such as `tsx`,
+ * the seam resolves the TypeScript source directly through the active loader.
+ */
+const moduleUrl = import.meta.url;
+const requireModule = createRequire(moduleUrl);
+
+function detectBuildExtension(url: string): '.cjs' | '.mjs' | null {
+  if (url.endsWith('.mjs')) {
+    return '.mjs';
+  }
+  if (url.endsWith('.cjs')) {
+    return '.cjs';
+  }
+  return null;
+}
+
+const buildExtension = detectBuildExtension(moduleUrl);
+
+/** False when the package runs from TypeScript source, where dist siblings do
+ *  not exist and lazily loadable modules must be registered up front. */
+export function isBuiltRuntime(): boolean {
+  return buildExtension != null;
+}
+
+/** Source-mode commands run the TypeScript through an ESM loader that a synchronous
+ *  CJS `require` can neither reach nor share module identity with, so lazily loadable
+ *  modules are provided up front instead: `@/llm/providers.eager` imports them through
+ *  the active loader and registers them here. */
+const sourceModeModules = new Map<string, unknown>();
+
+export function registerSourceModeModules(modules: Record<string, unknown>): void {
+  for (const [relativePath, moduleExports] of Object.entries(modules)) {
+    sourceModeModules.set(relativePath, moduleExports);
+  }
+}
+
+/** Loads a module of this package by its src-relative path, e.g. `llm/openai/index`. */
+export function requireInternalModule<T>(relativePath: string): T {
+  if (buildExtension != null) {
+    return requireModule(`./${relativePath}${buildExtension}`) as T;
+  }
+  const provided = sourceModeModules.get(relativePath);
+  if (provided == null) {
+    throw new Error(
+      `Lazily loaded module "${relativePath}" is unavailable when running from source; ` +
+        'import \'@/llm/providers.eager\' at the entrypoint before any model is used.'
+    );
+  }
+  return provided as T;
+}
+
+/** Loads a third-party package on first use; identity-sensitive callers must not use this. */
+export function requireLazyModule<T>(specifier: string): T {
+  return requireModule(specifier) as T;
+}

package/src/llm/bedrock/toolCache.ts

@@ -4,7 +4,11 @@ import type { OpenAIClient } from '@langchain/openai';
 import type { DocumentType } from '@smithy/types';
 import type { GraphTools } from '@/types';
 import { buildBedrockCachePoint, type PromptCacheTtl } from '@/messages/cache';
-import { _convertToOpenAITool } from '@/llm/openai';
+import { requireInternalModule } from '@/lazyRequire';
+
+/** Loads with the first Bedrock request rather than alongside every graph. */
+const convertToOpenAITool: typeof import('@/llm/openai')._convertToOpenAITool = (...args) =>
+  requireInternalModule<typeof import('@/llm/openai')>('llm/openai/index')._convertToOpenAITool(...args);
 
 const BEDROCK_TOOL_CACHE_MARKER = '__lc_bedrock_cache_point_after';
 const BEDROCK_TOOL_CACHE_DISABLED_MARKER = '__lc_bedrock_skip_tool_cache';
@@ -77,7 +81,7 @@ function toBedrockTool(tool: unknown): BedrockToolWithCacheMarker {
   }
 
   return openAIToBedrockTool(
-    _convertToOpenAITool(tool as BindToolsInput) as OpenAIFunctionTool
+    convertToOpenAITool(tool as BindToolsInput) as OpenAIFunctionTool
   ) as BedrockToolWithCacheMarker;
 }
 

package/src/llm/init.ts

@@ -1,9 +1,7 @@
-import { ChatVertexAI } from '@langchain/google-vertexai';
 import type { Runnable } from '@langchain/core/runnables';
 import type * as t from '@/types';
-import { ChatOpenAI, AzureChatOpenAI } from '@/llm/openai';
 import { getChatModelClass } from '@/llm/providers';
-import { isOpenAILike } from '@/utils';
+import { isOpenAILike, isLibreChatOpenAIModel, constructorChainHasLcName } from '@/utils';
 import { Providers } from '@/common';
 
 type InitializeModelParams<P extends t.ProviderName> = {
@@ -30,6 +28,18 @@ type InitializeModelParams<P extends t.ProviderName> = {
           })
 );
 
+const VERTEX_LC_NAMES: ReadonlySet<string> = new Set(['ChatVertexAI']);
+
+/** Structural stand-in for `instanceof ChatVertexAI`: matches both builds of
+ *  `@langchain/google-vertexai`, while this package's own vertex class reports
+ *  `LibreChatVertexAI` and keeps failing this guard exactly as it did under
+ *  `instanceof`. */
+function isLangchainVertexModel(
+  model: unknown
+): model is import('@langchain/google-vertexai').ChatVertexAI {
+  return constructorChainHasLcName(model, VERTEX_LC_NAMES);
+}
+
 /**
  * Creates a chat model instance for a given built-in or host-registered
  * provider, applies provider-specific field assignments, and optionally binds
@@ -47,10 +57,7 @@ export function initializeModel<P extends t.ProviderName>({
       (clientOptions ?? {}) as t.ProviderOptionsFor<P>
     );
 
-  if (
-    isOpenAILike(provider) &&
-    (model instanceof ChatOpenAI || model instanceof AzureChatOpenAI)
-  ) {
+  if (isOpenAILike(provider) && isLibreChatOpenAIModel(model)) {
     const opts = clientOptions as t.OpenAIClientOptions | undefined;
     if (opts) {
       model.temperature = opts.temperature as number;
@@ -59,7 +66,7 @@ export function initializeModel<P extends t.ProviderName>({
       model.presencePenalty = opts.presencePenalty as number;
       model.n = opts.n as number;
     }
-  } else if (provider === Providers.VERTEXAI && model instanceof ChatVertexAI) {
+  } else if (provider === Providers.VERTEXAI && isLangchainVertexModel(model)) {
     const opts = clientOptions as t.VertexAIClientOptions | undefined;
     if (opts) {
       model.temperature = opts.temperature as number;

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