@librechat/agents 3.7.0 → 3.7.1

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. */