@librechat/agents 3.8.0 → 3.8.2

package/src/run.ts

@@ -22,7 +22,6 @@ import type {
 } from '@langchain/core/messages';
 import type { StringPromptValue } from '@langchain/core/prompt_values';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import { isFadingTier } from '@/messages/fading';
 import type { AggregatedHookResult, HookRegistry } from '@/hooks';
 import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -40,7 +39,6 @@ import {
 } from '@/common';
 import {
   requireValidSubagentResumeManifest,
-  stripSubagentResumeManifest,
   SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
   SUBAGENT_RESUME_MANIFEST_CONFIG_KEY,
 } from '@/tools/subagent/SubagentReplay';
@@ -70,6 +68,16 @@ import {
   resolveLangfuseConfig,
   resolveToolOutputTracingConfig,
 } from '@/langfuseConfig';
+import {
+  cloneToolApprovalInterruptPayload,
+  TOOL_APPROVAL_REVIEW_CONFIG_KEY,
+} from '@/hitl/approvalReview';
+import {
+  TOOL_BATCH_REPLAY_KEY,
+  restoreToolReplayConfig,
+  stripToolBatchReplayState,
+  getPublicToolInterruptPayload,
+} from '@/tools/toolBatchReplay';
 import {
   resolveLangfuseDestinationKey,
   resolveLangfuseTraceAnchorParent,
@@ -104,6 +112,7 @@ import { seedRunInitialSessions } from '@/utils/toolSessions';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
 import { resolveClientOptionsModel } from '@/llm/request';
 import { createGraph } from '@/graphs/createGraph';
+import { isFadingTier } from '@/messages/fading';
 import { resolveMaxSeals } from '@/llm/preempt';
 import { isBuiltRuntime } from '@/lazyRequire';
 import { initializeModel } from '@/llm/init';
@@ -169,9 +178,7 @@ function materializeStopContinuation(
   return messages;
 }
 
-function advanceCheckpointCursor(
-  config: t.RunStreamConfig
-): t.RunStreamConfig {
+function advanceCheckpointCursor(config: t.RunStreamConfig): t.RunStreamConfig {
   const configurable = { ...config.configurable };
   delete configurable.checkpoint_id;
   delete configurable.checkpoint_map;
@@ -186,9 +193,7 @@ function assertFinalAdmissionSucceeded(result: AggregatedHookResult): void {
     result.errors.length > 0
       ? result.errors.join('; ')
       : 'one or more internal finalizers failed';
-  throw new Error(
-    `StopFinalize terminal admission failed: ${detail}`
-  );
+  throw new Error(`StopFinalize terminal admission failed: ${detail}`);
 }
 
 const CUSTOM_GRAPH_EVENTS = new Set<string>([
@@ -268,9 +273,7 @@ function isLangGraphResumeMapForInterrupt(
 }
 
 function getInterruptHookSessionId(payload: unknown): string | undefined {
-  const publicPayload = stripSubagentResumeManifest(
-    stripRunStepResumeState(payload)
-  );
+  const publicPayload = getPublicToolInterruptPayload(payload);
   if (
     publicPayload == null ||
     typeof publicPayload !== 'object' ||
@@ -423,7 +426,7 @@ function overwriteResumeRunStepState(
   const update = Array.isArray(command.update)
     ? [
       ...command.update.filter(([key]) => key !== 'runStepState'),
-      ['runStepState', overwrite] as [string, unknown],
+        ['runStepState', overwrite] as [string, unknown],
     ]
     : { ...(command.update ?? {}), runStepState: overwrite };
   const resumed = new Command({
@@ -1266,6 +1269,8 @@ export class Run<_T extends t.BaseGraphState> {
       recursionLimit,
       configurable: { ...callerConfig.configurable },
     };
+    delete config.configurable?.[TOOL_APPROVAL_REVIEW_CONFIG_KEY];
+    delete config.configurable?.[TOOL_BATCH_REPLAY_KEY];
     if (!isResume) {
       delete config.configurable?.[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
       delete config.configurable?.[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY];
@@ -1276,6 +1281,10 @@ export class Run<_T extends t.BaseGraphState> {
         config,
         (inputs as Command).update
       );
+      const publicPayload = stripRunStepResumeState(this._interrupt?.payload);
+      if (config.configurable != null) {
+        restoreToolReplayConfig(config.configurable, this._interrupt?.interruptId, publicPayload);
+      }
       if (graph.getStopContinuationExecutionId() === '') {
         graph.startStopContinuationExecution(nanoid());
         overwriteLegacyResumeState = this.hasCheckpointer;
@@ -1514,7 +1523,7 @@ export class Run<_T extends t.BaseGraphState> {
               this._interrupt = {
                 interruptId: first.id ?? '',
                 threadId,
-                payload: first.value,
+                payload: cloneToolApprovalInterruptPayload(first.value),
               };
             }
           }
@@ -1558,7 +1567,8 @@ export class Run<_T extends t.BaseGraphState> {
           stopReason = OUTPUT_TRUNCATED_HALT_REASON;
         }
 
-        const stopMessages = graph.getRunMessages() ?? stateInputs?.messages ?? [];
+        const stopMessages =
+          graph.getRunMessages() ?? stateInputs?.messages ?? [];
         const stopContinuationCount = graph.getStopContinuationCount();
         const continuationBudgetRemaining = Math.max(
           0,
@@ -1584,11 +1594,17 @@ export class Run<_T extends t.BaseGraphState> {
           }).catch((): undefined => undefined);
         }
 
+        /** A summarize-only run is complete once its summary exists: there
+         *  is no assistant reply for a Stop hook to demand, and its one
+         *  summarization claim is spent, so it admits no continuation. */
+        const continuationAdmissible = graph.summarizeOnlyAgentId == null;
         if (this.hookRegistry?.hasHookFor('StopFinalize', this.id) === true) {
           const stopInjected =
             stopResult == null ? [] : materializeStopContinuation(stopResult);
           const continuationPrevented =
-            stopReason != null || stopResult?.preventContinuation === true;
+            !continuationAdmissible ||
+            stopReason != null ||
+            stopResult?.preventContinuation === true;
           const finalized = await executeHooks({
             registry: this.hookRegistry,
             input: {
@@ -1622,7 +1638,9 @@ export class Run<_T extends t.BaseGraphState> {
         }
 
         const requestsContinuation =
-          stopReason == null && stopResult?.stopDecision === 'block';
+          continuationAdmissible &&
+          stopReason == null &&
+          stopResult?.stopDecision === 'block';
         if (requestsContinuation && stopResult != null) {
           const injected = materializeStopContinuation(stopResult);
           if (injected.length > 0) {
@@ -1873,8 +1891,8 @@ export class Run<_T extends t.BaseGraphState> {
     }
     return {
       ...this._interrupt,
-      payload: stripSubagentResumeManifest(
-        stripRunStepResumeState(this._interrupt.payload)
+      payload: cloneToolApprovalInterruptPayload(
+        getPublicToolInterruptPayload(this._interrupt.payload)
       ),
     } as t.RunInterruptResult<TPayload>;
   }
@@ -1996,16 +2014,20 @@ export class Run<_T extends t.BaseGraphState> {
   ): Promise<t.RunStreamConfig> {
     await this.restoreInterruptFromCheckpoint(callerConfig, resumeUpdate);
     const interrupt = this._interrupt;
-    const resumeManifest = requireValidSubagentResumeManifest(
-      stripRunStepResumeState(interrupt?.payload)
-    );
+    const replayPayload = stripRunStepResumeState(interrupt?.payload);
+    const resumeManifest = requireValidSubagentResumeManifest(replayPayload) ??
+      requireValidSubagentResumeManifest(stripToolBatchReplayState(replayPayload));
     const resumeConfigurable = { ...callerConfig.configurable };
+    delete resumeConfigurable[TOOL_APPROVAL_REVIEW_CONFIG_KEY];
+    delete resumeConfigurable[TOOL_BATCH_REPLAY_KEY];
     delete resumeConfigurable[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
     delete resumeConfigurable[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY];
     resumeConfigurable[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY] = nanoid();
     if (resumeManifest != null) {
       resumeConfigurable[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY] = resumeManifest;
     }
+    const publicPayload = stripRunStepResumeState(interrupt?.payload);
+    restoreToolReplayConfig(resumeConfigurable, interrupt?.interruptId, publicPayload);
     const manifestConfig = {
       ...callerConfig,
       configurable: resumeConfigurable,
@@ -2122,7 +2144,7 @@ export class Run<_T extends t.BaseGraphState> {
     const threadId = callerConfig.configurable?.thread_id;
     this._interrupt = {
       interruptId: persistedInterrupt.id,
-      payload: persistedInterrupt.value,
+      payload: cloneToolApprovalInterruptPayload(persistedInterrupt.value),
       ...(typeof threadId === 'string' ? { threadId } : {}),
       ...(typeof checkpointId === 'string' ? { checkpointId } : {}),
       ...(typeof checkpointNs === 'string' ? { checkpointNs } : {}),

package/src/session/AgentSession.ts

@@ -21,9 +21,12 @@ import type {
   SessionEntry,
   SessionForkOptions,
 } from './types';
-import { isFadingTier } from '@/messages/fading';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
+import {
+  deriveSessionMessages,
+  releaseSessionProjection,
+} from './sessionProjection';
 import { createSummarizeNode } from '@/summarization/node';
 import { resolveStreamLimits } from '@/llm/streamLimits';
 import { JsonlSessionStore } from './JsonlSessionStore';
@@ -31,6 +34,7 @@ import { AgentContext } from '@/agents/AgentContext';
 import { ContentTypes, GraphEvents } from '@/common';
 import { createRunId, createSessionId } from './ids';
 import { deriveMessages } from './deriveMessages';
+import { isFadingTier } from '@/messages/fading';
 import { createRunHandlers } from './handlers';
 import { Run } from '@/run';
 
@@ -377,7 +381,9 @@ function fadingGenerationKey(scopeKey: string, agentKey: string): string {
 
 function fadingGenerationScope(generationKey: string): string {
   const parsed: unknown = JSON.parse(generationKey);
-  return Array.isArray(parsed) && typeof parsed[0] === 'string' ? parsed[0] : '';
+  return Array.isArray(parsed) && typeof parsed[0] === 'string'
+    ? parsed[0]
+    : '';
 }
 
 /** What a run saw when it started, so its capture can tell stale from current. */
@@ -404,10 +410,7 @@ function mergeFadingTier(
   if (incoming == null) {
     return { ...current };
   }
-  const budgetTokens = Math.min(
-    current.budgetTokens,
-    incoming.budgetTokens
-  );
+  const budgetTokens = Math.min(current.budgetTokens, incoming.budgetTokens);
   const masked = current.masked || incoming.masked;
   const latched =
     current.latched === true ||
@@ -1010,6 +1013,9 @@ export class AgentSession {
   }
 
   getSessionStore(): JsonlSessionStore | undefined {
+    if (this.store) {
+      releaseSessionProjection(this.store);
+    }
     return this.store;
   }
 
@@ -1017,7 +1023,10 @@ export class AgentSession {
     return this.checkpointing.checkpointer;
   }
 
-  private getFadingState(threadId: string, checkpointNs = ''): {
+  private getFadingState(
+    threadId: string,
+    checkpointNs = ''
+  ): {
     fadingTier?: t.FadingTier;
     fadingTiers?: t.FadingTiers;
   } {
@@ -1058,8 +1067,7 @@ export class AgentSession {
 
   private trimAlternateFadingStates(): void {
     while (
-      this.alternateThreadFadingState.size >
-      MAX_ALTERNATE_THREAD_FADING_STATES
+      this.alternateThreadFadingState.size > MAX_ALTERNATE_THREAD_FADING_STATES
     ) {
       const oldestThreadId = this.alternateThreadFadingState.keys().next();
       if (oldestThreadId.done === true) {
@@ -1172,7 +1180,10 @@ export class AgentSession {
     };
     const advanceGeneration = (agentKey: string): void => {
       const key = fadingGenerationKey(scopeKey, agentKey);
-      this.fadingGenerations.set(key, (this.fadingGenerations.get(key) ?? 0) + 1);
+      this.fadingGenerations.set(
+        key,
+        (this.fadingGenerations.get(key) ?? 0) + 1
+      );
     };
     const mergeCapturedTier = (
       existing: t.FadingTier | undefined,
@@ -1218,7 +1229,11 @@ export class AgentSession {
       if (didResetTier) {
         advanceGeneration('');
       }
-      nextTier = mergeCapturedTier(current.fadingTier, incomingTier, didResetTier);
+      nextTier = mergeCapturedTier(
+        current.fadingTier,
+        incomingTier,
+        didResetTier
+      );
     }
     if (threadId === this.threadId && checkpointNs === '') {
       this.fadingTier = nextTier;
@@ -1408,8 +1423,8 @@ export class AgentSession {
       handlerResult.events.push(streamEvent);
       onEvent?.(streamEvent);
     };
-    const sessionState = deriveMessages(
-      isSessionThread ? (this.store?.getPath() ?? []) : []
+    const sessionState = deriveSessionMessages(
+      isSessionThread ? this.store : undefined
     );
     const fadingState = this.getFadingState(threadId, checkpointNs);
     let run: Run<t.IState> | undefined;
@@ -1690,7 +1705,9 @@ export class AgentSession {
       throw new Error('Cannot compact an ephemeral session');
     }
     const activePath = path ?? store.getPath();
-    const sessionState = deriveMessages(activePath);
+    const sessionState = path
+      ? deriveMessages(path)
+      : deriveSessionMessages(store);
     const messageEntries = activePath.filter(isMessageEntry);
     if (sessionState.messages.length === 0) {
       return undefined;
@@ -1819,8 +1836,8 @@ export class AgentSession {
       threadId,
       userHandlers: this.runConfig.customHandlers,
     });
-    const sessionState = deriveMessages(
-      isSessionThread ? (this.store?.getPath() ?? []) : []
+    const sessionState = deriveSessionMessages(
+      isSessionThread ? this.store : undefined
     );
     const fadingState = this.getFadingState(threadId, checkpointNs);
     let run: Run<t.IState> | undefined;

package/src/session/JsonlSessionStore.ts

@@ -35,6 +35,10 @@ import {
   serializeMessage,
   toJsonValue,
 } from './messageSerialization';
+import {
+  initializeSessionProjection,
+  shareSessionProjectionOwnership,
+} from './sessionProjection';
 import { createEntryId, createSessionId, createTimestamp } from './ids';
 
 const SESSION_VERSION = 1;
@@ -126,6 +130,7 @@ export class JsonlSessionStore {
     this.path = params.path;
     this.header = params.header;
     this.entries = sortEntries(params.entries);
+    initializeSessionProjection(this, this.entries);
   }
 
   static getDefaultRoot(): string {
@@ -573,6 +578,7 @@ export class JsonlSessionStore {
       name: options.name ?? this.header.name,
       parentSession: this.path,
     });
+    shareSessionProjectionOwnership(this, newStore);
     const pathEntries = target ? this.getPath(target.id) : [];
     for (const entry of pathEntries) {
       await newStore.appendExistingEntry(entry);

package/src/session/sessionProjection.ts

@@ -0,0 +1,126 @@
+import type { DerivedSessionMessages } from './deriveMessages';
+import type { SessionEntry, SessionStateEntry } from './types';
+import type { JsonlSessionStore } from './JsonlSessionStore';
+import { deriveMessages } from './deriveMessages';
+
+interface SessionProjection {
+  entries: readonly SessionEntry[];
+  ownership: { exposed: boolean };
+  indexedCount: number;
+  byId: Map<string, SessionEntry>;
+  lastState?: SessionStateEntry;
+  lastMessage?: SessionEntry;
+  leaf?: SessionEntry;
+  projected: SessionEntry[];
+}
+
+const projections = new WeakMap<JsonlSessionStore, SessionProjection>();
+
+/** Internal: only AgentSession's unexposed stores may reuse log topology. */
+export function initializeSessionProjection(
+  store: JsonlSessionStore,
+  entries: readonly SessionEntry[]
+): void {
+  projections.set(store, {
+    entries,
+    ownership: { exposed: false },
+    indexedCount: 0,
+    byId: new Map(),
+    projected: [],
+  });
+}
+
+/** Forks share entry references, so exposing either disables the whole family. */
+export function shareSessionProjectionOwnership(
+  source: JsonlSessionStore,
+  target: JsonlSessionStore
+): void {
+  const sourceProjection = projections.get(source);
+  const targetProjection = projections.get(target);
+  if (sourceProjection && targetProjection) {
+    targetProjection.ownership = sourceProjection.ownership;
+  }
+}
+
+export function releaseSessionProjection(store: JsonlSessionStore): void {
+  const projection = projections.get(store);
+  if (projection) {
+    projection.ownership.exposed = true;
+    projection.byId.clear();
+    projection.projected = [];
+    projection.leaf = undefined;
+  }
+}
+
+function indexAppends(projection: SessionProjection): boolean {
+  for (
+    ;
+    projection.indexedCount < projection.entries.length;
+    projection.indexedCount++
+  ) {
+    const entry = projection.entries[projection.indexedCount];
+    if (projection.byId.has(entry.id)) {
+      return false;
+    }
+    projection.byId.set(entry.id, entry);
+    if (entry.type === 'session_state') {
+      projection.lastState = entry;
+    } else if (entry.type === 'message' || entry.type === 'summary') {
+      projection.lastMessage = entry;
+    }
+  }
+  return true;
+}
+
+function projectLeaf(projection: SessionProjection): void {
+  const leafId = projection.lastState
+    ? projection.lastState.data.leafId
+    : projection.lastMessage?.id;
+  const leaf =
+    leafId != null && leafId !== '' ? projection.byId.get(leafId) : undefined;
+  if (leaf === projection.leaf) {
+    return;
+  }
+  const delta: SessionEntry[] = [];
+  let current = leaf;
+  while (current && current !== projection.leaf) {
+    if (current.type === 'message' || current.type === 'summary') {
+      delta.push(current);
+    }
+    if (current.type === 'summary') {
+      current = undefined;
+      break;
+    }
+    current =
+      current.parentId == null
+        ? undefined
+        : projection.byId.get(current.parentId);
+  }
+  if (!current) {
+    projection.projected = [];
+  }
+  for (let i = delta.length - 1; i >= 0; i--) {
+    projection.projected.push(delta[i]);
+  }
+  projection.leaf = leaf;
+}
+
+/** Reuses log topology, but materializes fresh mutable messages for every run. */
+export function deriveSessionMessages(
+  store: JsonlSessionStore | undefined
+): DerivedSessionMessages {
+  if (!store) {
+    return { messages: [] };
+  }
+  const projection = projections.get(store);
+  if (!projection || projection.ownership.exposed) {
+    releaseSessionProjection(store);
+    return deriveMessages(store.getPath());
+  }
+  if (!indexAppends(projection)) {
+    releaseSessionProjection(store);
+    return deriveMessages(store.getPath());
+  }
+  projectLeaf(projection);
+  return deriveMessages(projection.projected);
+}

package/src/stream.ts

@@ -1014,18 +1014,6 @@ function pruneEagerToolCallChunkStates(args: {
   }
 }
 
-function isEagerToolChunkStateComplete(
-  state: t.EagerEventToolCallChunkState
-): boolean {
-  return (
-    state.id != null &&
-    state.id !== '' &&
-    state.name != null &&
-    state.name !== '' &&
-    coerceRecordArgs(state.argsText) != null
-  );
-}
-
 function mergeToolCallArgsText(existing: string, incoming: string): string {
   if (incoming === '') {
     return existing;
@@ -1180,6 +1168,7 @@ function getStreamedReadyToolCalls(args: {
     key: string;
     state: t.EagerEventToolCallChunkState;
     sealedByAdapter: boolean;
+    parsedArgs: ToolCall['args'];
   }> = [];
 
   for (const [key, state] of graph.eagerEventToolCallChunks) {
@@ -1190,7 +1179,12 @@ function getStreamedReadyToolCalls(args: {
       graph.eagerEventToolCallChunks.delete(key);
       continue;
     }
-    if (!isEagerToolChunkStateComplete(state)) {
+    if (
+      state.id == null ||
+      state.id === '' ||
+      state.name == null ||
+      state.name === ''
+    ) {
       continue;
     }
     const isSealedByLaterChunk =
@@ -1209,10 +1203,15 @@ function getStreamedReadyToolCalls(args: {
       isSealedByLaterChunk ||
       isSealedExplicitly
     ) {
+      const parsedArgs = coerceRecordArgs(state.argsText);
+      if (parsedArgs == null) {
+        continue;
+      }
       readyEntries.push({
         key,
         state,
         sealedByAdapter: isSealedExplicitly || seal?.kind === 'all',
+        parsedArgs,
       });
     }
   }
@@ -1232,11 +1231,7 @@ function getStreamedReadyToolCalls(args: {
 
   return readyEntries
     .sort((left, right) => (left.state.index ?? 0) - (right.state.index ?? 0))
-    .flatMap(({ state, sealedByAdapter }) => {
-      const args = coerceRecordArgs(state.argsText);
-      if (args == null) {
-        return [];
-      }
+    .flatMap(({ state, sealedByAdapter, parsedArgs }) => {
       // The final request's args come from LangChain's canonical verbatim
       // concatenation of fragments, while `argsText` reconciles provider
       // quirks with lossy heuristics that can also swallow legitimately
@@ -1267,7 +1262,7 @@ function getStreamedReadyToolCalls(args: {
         {
           id: state.id,
           name: state.name ?? '',
-          args,
+          args: parsedArgs,
         },
       ];
     });

package/src/summarization/index.ts

@@ -9,7 +9,9 @@ export {
   buildSummarizationInstruction,
   buildSummaryCarrierText,
   separateSummarizationParameters,
+  ManualSummarizationSkippedError,
 } from './shared';
+export type { ManualSummarizationSkipReason } from './shared';
 
 const VALID_TRIGGER_TYPES = [
   'token_ratio',