@librechat/agents 3.6.16 → 3.7.1

package/src/llm/openrouter/toolCache.ts

@@ -5,7 +5,13 @@ import {
   buildAnthropicCacheControl,
   type PromptCacheTtl,
 } from '@/messages/cache';
-import { _convertToOpenAITool } from '@/llm/openai';
+import { requireInternalModule } from '@/lazyRequire';
+
+/** Loads with the first OpenRouter request rather than alongside every graph. */
+const convertToOpenAITool = (
+  tool: BindToolsInput
+): OpenAIClient.ChatCompletionTool =>
+  requireInternalModule<typeof import('@/llm/openai')>('llm/openai/index')._convertToOpenAITool(tool);
 
 type OpenRouterCacheControl = { type: 'ephemeral'; ttl?: '1h' };
 
@@ -38,7 +44,7 @@ function hasDeferredMarker(tool: unknown): boolean {
 }
 
 function toOpenRouterTool(tool: unknown): OpenRouterToolWithCacheControl {
-  const converted = _convertToOpenAITool(
+  const converted = convertToOpenAITool(
     tool as BindToolsInput
   ) as OpenRouterToolWithCacheControl;
 

package/src/llm/providerRegistry.ts

@@ -5,8 +5,13 @@ import type {
 } from '../provider-registration';
 import type { ProviderModelConstructor, ProviderName } from '@/types';
 
+type ProviderModelClass = new (config: never) => BaseChatModel;
+
 interface StoredProviderRegistration {
-  model: new (config: never) => BaseChatModel;
+  model?: ProviderModelClass;
+  /** Built-ins defer their provider SDK import until the first model request;
+   *  the resolved class is validated once and memoized into `model`. */
+  loadModel?: () => ProviderModelClass;
   family: ProviderFamily;
   manualToolStream: boolean;
   strictAlternation: boolean;
@@ -107,6 +112,31 @@ export function registerBuiltInProvider<
   builtInProviders.set(provider, createRegistration(provider, options));
 }
 
+interface BuiltInProviderLoaderOptions {
+  provider: ProviderName;
+  loadModel: () => ProviderModelClass;
+  family?: ProviderFamily;
+  manualToolStream?: boolean;
+  strictAlternation?: boolean;
+}
+
+/** Registers a built-in whose provider SDK loads on first use, not at import time. */
+export function registerBuiltInProviderLoader(
+  options: BuiltInProviderLoaderOptions
+): void {
+  const provider = normalizeProvider(options.provider);
+  if (builtInProviders.has(provider)) {
+    throw new Error(`LLM provider already registered: ${provider}`);
+  }
+  builtInProviders.set(provider, {
+    loadModel: options.loadModel,
+    family: options.family ?? 'generic',
+    manualToolStream: options.manualToolStream ?? false,
+    strictAlternation: options.strictAlternation ?? false,
+    owner: Symbol(provider),
+  });
+}
+
 export function getRegisteredChatModelClass<P extends ProviderName>(
   provider: P
 ): ProviderModelConstructor<P> {
@@ -114,6 +144,16 @@ export function getRegisteredChatModelClass<P extends ProviderName>(
   if (!registration) {
     throw new Error(`Unsupported LLM provider: ${provider}`);
   }
+  if (registration.model == null && registration.loadModel != null) {
+    const loaded = registration.loadModel();
+    if (typeof loaded !== 'function' || !isConstructible(loaded)) {
+      throw new TypeError(`LLM provider constructor is invalid: ${provider}`);
+    }
+    registration.model = loaded;
+  }
+  if (registration.model == null) {
+    throw new Error(`Unsupported LLM provider: ${provider}`);
+  }
   return registration.model as ProviderModelConstructor<P>;
 }
 

package/src/llm/providers.eager.ts

@@ -0,0 +1,24 @@
+import * as openai from '@/llm/openai';
+import * as google from '@/llm/google';
+import * as bedrock from '@/llm/bedrock';
+import * as mistral from '@/llm/mistral';
+import * as vertexai from '@/llm/vertexai';
+import * as anthropic from '@/llm/anthropic';
+import * as openrouter from '@/llm/openrouter';
+import { registerSourceModeModules } from '@/lazyRequire';
+
+/**
+ * Source-mode counterpart of the lazy provider loading the built package uses: commands
+ * that run the TypeScript directly import this module first, so every lazily loadable
+ * provider module is loaded through the active ESM loader — one module graph, one set of
+ * class identities — and registered with the lazy-require seam.
+ */
+registerSourceModeModules({
+  'llm/openai/index': openai,
+  'llm/google/index': google,
+  'llm/bedrock/index': bedrock,
+  'llm/mistral/index': mistral,
+  'llm/vertexai/index': vertexai,
+  'llm/anthropic/index': anthropic,
+  'llm/openrouter/index': openrouter,
+});

package/src/llm/providers.ts

@@ -1,81 +1,95 @@
-import type {
-  ChatModelConstructorMap,
-  ProviderModelConstructor,
-  ProviderName,
-} from '@/types';
+import type { ProviderModelConstructor, ProviderName } from '@/types';
+import { requireInternalModule } from '@/lazyRequire';
 import type { ProviderFamily } from '../provider-registration';
-import {
-  AzureChatOpenAI,
-  ChatDeepSeek,
-  ChatMoonshot,
-  ChatOpenAI,
-  ChatXAI,
-} from '@/llm/openai';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import {
   getRegisteredChatModelClass,
-  registerBuiltInProvider,
+  registerBuiltInProviderLoader,
 } from '@/llm/providerRegistry';
-import { CustomChatGoogleGenerativeAI } from '@/llm/google';
-import { CustomChatBedrockConverse } from '@/llm/bedrock';
-import { CustomChatMistralAI } from '@/llm/mistral';
-import { CustomAnthropic } from '@/llm/anthropic';
-import { ChatOpenRouter } from '@/llm/openrouter';
-import { ChatVertexAI } from '@/llm/vertexai';
 import { Providers } from '@/common';
 
+/**
+ * Built-in provider SDKs load on first model request, not at import time: eagerly
+ * importing every provider cost hundreds of milliseconds of boot in hosts that
+ * configure one or two of them. `createRequire` keeps resolution synchronous and
+ * correct from both the CJS and ESM builds.
+ */
+
+type ProviderModelClass = new (config: never) => BaseChatModel;
+
 type BuiltInProviderTraits = {
   family: ProviderFamily;
   manualToolStream?: boolean;
   strictAlternation?: boolean;
 };
 
-function initializeBuiltInProvider<P extends Providers>(
-  provider: P,
-  model: ChatModelConstructorMap[P],
+function initializeBuiltInProvider(
+  provider: Providers,
+  loadModel: () => ProviderModelClass,
   traits: BuiltInProviderTraits
 ): void {
-  registerBuiltInProvider({
+  registerBuiltInProviderLoader({
     provider,
-    model,
+    loadModel,
     ...traits,
   });
 }
 
-initializeBuiltInProvider(Providers.XAI, ChatXAI, { family: 'openai' });
-initializeBuiltInProvider(Providers.OPENAI, ChatOpenAI, { family: 'openai' });
-initializeBuiltInProvider(Providers.AZURE, AzureChatOpenAI, {
+const fromOpenAI =
+  (name: string) => (): ProviderModelClass =>
+    (requireInternalModule<Record<string, ProviderModelClass>>('llm/openai/index'))[
+      name
+    ];
+
+initializeBuiltInProvider(Providers.XAI, fromOpenAI('ChatXAI'), { family: 'openai' });
+initializeBuiltInProvider(Providers.OPENAI, fromOpenAI('ChatOpenAI'), { family: 'openai' });
+initializeBuiltInProvider(Providers.AZURE, fromOpenAI('AzureChatOpenAI'), {
   family: 'openai',
 });
-initializeBuiltInProvider(Providers.VERTEXAI, ChatVertexAI, {
-  family: 'google',
-});
-initializeBuiltInProvider(Providers.DEEPSEEK, ChatDeepSeek, {
+initializeBuiltInProvider(
+  Providers.VERTEXAI,
+  () => (requireInternalModule<typeof import('@/llm/vertexai')>('llm/vertexai/index')).ChatVertexAI,
+  { family: 'google' }
+);
+initializeBuiltInProvider(Providers.DEEPSEEK, fromOpenAI('ChatDeepSeek'), {
   family: 'openai',
 });
-initializeBuiltInProvider(Providers.MISTRALAI, CustomChatMistralAI, {
+const loadMistral = (): ProviderModelClass =>
+  (requireInternalModule<typeof import('@/llm/mistral')>('llm/mistral/index')).CustomChatMistralAI;
+initializeBuiltInProvider(Providers.MISTRALAI, loadMistral, {
   family: 'mistral',
   strictAlternation: true,
 });
-initializeBuiltInProvider(Providers.MISTRAL, CustomChatMistralAI, {
+initializeBuiltInProvider(Providers.MISTRAL, loadMistral, {
   family: 'mistral',
   strictAlternation: true,
 });
-initializeBuiltInProvider(Providers.ANTHROPIC, CustomAnthropic, {
-  family: 'anthropic',
-  manualToolStream: true,
-});
-initializeBuiltInProvider(Providers.OPENROUTER, ChatOpenRouter, {
-  family: 'openai',
-});
-initializeBuiltInProvider(Providers.BEDROCK, CustomChatBedrockConverse, {
-  family: 'bedrock',
-  manualToolStream: true,
-  strictAlternation: true,
-});
-initializeBuiltInProvider(Providers.GOOGLE, CustomChatGoogleGenerativeAI, {
-  family: 'google',
-});
-initializeBuiltInProvider(Providers.MOONSHOT, ChatMoonshot, {
+initializeBuiltInProvider(
+  Providers.ANTHROPIC,
+  () => (requireInternalModule<typeof import('@/llm/anthropic')>('llm/anthropic/index')).CustomAnthropic,
+  { family: 'anthropic', manualToolStream: true }
+);
+initializeBuiltInProvider(
+  Providers.OPENROUTER,
+  () =>
+    (requireInternalModule<typeof import('@/llm/openrouter')>('llm/openrouter/index')).ChatOpenRouter,
+  { family: 'openai' }
+);
+initializeBuiltInProvider(
+  Providers.BEDROCK,
+  () =>
+    (requireInternalModule<typeof import('@/llm/bedrock')>('llm/bedrock/index'))
+      .CustomChatBedrockConverse,
+  { family: 'bedrock', manualToolStream: true, strictAlternation: true }
+);
+initializeBuiltInProvider(
+  Providers.GOOGLE,
+  () =>
+    (requireInternalModule<typeof import('@/llm/google')>('llm/google/index'))
+      .CustomChatGoogleGenerativeAI,
+  { family: 'google' }
+);
+initializeBuiltInProvider(Providers.MOONSHOT, fromOpenAI('ChatMoonshot'), {
   family: 'generic',
 });
 

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;

package/src/messages/core.ts

@@ -980,6 +980,19 @@ function isCompleteToolStreamContentBlock(block: unknown): boolean {
   }
 }
 
+/** Drops incomplete streamed text blocks before provider-facing tool shaping. */
+export function dropIncompleteToolStreamContent(
+  content: AIMessage['content']
+): AIMessage['content'] {
+  if (!Array.isArray(content)) {
+    return content;
+  }
+  const completeContent = content.filter(isCompleteToolStreamContentBlock);
+  return completeContent.length === content.length
+    ? content
+    : toLangChainContent(completeContent);
+}
+
 function projectPreemptedResponsesV1Content(
   content: AIMessage['content'],
   reasoning: unknown,
@@ -2026,20 +2039,12 @@ export function projectToolStreamContentForProvider(
       }
       continue;
     }
-    if (!Array.isArray(assistantMessage.content)) {
-      continue;
-    }
-    const content = assistantMessage.content.filter(
-      isCompleteToolStreamContentBlock
-    );
-    if (content.length === assistantMessage.content.length) {
+    const content = dropIncompleteToolStreamContent(assistantMessage.content);
+    if (content === assistantMessage.content) {
       continue;
     }
     projected ??= [...messages];
-    projected[i] = cloneAIMessageWithContent(
-      assistantMessage,
-      toLangChainContent(content)
-    );
+    projected[i] = cloneAIMessageWithContent(assistantMessage, content);
   }
   return projected ?? messages;
 }

package/src/messages/format.ts

@@ -46,6 +46,7 @@ import {
   hasBijectiveProviderContentPartMapping,
   inspectProviderMessageProvenance,
   inspectProviderSourceMessageIds,
+  setFreshProviderMessageProvenance,
   setInvalidProviderMessageProvenance,
   setProviderMessageProvenance,
 } from './provenance';
@@ -57,6 +58,7 @@ import {
 } from '@/utils/toolContent';
 import { normalizeAnthropicToolCallId } from '@/llm/anthropic/utils/message_inputs';
 import { toLangChainContent, toLangChainMessageFields } from './langchain';
+import { flattenLegacyContent, isLegacyConvertible } from './content';
 import { HARD_MAX_TOOL_RESULT_CHARS } from '@/utils/truncation';
 import { Providers, ContentTypes, Constants } from '@/common';
 import { emitAgentLog } from '@/utils/events';
@@ -378,6 +380,12 @@ type SourceContentPartIndices = number | readonly number[];
 
 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. */
@@ -1380,7 +1388,7 @@ function stampSourceMessageIdentity(
       },
     ];
   }
-  setProviderMessageProvenance(message, partsToStamp);
+  setFreshProviderMessageProvenance(message, partsToStamp);
   if (sourceMessageId == null || derivedIndex !== 0) {
     return;
   }
@@ -1996,6 +2004,22 @@ export const formatAgentMessages = (
    * assistant turn. Held rather than emitted so an entry that produces
    * nothing cannot leave the anchor stranded as the final turn.
    */
+  const legacyContentEnabled = options?.legacyContent === true;
+  /** Emission choke point: every formatted message enters the result here, so
+   *  the legacy flatten happens once per message with no closing rescan. The
+   *  summary boundary slices payload entries before formatting, and nothing
+   *  mutates an emitted message's content afterwards, so flattening at
+   *  emission and flattening at return are equivalent. */
+  const emitFormattedMessage = (message: (typeof messages)[number]): void => {
+    if (legacyContentEnabled && isLegacyConvertible(message)) {
+      const flattened = flattenLegacyContent(
+        message.content as MessageContentComplex[]
+      );
+      message.content = flattened;
+      message.lc_kwargs.content = flattened;
+    }
+    messages.push(message);
+  };
   let pendingSteerAnchor = false;
   /**
    * Emits the deferred anchor ahead of `next` — the message about to be
@@ -2018,7 +2042,7 @@ export const formatAgentMessages = (
       'assistant'
     );
     stampSourceMessageIdentity(anchor, undefined, 0, 'synthetic');
-    messages.push(anchor);
+    emitFormattedMessage(anchor);
   };
   // If indexTokenCountMap is provided, create a new map to track the updated indices
   const updatedIndexTokenCountMap: Record<number, number> = {};
@@ -2098,7 +2122,7 @@ export const formatAgentMessages = (
         provenanceParts
       );
       flushSteerAnchor(formattedMessage);
-      messages.push(formattedMessage);
+      emitFormattedMessage(formattedMessage);
 
       // Update the index mapping for this message
       indexMapping[i] = [messages.length - 1];
@@ -2359,7 +2383,7 @@ export const formatAgentMessages = (
       flushSteerAnchor(formattedMessages[0]);
     }
     for (const formattedMessage of formattedMessages) {
-      messages.push(formattedMessage);
+      emitFormattedMessage(formattedMessage);
     }
     if (endsWithSteerMessage(formattedMessages)) {
       pendingSteerAnchor = true;
@@ -2390,7 +2414,7 @@ export const formatAgentMessages = (
             'user'
           );
           stampSourceMessageIdentity(skillMessage, undefined, 0, 'synthetic');
-          messages.push(skillMessage);
+          emitFormattedMessage(skillMessage);
         }
       }
     }

package/src/messages/index.ts

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

package/src/messages/projectionInvariant.ts

@@ -0,0 +1,134 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import { inspectProviderMessageProvenance } from './provenance';
+
+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[];
+}
+
+const MAX_REPORTED_PROJECTION_ISSUES = 64;
+
+function getMessageType(message: BaseMessage): string {
+  try {
+    return typeof message.type === 'string' ? message.type : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function appendIssue(
+  issues: ProviderMessageProjectionInvariantIssue[],
+  code: ProviderMessageProjectionIssueCode,
+  messageIndex: number,
+  messageType: string
+): void {
+  if (issues.length >= MAX_REPORTED_PROJECTION_ISSUES) {
+    return;
+  }
+  issues.push(Object.freeze({ code, messageIndex, messageType }));
+}
+
+/** Resolves the opt-in provider projection invariant without enabling it for
+ * unrecognized values. */
+export function resolveProviderMessageProjectionInvariantMode(
+  value = process.env.AGENT_MESSAGE_PROJECTION_INVARIANT
+): ProviderMessageProjectionInvariantMode {
+  if (value === 'observe' || value === 'assert') {
+    return value;
+  }
+  return 'off';
+}
+
+/** Inspects provider-bound lineage without reading message content or source ids. */
+export function inspectProviderMessageProjection(
+  messages: readonly BaseMessage[]
+): ProviderMessageProjectionInvariantReport {
+  const issues: ProviderMessageProjectionInvariantIssue[] = [];
+  let sourceBackedMessageCount = 0;
+  let syntheticMessageCount = 0;
+  let gapMessageCount = 0;
+
+  for (let messageIndex = 0; messageIndex < messages.length; messageIndex++) {
+    const message = messages[messageIndex];
+    const messageType = getMessageType(message);
+    const state = inspectProviderMessageProvenance(message);
+    if (state.status !== 'valid') {
+      gapMessageCount++;
+      appendIssue(
+        issues,
+        state.status === 'absent'
+          ? 'absent_provenance'
+          : 'invalid_provenance',
+        messageIndex,
+        messageType
+      );
+      continue;
+    }
+
+    let hasSourceBackedPart = false;
+    let hasGap = false;
+    for (const part of state.provenance.parts) {
+      if (part.sourceMessageId != null) {
+        hasSourceBackedPart = true;
+        continue;
+      }
+      if (part.attribution === 'synthetic') {
+        continue;
+      }
+      hasGap = true;
+      appendIssue(
+        issues,
+        'unsourced_non_synthetic_part',
+        messageIndex,
+        messageType
+      );
+    }
+
+    if (hasGap) {
+      gapMessageCount++;
+    } else if (hasSourceBackedPart) {
+      sourceBackedMessageCount++;
+    } else {
+      syntheticMessageCount++;
+    }
+  }
+
+  return Object.freeze({
+    valid: gapMessageCount === 0,
+    messageCount: messages.length,
+    sourceBackedMessageCount,
+    syntheticMessageCount,
+    gapMessageCount,
+    issues: Object.freeze(issues),
+  });
+}
+
+export class ProviderMessageProjectionInvariantError extends Error {
+  readonly report: ProviderMessageProjectionInvariantReport;
+
+  constructor(report: ProviderMessageProjectionInvariantReport) {
+    super('Provider message projection invariant failed');
+    this.name = 'ProviderMessageProjectionInvariantError';
+    this.report = report;
+  }
+}

package/src/messages/provenance.ts

@@ -766,11 +766,14 @@ function publishProviderMessageProvenance(
   }
 }
 
-/** Replaces typed provenance and synchronizes its stable plural source ids. */
-export function setProviderMessageProvenance(
-  message: BaseMessage,
+interface ResolvedProvenancePublication {
+  provenance: ProviderMessageProvenance;
+  sourceMessageIds?: readonly string[];
+}
+
+function resolveProvenancePublication(
   parts: readonly ProviderMessageProvenancePart[]
-): void {
+): ResolvedProvenancePublication {
   const normalizedParts = normalizeProvenanceParts(parts);
   const provenance: ProviderMessageProvenance = Object.freeze({
     version: PROVIDER_MESSAGE_PROVENANCE_VERSION,
@@ -782,21 +785,60 @@ export function setProviderMessageProvenance(
   for (const part of normalizedParts) {
     appendSourceMessageId(sourceMessageIds, seen, part.sourceMessageId);
   }
-  if (sourceMessageIds.length > 0) {
-    const immutableSourceMessageIds = Object.freeze(sourceMessageIds);
-    immutableProviderSourceMessageIds.add(immutableSourceMessageIds);
-    immutableProviderMessageSourceIds.set(
-      provenance,
-      immutableSourceMessageIds
-    );
-    publishProviderMessageProvenance(
-      message,
-      provenance,
-      immutableSourceMessageIds
-    );
-    return;
+  if (sourceMessageIds.length === 0) {
+    return { provenance };
   }
-  publishProviderMessageProvenance(message, provenance);
+  const immutableSourceMessageIds = Object.freeze(sourceMessageIds);
+  immutableProviderSourceMessageIds.add(immutableSourceMessageIds);
+  immutableProviderMessageSourceIds.set(provenance, immutableSourceMessageIds);
+  return { provenance, sourceMessageIds: immutableSourceMessageIds };
+}
+
+/** Replaces typed provenance and synchronizes its stable plural source ids. */
+export function setProviderMessageProvenance(
+  message: BaseMessage,
+  parts: readonly ProviderMessageProvenancePart[]
+): void {
+  const resolved = resolveProvenancePublication(parts);
+  publishProviderMessageProvenance(
+    message,
+    resolved.provenance,
+    resolved.sourceMessageIds
+  );
+}
+
+/**
+ * {@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 function setFreshProviderMessageProvenance(
+  message: BaseMessage,
+  parts: readonly ProviderMessageProvenancePart[]
+): void {
+  const resolved = resolveProvenancePublication(parts);
+  const replacement: UntrustedProviderMessageAdditionalKwargs = {
+    ...message.additional_kwargs,
+  };
+  replacement.provenance = resolved.provenance;
+  const sourceMessageIds = resolved.sourceMessageIds;
+  if (sourceMessageIds != null && sourceMessageIds.length > 0) {
+    replacement.sourceMessageIds = sourceMessageIds;
+    replacement.sourceMessageId = sourceMessageIds[sourceMessageIds.length - 1];
+  } else {
+    delete replacement.sourceMessageIds;
+    delete replacement.sourceMessageId;
+  }
+  const serializedReplacement: BaseMessage['lc_kwargs'] = {
+    ...message.lc_kwargs,
+  };
+  serializedReplacement.additional_kwargs = replacement;
+  message.additional_kwargs = replacement;
+  message.lc_kwargs = serializedReplacement;
 }
 
 /** Publishes the canonical fail-closed marker for malformed provenance. */