@librechat/agents 3.4.0 → 3.4.1

package/src/run.ts

@@ -4,21 +4,28 @@ import { PromptTemplate } from '@langchain/core/prompts';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
-import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import {
+  BaseMessage,
+  HumanMessage,
+  SystemMessage,
+} from '@langchain/core/messages';
 import {
   Command,
   INTERRUPT,
   MemorySaver,
   isInterrupted,
 } from '@langchain/langgraph';
-import type {
-  MessageContentComplex,
-  BaseMessage,
-} from '@langchain/core/messages';
 import type { StringPromptValue } from '@langchain/core/prompt_values';
+import type { MessageContentComplex } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
+import {
+  requireValidSubagentResumeManifest,
+  stripSubagentResumeManifest,
+  SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
+  SUBAGENT_RESUME_MANIFEST_CONFIG_KEY,
+} from '@/tools/subagent/SubagentReplay';
 import {
   createLangfuseTraceMetadata,
   createLangfuseHandler,
@@ -121,19 +128,83 @@ function isLangGraphResumeMapForInterrupt(
   return Object.prototype.hasOwnProperty.call(value, interruptId);
 }
 
+function getInterruptHookSessionId(payload: unknown): string | undefined {
+  const publicPayload = stripSubagentResumeManifest(payload);
+  if (
+    publicPayload == null ||
+    typeof publicPayload !== 'object' ||
+    (publicPayload as { type?: unknown }).type !== 'tool_approval'
+  ) {
+    return undefined;
+  }
+  const sessionId = (publicPayload as { hook_session_id?: unknown })
+    .hook_session_id;
+  return typeof sessionId === 'string' && sessionId.length > 0
+    ? sessionId
+    : undefined;
+}
+
 type InterruptStateSnapshot = {
   config?: RunnableConfig;
+  values?: { messages?: BaseMessage[] };
   tasks?: Array<{
-    interrupts?: Array<{ id?: string }>;
+    interrupts?: Array<{ id?: string; value?: unknown }>;
   }>;
 };
 
 type WorkflowWithStateHistory = {
+  getState?(config: RunnableConfig): Promise<InterruptStateSnapshot>;
   getStateHistory?(
     config: RunnableConfig
   ): AsyncIterableIterator<InterruptStateSnapshot>;
 };
 
+function getFirstPersistedInterrupt(
+  snapshot: InterruptStateSnapshot
+): { id: string; value: unknown } | undefined {
+  for (const task of snapshot.tasks ?? []) {
+    for (const pendingInterrupt of task.interrupts ?? []) {
+      if (
+        typeof pendingInterrupt.id === 'string' &&
+        pendingInterrupt.id.length > 0
+      ) {
+        return { id: pendingInterrupt.id, value: pendingInterrupt.value };
+      }
+    }
+  }
+  return undefined;
+}
+
+function getPersistedMessages(
+  snapshot: InterruptStateSnapshot
+): BaseMessage[] | undefined {
+  const messages = snapshot.values?.messages;
+  if (!Array.isArray(messages) || !messages.every(BaseMessage.isInstance)) {
+    return undefined;
+  }
+  return messages;
+}
+
+type ResumeCommandUpdate = ConstructorParameters<typeof Command>[0]['update'];
+
+function getResumeUpdateMessages(
+  update: ResumeCommandUpdate
+): BaseMessage[] | undefined {
+  if (update == null) {
+    return undefined;
+  }
+  const messages = Array.isArray(update)
+    ? update.find(([key]) => key === 'messages')?.[1]
+    : update.messages;
+  if (BaseMessage.isInstance(messages)) {
+    return [messages];
+  }
+  if (!Array.isArray(messages) || !messages.every(BaseMessage.isInstance)) {
+    return undefined;
+  }
+  return messages;
+}
+
 export class Run<_T extends t.BaseGraphState> {
   id: string;
   private tokenCounter?: t.TokenCounter;
@@ -227,8 +298,6 @@ export class Run<_T extends t.BaseGraphState> {
       /** Default to legacy graph for 'standard' or undefined type */
       this.graphRunnable = this.createLegacyGraph(config.graphConfig);
       if (this.Graph) {
-        this.Graph.compileOptions =
-          config.graphConfig.compileOptions ?? this.Graph.compileOptions;
         this.Graph.handlerRegistry = handlerRegistry;
       }
     }
@@ -542,6 +611,10 @@ export class Run<_T extends t.BaseGraphState> {
     return this.Graph.getRunMessages();
   }
 
+  getChildCheckpointThreadIds(): string[] {
+    return this.Graph?.getChildCheckpointThreadIds() ?? [];
+  }
+
   /**
    * Returns a defensive snapshot of tools discovered by the current run.
    * Pass an agent id for that context, or omit it for the ordered union across
@@ -759,6 +832,10 @@ export class Run<_T extends t.BaseGraphState> {
       recursionLimit,
       configurable: { ...callerConfig.configurable },
     };
+    if (!isResume) {
+      delete config.configurable?.[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
+      delete config.configurable?.[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY];
+    }
 
     /**
      * Cancellation can arrive either at graph construction or per-call through
@@ -1248,7 +1325,13 @@ export class Run<_T extends t.BaseGraphState> {
   getInterrupt<TPayload = t.HumanInterruptPayload>():
     | t.RunInterruptResult<TPayload>
     | undefined {
-    return this._interrupt as t.RunInterruptResult<TPayload> | undefined;
+    if (this._interrupt == null) {
+      return undefined;
+    }
+    return {
+      ...this._interrupt,
+      payload: stripSubagentResumeManifest(this._interrupt.payload),
+    } as t.RunInterruptResult<TPayload>;
   }
 
   /**
@@ -1331,6 +1414,10 @@ export class Run<_T extends t.BaseGraphState> {
       'update' | 'goto'
     >
   ): Promise<MessageContentComplex[] | undefined> {
+    const resumeConfig = await this.resolveInterruptResumeConfig(
+      callerConfig,
+      commandOptions?.update
+    );
     const interruptId = this._interrupt?.interruptId;
     const scopedResume =
       typeof interruptId === 'string' &&
@@ -1338,7 +1425,6 @@ export class Run<_T extends t.BaseGraphState> {
       !isLangGraphResumeMapForInterrupt(resumeValue, interruptId)
         ? { [interruptId]: resumeValue }
         : resumeValue;
-    const resumeConfig = await this.resolveInterruptResumeConfig(callerConfig);
     // langgraph 1.4.5 applies resume + state update + reroute in one superstep
     // (single checkpoint). `update`/`goto` are omitted unless the caller sets them.
     return this.processStream(
@@ -1357,9 +1443,29 @@ export class Run<_T extends t.BaseGraphState> {
   }
 
   private async resolveInterruptResumeConfig(
-    callerConfig: t.RunStreamConfig
+    callerConfig: t.RunStreamConfig,
+    resumeUpdate?: ResumeCommandUpdate
   ): Promise<t.RunStreamConfig> {
+    await this.restoreInterruptFromCheckpoint(callerConfig, resumeUpdate);
     const interrupt = this._interrupt;
+    const resumeManifest = requireValidSubagentResumeManifest(
+      interrupt?.payload
+    );
+    const resumeConfigurable = { ...callerConfig.configurable };
+    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 manifestConfig = {
+      ...callerConfig,
+      configurable: resumeConfigurable,
+    };
+    const hookSessionId = getInterruptHookSessionId(interrupt?.payload);
+    if (hookSessionId != null) {
+      this.hookRegistry?.copySession(hookSessionId, this.id);
+    }
     const interruptId = interrupt?.interruptId;
     const workflow = this.graphRunnable as
       | (t.CompiledStateWorkflow & WorkflowWithStateHistory)
@@ -1367,9 +1473,9 @@ export class Run<_T extends t.BaseGraphState> {
     const stateHistory = workflow?.getStateHistory;
     if (interrupt?.checkpointId != null && interrupt.checkpointId.length > 0) {
       return {
-        ...callerConfig,
+        ...manifestConfig,
         configurable: {
-          ...callerConfig.configurable,
+          ...manifestConfig.configurable,
           checkpoint_id: interrupt.checkpointId,
           ...(typeof interrupt.checkpointNs === 'string'
             ? { checkpoint_ns: interrupt.checkpointNs }
@@ -1383,12 +1489,12 @@ export class Run<_T extends t.BaseGraphState> {
       interruptId.length === 0 ||
       typeof stateHistory !== 'function'
     ) {
-      return callerConfig;
+      return manifestConfig;
     }
 
     for await (const snapshot of stateHistory.call(
       this.graphRunnable,
-      callerConfig as RunnableConfig
+      manifestConfig as RunnableConfig
     )) {
       const hasMatchingInterrupt =
         snapshot.tasks?.some(
@@ -1411,9 +1517,9 @@ export class Run<_T extends t.BaseGraphState> {
           ...(typeof checkpointNs === 'string' ? { checkpointNs } : {}),
         };
         return {
-          ...callerConfig,
+          ...manifestConfig,
           configurable: {
-            ...callerConfig.configurable,
+            ...manifestConfig.configurable,
             checkpoint_id: checkpointId,
             ...(typeof checkpointNs === 'string'
               ? { checkpoint_ns: checkpointNs }
@@ -1423,7 +1529,47 @@ export class Run<_T extends t.BaseGraphState> {
       }
     }
 
-    return callerConfig;
+    return manifestConfig;
+  }
+
+  private async restoreInterruptFromCheckpoint(
+    callerConfig: t.RunStreamConfig,
+    resumeUpdate?: ResumeCommandUpdate
+  ): Promise<void> {
+    if (this._interrupt != null || this.humanInTheLoop?.enabled !== true) {
+      return;
+    }
+    const workflow = this.graphRunnable as
+      | (t.CompiledStateWorkflow & WorkflowWithStateHistory)
+      | undefined;
+    if (typeof workflow?.getState !== 'function') {
+      return;
+    }
+
+    const snapshot = await workflow.getState(callerConfig as RunnableConfig);
+    const persistedInterrupt = getFirstPersistedInterrupt(snapshot);
+    if (persistedInterrupt == null) {
+      return;
+    }
+    const persistedMessages = getPersistedMessages(snapshot);
+    if (persistedMessages != null) {
+      this.Graph?.restoreCheckpointMessages(
+        persistedMessages,
+        getResumeUpdateMessages(resumeUpdate)
+      );
+    }
+
+    const checkpointConfigurable = snapshot.config?.configurable;
+    const checkpointId = checkpointConfigurable?.checkpoint_id;
+    const checkpointNs = checkpointConfigurable?.checkpoint_ns;
+    const threadId = callerConfig.configurable?.thread_id;
+    this._interrupt = {
+      interruptId: persistedInterrupt.id,
+      payload: persistedInterrupt.value,
+      ...(typeof threadId === 'string' ? { threadId } : {}),
+      ...(typeof checkpointId === 'string' ? { checkpointId } : {}),
+      ...(typeof checkpointNs === 'string' ? { checkpointNs } : {}),
+    };
   }
 
   private createSystemCallback<K extends keyof t.ClientCallbacks>(

package/src/session/AgentSession.ts

@@ -934,6 +934,30 @@ export class AgentSession {
     });
   }
 
+  private async recordChildCheckpointThreads(params: {
+    source: 'run' | 'resume';
+    runId: string;
+    run: Run<t.IState>;
+  }): Promise<void> {
+    if (!this.checkpointing.enabled || this.store == null) {
+      return;
+    }
+    const recordedThreadIds = new Set(
+      this.store.getCheckpoints().map((checkpoint) => checkpoint.data.threadId)
+    );
+    for (const threadId of params.run.getChildCheckpointThreadIds()) {
+      if (recordedThreadIds.has(threadId)) {
+        continue;
+      }
+      recordedThreadIds.add(threadId);
+      await this.store.appendCheckpoint({
+        source: params.source,
+        runId: params.runId,
+        threadId,
+      });
+    }
+  }
+
   private getCheckpointThreadIds(): string[] {
     const threadIds = new Set<string>([this.threadId]);
     for (const checkpoint of this.store?.getCheckpoints() ?? []) {
@@ -1006,6 +1030,7 @@ export class AgentSession {
     const sessionState = createSessionRunState(
       isSessionThread ? (this.store?.getPath() ?? []) : []
     );
+    let run: Run<t.IState> | undefined;
     try {
       const runConfig: t.RunConfig = {
         ...this.runConfig,
@@ -1024,7 +1049,7 @@ export class AgentSession {
           ...handlerResult.handlers,
         },
       };
-      const run = await Run.create<t.IState>(runConfig);
+      run = await Run.create<t.IState>(runConfig);
       let messages = inputMessages;
       if (!useCheckpointState && sessionState.messages.length > 0) {
         messages = sessionState.messages;
@@ -1070,6 +1095,11 @@ export class AgentSession {
         checkpointId: interrupt?.checkpointId,
         checkpointNs: interrupt?.checkpointNs,
       });
+      await this.recordChildCheckpointThreads({
+        source: 'run',
+        runId,
+        run,
+      });
       const contentParts = (content ?? handlerResult.contentParts).filter(
         (part): part is t.MessageContentComplex => part != null
       );
@@ -1099,6 +1129,13 @@ export class AgentSession {
         threadId,
         config: callerConfig,
       });
+      if (run != null) {
+        await this.recordChildCheckpointThreads({
+          source: 'run',
+          runId,
+          run,
+        });
+      }
       throw error;
     }
   }
@@ -1348,8 +1385,9 @@ export class AgentSession {
     const sessionState = createSessionRunState(
       isSessionThread ? (this.store?.getPath() ?? []) : []
     );
+    let run: Run<t.IState> | undefined;
     try {
-      const run = await Run.create<t.IState>({
+      run = await Run.create<t.IState>({
         ...this.runConfig,
         runId,
         graphConfig: applyCheckpointingToGraphConfig(
@@ -1400,6 +1438,11 @@ export class AgentSession {
         checkpointId: interrupt?.checkpointId,
         checkpointNs: interrupt?.checkpointNs,
       });
+      await this.recordChildCheckpointThreads({
+        source: 'resume',
+        runId,
+        run,
+      });
       const contentParts = (content ?? handlerResult.contentParts).filter(
         (part): part is t.MessageContentComplex => part != null
       );
@@ -1425,6 +1468,13 @@ export class AgentSession {
         threadId,
         config: callerConfig,
       });
+      if (run != null) {
+        await this.recordChildCheckpointThreads({
+          source: 'resume',
+          runId,
+          run,
+        });
+      }
       throw error;
     }
   }

package/src/session/__tests__/JsonlSessionStore.test.ts

@@ -25,6 +25,9 @@ type MockRun = {
   >;
   getInterrupt: jest.MockedFunction<Run<t.IState>['getInterrupt']>;
   getHaltReason: jest.MockedFunction<Run<t.IState>['getHaltReason']>;
+  getChildCheckpointThreadIds: jest.MockedFunction<
+    Run<t.IState>['getChildCheckpointThreadIds']
+  >;
 };
 
 function createMockRun(outputText = 'ok'): MockRun {
@@ -45,6 +48,7 @@ function createMockRun(outputText = 'ok'): MockRun {
     getCalibrationRatio: jest.fn(() => 1),
     getInterrupt: jest.fn(() => undefined),
     getHaltReason: jest.fn(() => undefined),
+    getChildCheckpointThreadIds: jest.fn(() => []),
   };
 }
 
@@ -1119,6 +1123,55 @@ describe('JsonlSessionStore', () => {
     });
   });
 
+  it('records and resets child checkpoint threads owned by a run', async () => {
+    const checkpointer = new MemorySaver();
+    const childThreadId = 'subagent:owned-child';
+    const mockRun = createMockRun('child result');
+    mockRun.getChildCheckpointThreadIds.mockReturnValue([childThreadId]);
+    mockRunCreate(mockRun);
+    const session = await createAgentSession({
+      cwd: dir,
+      runId: 'template-run',
+      checkpointing: { checkpointer },
+      graphConfig: {
+        type: 'standard',
+        llmConfig: {
+          provider: 'openAI' as never,
+          model: 'test-model',
+        },
+        instructions: 'test',
+      },
+    });
+    await putCheckpoint({
+      checkpointer,
+      threadId: childThreadId,
+      id: 'checkpoint_child',
+    });
+
+    await session.run('fresh turn', { runId: 'run_with_child' });
+
+    expect(
+      session.getSessionStore()?.getCheckpoints(childThreadId).at(-1)?.data
+    ).toMatchObject({
+      source: 'run',
+      runId: 'run_with_child',
+      threadId: childThreadId,
+    });
+    const firstMessage = session
+      .getSessionStore()
+      ?.getPath()
+      .find((entry) => entry.type === 'message');
+    await session.branch(firstMessage?.id ?? '', { position: 'at' });
+
+    const tuple = await checkpointer.getTuple({
+      configurable: { thread_id: childThreadId },
+    });
+    expect(tuple).toBeUndefined();
+    expect(
+      session.getSessionStore()?.getCheckpoints(childThreadId).at(-1)?.data
+    ).toMatchObject({ source: 'reset', reason: 'branch' });
+  });
+
   it('keeps checkpoint state when branching to the active JSONL leaf', async () => {
     const checkpointer = new MemorySaver();
     const session = await createAgentSession({

package/src/summarization/__tests__/node.test.ts

@@ -1059,6 +1059,24 @@ describe('recency window — first-turn protection', () => {
       expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm2' });
     });
 
+    it('anchors a derived retained message on its persisted source id', async () => {
+      const summaryBlock = await runCompaction([
+        new HumanMessage({ content: 'turn 1 query', id: 'm1' }),
+        new AIMessage({ content: 'pre-steer reply', id: 'm2' }),
+        new HumanMessage({
+          content: 'steer',
+          id: 'reducer-uuid',
+          additional_kwargs: {
+            role: 'user',
+            source: 'steer',
+            sourceMessageId: 'm2',
+          },
+        }),
+      ]);
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm2' });
+    });
+
     /** `formatAgentMessages` reconstructs skill bodies inside its payload loop
      *  and keeps processing payload entries after, so this unstamped entry — a
      *  reducer UUID by the time compaction sees it — precedes stamped messages.
@@ -1770,13 +1788,13 @@ describe('summarize node breaker capture', () => {
     const entryBreaker = new AbortController();
     /** The trip lands while ON_SUMMARIZE_START is awaited — after the
      * entry check already passed. */
-    jest.spyOn(eventUtils, 'safeDispatchCustomEvent').mockImplementation((async (
-      ...args: unknown[]
-    ) => {
-      if (args[0] === GraphEvents.ON_SUMMARIZE_START) {
-        entryBreaker.abort(trip);
-      }
-    }) as never);
+    jest
+      .spyOn(eventUtils, 'safeDispatchCustomEvent')
+      .mockImplementation((async (...args: unknown[]) => {
+        if (args[0] === GraphEvents.ON_SUMMARIZE_START) {
+          entryBreaker.abort(trip);
+        }
+      }) as never);
     const modelClassSpy = jest
       .spyOn(providers, 'getChatModelClass')
       .mockReturnValue(
@@ -1915,13 +1933,13 @@ describe('summarize node breaker capture', () => {
     const entryBreaker = new AbortController();
     const lateBreaker = new AbortController();
     let started = false;
-    jest.spyOn(eventUtils, 'safeDispatchCustomEvent').mockImplementation((async (
-      ...args: unknown[]
-    ) => {
-      if (args[0] === GraphEvents.ON_SUMMARIZE_START) {
-        started = true;
-      }
-    }) as never);
+    jest
+      .spyOn(eventUtils, 'safeDispatchCustomEvent')
+      .mockImplementation((async (...args: unknown[]) => {
+        if (args[0] === GraphEvents.ON_SUMMARIZE_START) {
+          started = true;
+        }
+      }) as never);
 
     const capturedSignals: Array<AbortSignal | undefined> = [];
     jest.spyOn(providers, 'getChatModelClass').mockReturnValue(

package/src/summarization/node.ts

@@ -17,6 +17,11 @@ import {
   isComputerCallOutputMessage,
   serializeToolContentBounded,
 } from '@/utils/toolContent';
+import {
+  enforceStreamLimitsForWireChunk,
+  StreamLimitExceededError,
+  STREAM_LIMIT_EPOCH_KEY,
+} from '@/llm/streamLimits';
 import {
   addTailCacheControl,
   resolvePromptCacheTtl,
@@ -34,11 +39,6 @@ import {
   Providers,
 } from '@/common';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
-import {
-  enforceStreamLimitsForWireChunk,
-  StreamLimitExceededError,
-  STREAM_LIMIT_EPOCH_KEY,
-} from '@/llm/streamLimits';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { calculateMaxToolResultChars } from '@/utils/truncation';
 import { createRemoveAllMessage } from '@/messages/reducer';
@@ -418,8 +418,9 @@ function computeSummaryTokenCount(
  * in `ToolNode` and `StandardGraph`, handoff cues, reconstructed skill bodies.
  *
  * `steer` is exempt from the `source` check because a replayed steer *is*
- * stamped from its payload entry; rejecting every marked `source` once dropped
- * exactly those retained steers. Injected steers are still caught, by `injected`.
+ * correlated with its payload entry; rejecting every marked `source` once
+ * dropped exactly those retained steers. Injected steers are still caught, by
+ * `injected`.
  *
  * Known limitation: a payload entry that omits `messageId` is never stamped, so
  * the reducer's UUID is recorded and cannot resolve on the next run. There is no
@@ -443,7 +444,10 @@ function resolveSummaryCoverage(
     if (isSyntheticContext(message)) {
       continue;
     }
-    const id = message.id?.trim();
+    const sourceMessageId = message.additional_kwargs.sourceMessageId;
+    const sourceId =
+      typeof sourceMessageId === 'string' ? sourceMessageId.trim() : '';
+    const id = sourceId !== '' ? sourceId : message.id?.trim();
     if (id != null && id !== '') {
       return { retainedFromMessageId: id };
     }
@@ -1244,9 +1248,9 @@ export function createSummarizeNode({
             ? { [Constants.INVOKED_MODEL]: clientConfig.modelName }
             : {}),
           /** Entry-captured breaker epoch: the wire consumer epoch-gates
-           * old-run summary chunks exactly like model-attempt chunks —
-           * without the stamp, a straggling summary from a failed run
-           * reads as current and could abort the next run's controller. */
+             * old-run summary chunks exactly like model-attempt chunks —
+             * without the stamp, a straggling summary from a failed run
+             * reads as current and could abort the next run's controller. */
           ...(entryBreakerEpoch != null
             ? { [STREAM_LIMIT_EPOCH_KEY]: entryBreakerEpoch }
             : {}),