@librechat/agents 3.7.0 → 3.7.2

package/src/eventActor/index.ts

@@ -0,0 +1,32 @@
+export {
+  EventActorExecutor,
+  createEventActorExecutor,
+} from './EventActorExecutor';
+export type {
+  EventActorAdapterPrepareRequest,
+  EventActorAdapterPreparation,
+  EventActorAppliedResult,
+  EventActorCheckpointFork,
+  EventActorCheckpointReference,
+  EventActorCommitRequest,
+  EventActorCommitResult,
+  EventActorDiscardReason,
+  EventActorDiscardRequest,
+  EventActorEvent,
+  EventActorExecutionRequest,
+  EventActorExecutionResult,
+  EventActorExecutorOptions,
+  EventActorHead,
+  EventActorHostAdapter,
+  EventActorInvocation,
+  EventActorInvocationContext,
+  EventActorIndeterminateResult,
+  EventActorInvocationReference,
+  EventActorInvocationResult,
+  EventActorPreparation,
+  EventActorPreparationContext,
+  EventActorPreparedInvocation,
+  EventActorPrepareRequest,
+  EventActorSettlementResult,
+  EventActorTerminalResult,
+} from './types';

package/src/eventActor/types.ts

@@ -0,0 +1,250 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+
+/** Durable event payload accepted by the actor lifecycle. */
+export type EventActorEvent =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly EventActorEvent[]
+  | { readonly [key: string]: EventActorEvent };
+
+/** Stable reference to one persisted LangGraph checkpoint. */
+export interface EventActorCheckpointReference {
+  threadId: string;
+  checkpointId?: string;
+  checkpointNs: string;
+}
+
+/** Committed logical head read before an event invocation is prepared. */
+export interface EventActorHead {
+  actorThreadId: string;
+  generation: number;
+  checkpoint?: EventActorCheckpointReference;
+}
+
+/** Invocation-owned checkpoint fork that cannot become authoritative in place. */
+export interface EventActorCheckpointFork
+  extends EventActorCheckpointReference {
+  invocationId: string;
+}
+
+export interface EventActorInvocationReference {
+  actorThreadId: string;
+  invocationId: string;
+  depth: number;
+  continuation: 'warm' | 'cold';
+  base: EventActorHead;
+  fork: EventActorCheckpointFork;
+}
+
+export interface EventActorInvocation<TEvent extends EventActorEvent>
+  extends EventActorInvocationReference {
+  event: TEvent;
+}
+
+export interface EventActorPreparedInvocation<TEvent extends EventActorEvent>
+  extends EventActorInvocation<TEvent> {
+  /**
+   * Executor-authenticated, time-bounded binding over the complete prepared
+   * invocation. Its wire representation is opaque to callers.
+   */
+  preparationDigest: string;
+}
+
+export type EventActorAdapterPreparation<TEvent extends EventActorEvent> =
+  | { status: 'ready'; invocation: EventActorInvocation<TEvent> }
+  | { status: 'checkpoint_unavailable'; head: EventActorHead };
+
+export type EventActorPreparation<TEvent extends EventActorEvent> =
+  | { status: 'ready'; invocation: EventActorPreparedInvocation<TEvent> }
+  | {
+      status: 'checkpoint_unavailable';
+      request: EventActorPrepareRequest<TEvent>;
+      head: EventActorHead;
+      /** Executor-authenticated binding over this exact request/head pair. */
+      preparationDigest: string;
+    };
+
+export type EventActorTerminalResult<TResult extends EventActorEvent> =
+  | {
+      status: 'applied';
+      result: TResult;
+      checkpoint: EventActorCheckpointFork;
+    }
+  | { status: 'completed_no_action'; result?: TResult };
+
+export type EventActorAppliedResult<TResult extends EventActorEvent> = Extract<
+  EventActorTerminalResult<TResult>,
+  { status: 'applied' }
+> & {
+  /** Executor-issued one-shot settlement for the invocation that produced this action. */
+  invocation: EventActorInvocationReference;
+};
+
+export interface EventActorIndeterminateResult<
+  TResult extends EventActorEvent,
+> {
+  /** Applied handling cannot be proven safe to retry; retain its fork. */
+  status: 'commit_indeterminate';
+  result?: TResult;
+  checkpoint: EventActorCheckpointFork;
+  error: Error;
+}
+
+export type EventActorInvocationResult<TResult extends EventActorEvent> =
+  | EventActorAppliedResult<TResult>
+  | EventActorIndeterminateResult<TResult>
+  | Extract<
+      EventActorTerminalResult<TResult>,
+      { status: 'completed_no_action' }
+    >;
+
+export interface EventActorInvocationContext {
+  signal: AbortSignal;
+  config: RunnableConfig;
+}
+
+export interface EventActorPreparationContext {
+  /** Explicit task-owned cancellation; parent-run ambient signals are excluded. */
+  signal: AbortSignal;
+}
+
+export interface EventActorPrepareRequest<TEvent extends EventActorEvent> {
+  actorThreadId: string;
+  invocationId: string;
+  depth: number;
+  event: TEvent;
+}
+
+export interface EventActorAdapterPrepareRequest<TEvent extends EventActorEvent>
+  extends EventActorPrepareRequest<TEvent> {
+  /** Unique execution-attempt namespace; invocationId remains the logical idempotency key. */
+  checkpointNs: string;
+}
+
+export interface EventActorCommitRequest<TResult extends EventActorEvent> {
+  invocation: EventActorInvocationReference;
+  expectedHead: EventActorHead;
+  checkpoint: EventActorCheckpointFork;
+  result: TResult;
+  retention: {
+    committedCheckpoints: 2;
+    dormantCheckpointTtlMs: number;
+  };
+}
+
+export type EventActorCommitResult =
+  | { status: 'committed'; head: EventActorHead }
+  | { status: 'stale'; head?: EventActorHead };
+
+/** Public settlement outcome after an action has already been applied. */
+export type EventActorSettlementResult<TResult extends EventActorEvent> =
+  | EventActorCommitResult
+  | EventActorIndeterminateResult<TResult>;
+
+export type EventActorDiscardReason =
+  | 'cancelled'
+  | 'completed_no_action'
+  | 'failed';
+
+export interface EventActorDiscardRequest {
+  invocation: EventActorInvocationReference;
+  reason: EventActorDiscardReason;
+}
+
+/**
+ * Host adapter for durable actor state and the concrete agent invocation.
+ * `commit` must compare both the expected generation and checkpoint identity
+ * atomically before advancing the logical actor head. The host mailbox
+ * deduplicates the logical `invocationId` before entering this seam, while each
+ * SDK execution attempt receives a distinct checkpoint namespace. Preparation
+ * methods own rollback until they return a ready invocation and must treat the
+ * request event as immutable. On cancellation they roll back and reject with
+ * `context.signal.reason`; cleanup failures reject with their own error so they
+ * remain observable. `invoke` returns only after its provider, stream, timer,
+ * and executor resources have been released. Once qualifying action evidence
+ * exists, `invoke` must return `applied` even if a later abort or provider
+ * failure occurs; a thrown error is therefore a definite no-action failure
+ * whose fork is safe to discard. `commit` must not reclaim an applied stale
+ * fork: the SDK retains and surfaces it as `commit_conflict` for host
+ * reconciliation. `discard` must be idempotent for the same invocation because
+ * an ambiguous cleanup failure can be retried through the public lifecycle.
+ */
+export interface EventActorHostAdapter<
+  TEvent extends EventActorEvent,
+  TResult extends EventActorEvent,
+> {
+  prepare(
+    request: EventActorAdapterPrepareRequest<TEvent>,
+    context: EventActorPreparationContext
+  ): Promise<EventActorAdapterPreparation<TEvent>>;
+  coldContinue(
+    request: EventActorAdapterPrepareRequest<TEvent>,
+    head: EventActorHead,
+    context: EventActorPreparationContext
+  ): Promise<EventActorInvocation<TEvent>>;
+  invoke(
+    invocation: EventActorInvocation<TEvent>,
+    context: EventActorInvocationContext
+  ): Promise<EventActorTerminalResult<TResult>>;
+  commit(
+    request: EventActorCommitRequest<TResult>
+  ): Promise<EventActorCommitResult>;
+  discard(request: EventActorDiscardRequest): Promise<void>;
+}
+
+export interface EventActorExecutionRequest<TEvent extends EventActorEvent> {
+  actorThreadId: string;
+  invocationId: string;
+  event: TEvent;
+  depth?: number;
+  /** Explicit task-owned signal. Ambient parent-run signals are ignored. */
+  signal?: AbortSignal;
+}
+
+export type EventActorExecutionResult<TResult extends EventActorEvent> =
+  | {
+      status: 'applied';
+      result: TResult;
+      head: EventActorHead;
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      status: 'completed_no_action';
+      result?: TResult;
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      status: 'cancelled';
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      /** The action happened, but another head won the CAS. Reconcile; do not retry. */
+      status: 'commit_conflict';
+      result: TResult;
+      checkpoint: EventActorCheckpointFork;
+      head?: EventActorHead;
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      /** Applied handling cannot be proven safe to retry; retain its fork. */
+      status: 'commit_indeterminate';
+      result?: TResult;
+      checkpoint: EventActorCheckpointFork;
+      error: Error;
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      status: 'failed';
+      error: Error;
+      continuation: 'warm' | 'cold';
+    };
+
+export interface EventActorExecutorOptions {
+  maxDepth?: number;
+  /** Also bounds signed preparation authority and local terminal fences. */
+  dormantCheckpointTtlMs?: number;
+  /** Stable private key of at least 32 bytes for cross-lifetime handoffs. */
+  preparationSigningKey?: string | Uint8Array;
+}

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/index.ts

@@ -43,6 +43,9 @@ export * from './hooks';
 /* Programmatic sessions */
 export * from './session';
 
+/* Event actors */
+export * from './eventActor';
+
 /* HITL helpers */
 export * from './hitl';
 

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;

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';