@librechat/agents 3.7.0 → 3.7.1

package/src/messages/recency.ts

@@ -1,6 +1,27 @@
-import type { BaseMessage } from '@langchain/core/messages';
+import type {
+  AIMessage,
+  BaseMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import type {
+  ProviderToolCallIndex,
+  ProviderToolCallPartDescriptor,
+  ProviderToolResultPartDescriptor,
+} from './toolResultTypes';
+import { getProviderSourceMessageIds } from './provenance';
+import {
+  appendProviderToolCallDescriptor,
+  consumeProviderToolResultPair,
+  getBoundedProviderPairingArray,
+  getBoundedProviderPairingArrayProperty,
+  getProviderAIMessageToolCallDescriptor,
+  getProviderToolCallPartDescriptor,
+  getProviderToolResultPartDescriptor,
+  PROVIDER_TOOL_PAIRING_MAX_IDENTIFIER_CHARS,
+} from './toolResultTypes';
 
 export const DEFAULT_RETAIN_RECENT_TURNS = 2;
+export const DEFAULT_INTRA_TURN_RETAIN_RATIO = 0.16;
 
 /**
  * Configuration for splitting a message list into a head (to be summarized)
@@ -8,15 +29,15 @@ export const DEFAULT_RETAIN_RECENT_TURNS = 2;
  */
 export interface RecencyWindowOptions {
   /**
-   * 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 that tool_use / tool_result pairs are
-   * never split across the head/tail divide.
+   * 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, so the boundary cannot split them from their calls.
    *
-   * The most recent turn is always preserved regardless of this value or
-   * the token cap, so that a single oversized first message is never
-   * destroyed by summarization.
+   * The most recent turn is preserved unless `intraTurnTokens` enables the
+   * pairing-balanced fallback for a tool-heavy history. A lone oversized user
+   * message is never eligible for that fallback.
    *
    * Defaults to `2`.  A value of `0` disables the recency window (head =
    * everything, tail = empty), restoring the pre-recency-window behavior.
@@ -34,31 +55,378 @@ export interface RecencyWindowOptions {
   tokens?: number;
   /** Token-counter used to evaluate the optional `tokens` cap. */
   tokenCounter?: (m: BaseMessage) => number;
+  /**
+   * Minimum token budget to retain when the turn window would otherwise make
+   * the whole history indivisible. When set with `tokenCounter`, older closed
+   * tool-call/result units may be summarized from within the earliest retained
+   * turn. A lone user payload and open tool units remain indivisible.
+   */
+  intraTurnTokens?: number;
 }
 
 export interface RecencySplit {
   /** Older messages eligible for summarization.  Empty when nothing to summarize. */
   head: BaseMessage[];
-  /** Recent messages preserved verbatim.  Always contains the most recent turn when any HumanMessage exists. */
+  /** Recent messages preserved verbatim, beginning at a pairing-balanced boundary. */
   tail: BaseMessage[];
   /** Number of user-led turns retained in the tail (0 if no HumanMessage exists). */
   tailTurnCount: number;
   /** Index in the original `messages` array where the tail begins. */
   tailStartIndex: number;
+  /** True when the pairing-balanced fallback selected the boundary. */
+  usedIntraTurnFallback: boolean;
+}
+
+export function resolveIntraTurnRetainTokens({
+  tokens,
+  maxContextTokens,
+}: {
+  tokens?: number;
+  maxContextTokens?: number;
+}): number | undefined {
+  if (tokens != null) {
+    return Number.isFinite(tokens) && tokens > 0
+      ? Math.floor(tokens)
+      : undefined;
+  }
+  if (
+    maxContextTokens == null ||
+    !Number.isFinite(maxContextTokens) ||
+    maxContextTokens <= 0
+  ) {
+    return undefined;
+  }
+  return Math.max(
+    1,
+    Math.floor(maxContextTokens * DEFAULT_INTRA_TURN_RETAIN_RATIO)
+  );
+}
+
+function readOwnString(value: unknown, key: string): string | undefined {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor != null &&
+      'value' in descriptor &&
+      typeof descriptor.value === 'string' &&
+      descriptor.value !== '' &&
+      descriptor.value.length <= PROVIDER_TOOL_PAIRING_MAX_IDENTIFIER_CHARS
+      ? descriptor.value
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readOwnValue(value: unknown, key: string): unknown {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor != null && 'value' in descriptor
+      ? descriptor.value
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const LEGACY_FUNCTION_CALL_PREFIX = 'legacy_function:';
+
+function getLegacyFunctionCallId(name: string): string | undefined {
+  const callId = `${LEGACY_FUNCTION_CALL_PREFIX}${name}`;
+  return callId.length <= PROVIDER_TOOL_PAIRING_MAX_IDENTIFIER_CHARS
+    ? callId
+    : undefined;
+}
+
+function getRawToolCallDescriptor(
+  toolCall: unknown
+): ProviderToolCallPartDescriptor | undefined {
+  const callId = readOwnString(toolCall, 'id');
+  if (callId == null) {
+    return undefined;
+  }
+  let name: string | undefined;
+  if (toolCall != null && typeof toolCall === 'object') {
+    try {
+      const property = Object.getOwnPropertyDescriptor(toolCall, 'function');
+      name =
+        property != null && 'value' in property
+          ? readOwnString(property.value, 'name')
+          : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  return {
+    callId,
+    kind: 'tool',
+    sourceType: 'raw_tool_calls',
+    ...(name == null ? {} : { name }),
+  };
+}
+
+function appendMessageToolCalls(
+  message: BaseMessage,
+  calls: ProviderToolCallIndex
+): void {
+  const messageRole = (message as BaseMessage & { role?: unknown }).role;
+  if (message.getType() !== 'ai' && messageRole !== 'assistant') {
+    return;
+  }
+
+  for (const toolCall of (message as AIMessage).tool_calls ?? []) {
+    const descriptor = getProviderAIMessageToolCallDescriptor(toolCall);
+    if (descriptor != null) {
+      appendProviderToolCallDescriptor(calls, descriptor);
+    }
+  }
+
+  const rawToolCalls = getBoundedProviderPairingArrayProperty(
+    message.additional_kwargs,
+    'tool_calls'
+  );
+  if (rawToolCalls != null) {
+    for (const toolCall of rawToolCalls) {
+      const descriptor = getRawToolCallDescriptor(toolCall);
+      if (descriptor != null) {
+        appendProviderToolCallDescriptor(calls, descriptor);
+      }
+    }
+  }
+
+  const legacyFunctionCall = readOwnValue(
+    message.additional_kwargs,
+    'function_call'
+  );
+  const legacyFunctionName = readOwnString(legacyFunctionCall, 'name');
+  const legacyFunctionCallId =
+    legacyFunctionName == null
+      ? undefined
+      : getLegacyFunctionCallId(legacyFunctionName);
+  if (legacyFunctionCallId != null) {
+    appendProviderToolCallDescriptor(calls, {
+      callId: legacyFunctionCallId,
+      kind: 'tool',
+      name: legacyFunctionName,
+      sourceType: 'legacy_function_call',
+    });
+  }
+}
+
+function getToolMessageResultDescriptor(
+  message: BaseMessage
+): ProviderToolResultPartDescriptor | undefined {
+  if (message.getType() === 'function' && message.name != null) {
+    const toolCallId = getLegacyFunctionCallId(message.name);
+    return toolCallId == null
+      ? undefined
+      : {
+        type: 'function_message',
+        toolCallId,
+        compatibleCallKinds: ['tool'],
+        expectedToolNames: [message.name],
+      };
+  }
+  if (message.getType() !== 'tool') {
+    return undefined;
+  }
+  const toolMessage = message as ToolMessage & { toolCallId?: unknown };
+  const toolCallId =
+    typeof toolMessage.tool_call_id === 'string'
+      ? toolMessage.tool_call_id
+      : toolMessage.toolCallId;
+  return typeof toolCallId === 'string' &&
+    toolCallId !== '' &&
+    toolCallId.length <= PROVIDER_TOOL_PAIRING_MAX_IDENTIFIER_CHARS
+    ? {
+      type: 'tool_message',
+      toolCallId,
+      compatibleCallKinds: ['tool'],
+    }
+    : undefined;
+}
+
+interface MessagePairingResult {
+  completedToolCalls: number;
+  trustedHumanToolResult: boolean;
+}
+
+function inspectMessagePairing(
+  message: BaseMessage,
+  calls: ProviderToolCallIndex
+): MessagePairingResult {
+  const isHuman = message.getType() === 'human';
+  const candidateCalls = isHuman ? new Map(calls) : calls;
+  if (!isHuman) {
+    appendMessageToolCalls(message, candidateCalls);
+  }
+  const content = getBoundedProviderPairingArray(message.content);
+  let completedToolCalls = 0;
+  let resultPartCount = 0;
+  let everyPartIsTrustedHumanResult = isHuman && content != null;
+  if (content != null) {
+    let previousPart: unknown;
+    for (const part of content) {
+      const callDescriptor = getProviderToolCallPartDescriptor(part);
+      if (callDescriptor != null && !isHuman) {
+        appendProviderToolCallDescriptor(candidateCalls, callDescriptor);
+      }
+      const resultDescriptor = getProviderToolResultPartDescriptor(part);
+      if (resultDescriptor == null) {
+        everyPartIsTrustedHumanResult = false;
+      } else {
+        resultPartCount += 1;
+        const canPairHumanResult =
+          !isHuman || resultDescriptor.allowHumanMessagePairing === true;
+        if (
+          canPairHumanResult &&
+          consumeProviderToolResultPair(
+            resultDescriptor,
+            candidateCalls,
+            previousPart
+          )
+        ) {
+          completedToolCalls += 1;
+        } else {
+          everyPartIsTrustedHumanResult = false;
+        }
+      }
+      previousPart = part;
+    }
+  }
+
+  const toolMessageResult = getToolMessageResultDescriptor(message);
+  if (
+    toolMessageResult != null &&
+    consumeProviderToolResultPair(toolMessageResult, candidateCalls)
+  ) {
+    completedToolCalls += 1;
+  }
+
+  const trustedHumanToolResult =
+    everyPartIsTrustedHumanResult &&
+    resultPartCount > 0 &&
+    resultPartCount === content?.length;
+  if (trustedHumanToolResult) {
+    calls.clear();
+    for (const [callId, entry] of candidateCalls) {
+      calls.set(callId, entry);
+    }
+  }
+  return {
+    completedToolCalls: isHuman && !trustedHumanToolResult
+      ? 0
+      : completedToolCalls,
+    trustedHumanToolResult,
+  };
+}
+
+function findTurnStarts(messages: BaseMessage[]): number[] {
+  const turnStarts: number[] = [];
+  const calls: ProviderToolCallIndex = new Map();
+  for (let i = 0; i < messages.length; i++) {
+    const message = messages[i] as BaseMessage;
+    const pairing = inspectMessagePairing(message, calls);
+    if (message.getType() !== 'human' || pairing.trustedHumanToolResult) {
+      continue;
+    }
+    turnStarts.push(i);
+    calls.clear();
+  }
+  return turnStarts;
+}
+
+function getCoverageSourceIds(message: BaseMessage): string[] {
+  const sourceIds = getProviderSourceMessageIds(message);
+  if (sourceIds.length > 0) {
+    return sourceIds;
+  }
+  const messageId = message.id?.trim();
+  return messageId != null && messageId !== '' ? [messageId] : [];
+}
+
+function findIntraTurnBoundary(
+  messages: BaseMessage[],
+  countMessageAt: (index: number) => number,
+  retainTokens: number,
+  earliestRetainedTurnEndIndex: number
+): number | undefined {
+  let remainingTokens = 0;
+  for (let i = 0; i < messages.length; i++) {
+    remainingTokens += countMessageAt(i);
+  }
+  if (remainingTokens <= retainTokens) {
+    return undefined;
+  }
+
+  const sourceIdsByIndex = new Array<string[]>(messages.length);
+  const lastIndexBySourceId = new Map<string, number>();
+  for (let i = 0; i < messages.length; i++) {
+    const sourceIds = getCoverageSourceIds(messages[i] as BaseMessage);
+    sourceIdsByIndex[i] = sourceIds;
+    for (const sourceId of sourceIds) {
+      lastIndexBySourceId.set(sourceId, i);
+    }
+  }
+
+  const pendingToolCalls: ProviderToolCallIndex = new Map();
+  const straddlingSourceIds = new Set<string>();
+  let completedToolCalls = 0;
+  let boundary: number | undefined;
+
+  const boundarySearchEnd = Math.min(
+    messages.length - 1,
+    earliestRetainedTurnEndIndex - 1
+  );
+  for (let i = 0; i <= boundarySearchEnd; i++) {
+    const message = messages[i] as BaseMessage;
+    remainingTokens -= countMessageAt(i);
+
+    const pairing = inspectMessagePairing(message, pendingToolCalls);
+    completedToolCalls += pairing.completedToolCalls;
+    if (message.getType() === 'human' && !pairing.trustedHumanToolResult) {
+      pendingToolCalls.clear();
+    }
+
+    for (const sourceId of sourceIdsByIndex[i] as string[]) {
+      if (lastIndexBySourceId.get(sourceId) === i) {
+        straddlingSourceIds.delete(sourceId);
+      } else {
+        straddlingSourceIds.add(sourceId);
+      }
+    }
+
+    if (remainingTokens < retainTokens) {
+      break;
+    }
+    if (
+      completedToolCalls > 0 &&
+      pendingToolCalls.size === 0 &&
+      straddlingSourceIds.size === 0 &&
+      (message.getType() !== 'human' || pairing.trustedHumanToolResult)
+    ) {
+      boundary = i + 1;
+    }
+  }
+
+  return boundary;
 }
 
 /**
  * Splits `messages` into a head (older, to summarize) and a tail (recent,
- * to preserve verbatim) at user-message boundaries.  The most recent
- * user-led turn is always included in the tail; additional older turns
- * are added subject to `turns` and `tokens` caps.
+ * to preserve verbatim), preferring user-message boundaries. The most recent
+ * user-led turn is normally included in the tail; additional older turns are
+ * added subject to `turns` and `tokens` caps.
  *
- * Cutting strictly at HumanMessage boundaries ensures that:
- * - tool_use ↔ tool_result pairs are never split (they always live within
- *   the same turn);
- * - the first user message is never replaced by a summary, addressing
- *   the "first turn destruction" failure mode where a single large
- *   user-pasted payload would otherwise be replaced by a generic summary.
+ * When that policy exposes no compactable head, `intraTurnTokens` may select
+ * a boundary after older closed tool-call/result units. This keeps runaway
+ * first-turn tool loops compactable without splitting parallel calls from
+ * their results. A user payload without a completed tool unit stays intact.
  *
  * When `messages` contains no HumanMessage (degenerate state — e.g. system
  * + assistant messages from a programmatic preamble), everything is
@@ -78,15 +446,11 @@ export function splitAtRecencyBoundary(
       tail: [],
       tailTurnCount: 0,
       tailStartIndex: messages.length,
+      usedIntraTurnFallback: false,
     };
   }
 
-  const turnStarts: number[] = [];
-  for (let i = 0; i < messages.length; i++) {
-    if (messages[i].getType() === 'human') {
-      turnStarts.push(i);
-    }
-  }
+  const turnStarts = findTurnStarts(messages);
 
   if (turnStarts.length === 0) {
     return {
@@ -94,6 +458,7 @@ export function splitAtRecencyBoundary(
       tail: [],
       tailTurnCount: 0,
       tailStartIndex: messages.length,
+      usedIntraTurnFallback: false,
     };
   }
 
@@ -105,6 +470,16 @@ export function splitAtRecencyBoundary(
   const tokenCounter = options.tokenCounter;
   const trackTokens =
     tokensCap != null && Number.isFinite(tokensCap) && tokenCounter != null;
+  const messageTokens: Array<number | undefined> = new Array(messages.length);
+  const countMessageAt = (index: number): number => {
+    const cached = messageTokens[index];
+    if (cached != null) {
+      return cached;
+    }
+    const count = tokenCounter?.(messages[index] as BaseMessage) ?? 0;
+    messageTokens[index] = count;
+    return count;
+  };
 
   /**
    * Token-counting strategy: each candidate turn `t` spans the half-open
@@ -122,7 +497,7 @@ export function splitAtRecencyBoundary(
   let tailTokens = 0;
   if (trackTokens) {
     for (let i = lastTurnStart; i < messages.length; i++) {
-      tailTokens += tokenCounter(messages[i] as BaseMessage);
+      tailTokens += countMessageAt(i);
     }
   }
 
@@ -136,7 +511,7 @@ export function splitAtRecencyBoundary(
     if (trackTokens) {
       let turnTokens = 0;
       for (let i = turnStart; i < turnEnd; i++) {
-        turnTokens += tokenCounter(messages[i] as BaseMessage);
+        turnTokens += countMessageAt(i);
       }
       if (tailTokens + turnTokens > (tokensCap as number)) {
         break;
@@ -148,10 +523,37 @@ export function splitAtRecencyBoundary(
     tailTurnCount += 1;
   }
 
+  if (tailStartIndex === turnStarts[0]) {
+    const intraTurnTokens = options.intraTurnTokens;
+    if (
+      intraTurnTokens != null &&
+      Number.isFinite(intraTurnTokens) &&
+      intraTurnTokens > 0 &&
+      tokenCounter != null
+    ) {
+      const intraTurnBoundary = findIntraTurnBoundary(
+        messages,
+        countMessageAt,
+        intraTurnTokens,
+        turnStarts[1] ?? messages.length
+      );
+      if (intraTurnBoundary != null) {
+        return {
+          head: messages.slice(0, intraTurnBoundary),
+          tail: messages.slice(intraTurnBoundary),
+          tailTurnCount,
+          tailStartIndex: intraTurnBoundary,
+          usedIntraTurnFallback: true,
+        };
+      }
+    }
+  }
+
   return {
     head: messages.slice(0, tailStartIndex),
     tail: messages.slice(tailStartIndex),
     tailTurnCount,
     tailStartIndex,
+    usedIntraTurnFallback: false,
   };
 }

package/src/session/AgentSession.ts

@@ -23,7 +23,7 @@ import type {
 } from './types';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
-import { deserializeMessage } from './messageSerialization';
+import { deriveMessages } from './deriveMessages';
 import { createSummarizeNode } from '@/summarization/node';
 import { resolveStreamLimits } from '@/llm/streamLimits';
 import { JsonlSessionStore } from './JsonlSessionStore';
@@ -493,32 +493,6 @@ function createCheckpointReference(params: {
   };
 }
 
-function createSessionRunState(entries: SessionEntry[]): {
-  messages: BaseMessage[];
-  initialSummary?: InitialSummary;
-} {
-  const messages: BaseMessage[] = [];
-  let initialSummary: InitialSummary | undefined;
-  for (const entry of entries) {
-    if (entry.type === 'summary') {
-      initialSummary = {
-        text: entry.data.text,
-        tokenCount:
-          typeof entry.data.tokenCount === 'number' &&
-          Number.isFinite(entry.data.tokenCount)
-            ? entry.data.tokenCount
-            : 0,
-      };
-      messages.length = 0;
-      continue;
-    }
-    if (entry.type === 'message') {
-      messages.push(deserializeMessage(entry.data.message));
-    }
-  }
-  return { messages, initialSummary };
-}
-
 function isMessageEntry(
   entry: SessionEntry
 ): entry is Extract<SessionEntry, { type: 'message' }> {
@@ -1103,7 +1077,7 @@ export class AgentSession {
       handlerResult.events.push(streamEvent);
       onEvent?.(streamEvent);
     };
-    const sessionState = createSessionRunState(
+    const sessionState = deriveMessages(
       isSessionThread ? (this.store?.getPath() ?? []) : []
     );
     let run: Run<t.IState> | undefined;
@@ -1349,7 +1323,7 @@ export class AgentSession {
       throw new Error('Cannot compact an ephemeral session');
     }
     const activePath = path ?? store.getPath();
-    const sessionState = createSessionRunState(activePath);
+    const sessionState = deriveMessages(activePath);
     const messageEntries = activePath.filter(isMessageEntry);
     if (sessionState.messages.length === 0) {
       return undefined;
@@ -1474,7 +1448,7 @@ export class AgentSession {
       threadId,
       userHandlers: this.runConfig.customHandlers,
     });
-    const sessionState = createSessionRunState(
+    const sessionState = deriveMessages(
       isSessionThread ? (this.store?.getPath() ?? []) : []
     );
     let run: Run<t.IState> | undefined;

package/src/session/deriveMessages.ts

@@ -0,0 +1,37 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { SessionEntry } from './types';
+import { deserializeMessage } from './messageSerialization';
+
+export interface DerivedSessionMessages {
+  initialSummary?: {
+    text: string;
+    tokenCount: number;
+  };
+  messages: BaseMessage[];
+}
+
+/** Derives the active model context from one append-only session-log path. */
+export function deriveMessages(
+  entries: readonly SessionEntry[]
+): DerivedSessionMessages {
+  const messages: BaseMessage[] = [];
+  let initialSummary: DerivedSessionMessages['initialSummary'];
+  for (const entry of entries) {
+    if (entry.type === 'summary') {
+      initialSummary = {
+        text: entry.data.text,
+        tokenCount:
+          typeof entry.data.tokenCount === 'number' &&
+          Number.isFinite(entry.data.tokenCount)
+            ? entry.data.tokenCount
+            : 0,
+      };
+      messages.length = 0;
+      continue;
+    }
+    if (entry.type === 'message') {
+      messages.push(deserializeMessage(entry.data.message));
+    }
+  }
+  return { messages, ...(initialSummary != null && { initialSummary }) };
+}

package/src/session/index.ts

@@ -1,4 +1,5 @@
 export { AgentSession, createAgentSession } from './AgentSession';
+export { deriveMessages } from './deriveMessages';
 export { JsonlSessionStore, SessionManager } from './JsonlSessionStore';
 export { createRunHandlers } from './handlers';
 export {
@@ -42,3 +43,4 @@ export type {
   SessionSummaryEntry,
   SessionTreeNode,
 } from './types';
+export type { DerivedSessionMessages } from './deriveMessages';