@librechat/agents 3.3.13 → 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/specs/subagent.test.ts

@@ -21,6 +21,7 @@ import * as providers from '@/llm/providers';
 import { Run } from '@/run';
 
 const CHILD_RESPONSE = 'Research result: Paris is the capital of France.';
+const OVERRIDDEN_CHILD_RESPONSE = 'Deterministic child override result.';
 
 const callerConfig: Partial<RunnableConfig> & {
   version: 'v1' | 'v2';
@@ -226,6 +227,49 @@ describe('Subagent Integration', () => {
     expect(subagentTool).toBeDefined();
   });
 
+  it('only applies an explicitly configured subagent model override', async () => {
+    const invokeSubagent = async (
+      overrideSubagents: boolean
+    ): Promise<string> => {
+      const run = await Run.create<t.IState>({
+        runId: `subagent-model-override-${overrideSubagents}-${Date.now()}`,
+        graphConfig: {
+          type: 'standard',
+          agents: [createParentAgent()],
+        },
+        returnContent: true,
+        skipCleanup: true,
+      });
+      const graph = run.Graph as StandardGraph;
+      const model = new FakeListChatModel({
+        responses: [OVERRIDDEN_CHILD_RESPONSE],
+      });
+      graph.overrideModel = model;
+      if (overrideSubagents) {
+        graph.setSubagentModelOverride(model);
+      }
+
+      const context = graph.agentContexts.get('parent');
+      const subagentTool = (context?.graphTools as t.GenericTool[]).find(
+        (tool) => 'name' in tool && tool.name === Constants.SUBAGENT
+      );
+      expect(subagentTool).toBeDefined();
+
+      return String(
+        await subagentTool!.invoke(
+          {
+            description: 'What is the capital of France?',
+            subagent_type: 'researcher',
+          },
+          callerConfig
+        )
+      );
+    };
+
+    await expect(invokeSubagent(false)).resolves.toBe(CHILD_RESPONSE);
+    await expect(invokeSubagent(true)).resolves.toBe(OVERRIDDEN_CHILD_RESPONSE);
+  });
+
   it('inherits eager event-tool settings into self-spawn child graphs', async () => {
     const originalCreateWorkflow = StandardGraph.prototype.createWorkflow;
     const observedChildGraphs: Array<{