@librechat/agents 3.4.0 → 3.4.2

package/src/run.ts

@@ -4,21 +4,30 @@ 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 { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import type { StandardGraph } from '@/graphs/Graph';
 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,
@@ -55,12 +64,12 @@ import {
   createCompletionTitleRunnable,
   createTitleRunnable,
 } from '@/utils/title';
+import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
 import { initializeLangfuseTracing } from './instrumentation';
-import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
+import { createGraph } from '@/graphs/createGraph';
 import { resolveMaxSeals } from '@/llm/preempt';
-import { StandardGraph } from '@/graphs/Graph';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { isOpenAILike } from '@/utils/llm';
@@ -121,19 +130,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 +300,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;
       }
     }
@@ -277,30 +348,35 @@ export class Run<_T extends t.BaseGraphState> {
       signal = legacySignal;
     }
 
-    const standardGraph = new StandardGraph({
-      signal,
-      runId: this.id,
-      agents: [agentConfig],
-      langfuse: this.langfuse,
-      tokenCounter: this.tokenCounter,
-      indexTokenCountMap: this.indexTokenCountMap,
-      calibrationRatio: this.calibrationRatio,
-      subagentUsageSink: this.subagentUsageSink,
-      preemption: this.preemption,
-      streamLimits: this.streamLimits,
+    const standardGraph = createGraph({
+      kind: 'standard',
+      input: {
+        signal,
+        runId: this.id,
+        agents: [agentConfig],
+        langfuse: this.langfuse,
+        tokenCounter: this.tokenCounter,
+        indexTokenCountMap: this.indexTokenCountMap,
+        calibrationRatio: this.calibrationRatio,
+        subagentUsageSink: this.subagentUsageSink,
+        preemption: this.preemption,
+        streamLimits: this.streamLimits,
+      },
     });
     /** Propagate compile options from graph config */
     standardGraph.compileOptions = this.applyHITLCheckpointerFallback(
       config.compileOptions
     );
     this.hasCheckpointer = standardGraph.compileOptions?.checkpointer != null;
-    standardGraph.hookRegistry = this.hookRegistry;
-    standardGraph.humanInTheLoop = this.humanInTheLoop;
-    standardGraph.toolOutputReferences = this.toolOutputReferences;
-    standardGraph.eagerEventToolExecution = this.eagerEventToolExecution;
-    standardGraph.codeSessionToolNames = this.codeSessionToolNames;
-    standardGraph.interruptingToolNames = this.interruptingToolNames;
-    standardGraph.toolExecution = this.toolExecution;
+    applyGraphRuntimeConfig(standardGraph, {
+      hookRegistry: this.hookRegistry,
+      humanInTheLoop: this.humanInTheLoop,
+      toolOutputReferences: this.toolOutputReferences,
+      eagerEventToolExecution: this.eagerEventToolExecution,
+      codeSessionToolNames: this.codeSessionToolNames,
+      interruptingToolNames: this.interruptingToolNames,
+      toolExecution: this.toolExecution,
+    });
     this.Graph = standardGraph;
     return standardGraph.createWorkflow();
   }
@@ -310,30 +386,35 @@ export class Run<_T extends t.BaseGraphState> {
   ): t.CompiledStateWorkflow {
     const { agents, edges, compileOptions } = config;
 
-    const multiAgentGraph = new MultiAgentGraph({
-      runId: this.id,
-      agents,
-      edges,
-      langfuse: this.langfuse,
-      tokenCounter: this.tokenCounter,
-      indexTokenCountMap: this.indexTokenCountMap,
-      calibrationRatio: this.calibrationRatio,
-      subagentUsageSink: this.subagentUsageSink,
-      preemption: this.preemption,
-      streamLimits: this.streamLimits,
+    const multiAgentGraph = createGraph({
+      kind: 'multi-agent',
+      input: {
+        runId: this.id,
+        agents,
+        edges,
+        langfuse: this.langfuse,
+        tokenCounter: this.tokenCounter,
+        indexTokenCountMap: this.indexTokenCountMap,
+        calibrationRatio: this.calibrationRatio,
+        subagentUsageSink: this.subagentUsageSink,
+        preemption: this.preemption,
+        streamLimits: this.streamLimits,
+      },
     });
 
     multiAgentGraph.compileOptions =
       this.applyHITLCheckpointerFallback(compileOptions);
     this.hasCheckpointer = multiAgentGraph.compileOptions?.checkpointer != null;
 
-    multiAgentGraph.hookRegistry = this.hookRegistry;
-    multiAgentGraph.humanInTheLoop = this.humanInTheLoop;
-    multiAgentGraph.toolOutputReferences = this.toolOutputReferences;
-    multiAgentGraph.eagerEventToolExecution = this.eagerEventToolExecution;
-    multiAgentGraph.codeSessionToolNames = this.codeSessionToolNames;
-    multiAgentGraph.interruptingToolNames = this.interruptingToolNames;
-    multiAgentGraph.toolExecution = this.toolExecution;
+    applyGraphRuntimeConfig(multiAgentGraph, {
+      hookRegistry: this.hookRegistry,
+      humanInTheLoop: this.humanInTheLoop,
+      toolOutputReferences: this.toolOutputReferences,
+      eagerEventToolExecution: this.eagerEventToolExecution,
+      codeSessionToolNames: this.codeSessionToolNames,
+      interruptingToolNames: this.interruptingToolNames,
+      toolExecution: this.toolExecution,
+    });
     this.Graph = multiAgentGraph;
     return multiAgentGraph.createWorkflow();
   }
@@ -542,6 +623,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 +844,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 +1337,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 +1426,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 +1437,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 +1455,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 +1485,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 +1501,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 +1529,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 +1541,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({