@librechat/agents 3.7.0 → 3.7.2

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