@librechat/agents 3.2.52 → 3.2.54

package/src/run.ts

@@ -135,6 +135,13 @@ export class Run<_T extends t.BaseGraphState> {
   Graph: StandardGraph | MultiAgentGraph | undefined;
   returnContent: boolean = false;
   private skipCleanup: boolean = false;
+  /**
+   * Whether the compiled graph was built with a checkpointer (host-supplied
+   * or the HITL `MemorySaver` fallback). Captured at graph creation because
+   * the constructor can later overwrite `Graph.compileOptions` with the raw
+   * caller options, dropping the fallback checkpointer from that metadata.
+   */
+  private hasCheckpointer: boolean = false;
   private _streamResult: t.MessageContentComplex[] | undefined;
   /**
    * Captured interrupt payload typed as `unknown` because the SDK
@@ -256,6 +263,7 @@ export class Run<_T extends t.BaseGraphState> {
     standardGraph.compileOptions = this.applyHITLCheckpointerFallback(
       config.compileOptions
     );
+    this.hasCheckpointer = standardGraph.compileOptions?.checkpointer != null;
     standardGraph.hookRegistry = this.hookRegistry;
     standardGraph.humanInTheLoop = this.humanInTheLoop;
     standardGraph.toolOutputReferences = this.toolOutputReferences;
@@ -283,6 +291,7 @@ export class Run<_T extends t.BaseGraphState> {
 
     multiAgentGraph.compileOptions =
       this.applyHITLCheckpointerFallback(compileOptions);
+    this.hasCheckpointer = multiAgentGraph.compileOptions?.checkpointer != null;
 
     multiAgentGraph.hookRegistry = this.hookRegistry;
     multiAgentGraph.humanInTheLoop = this.humanInTheLoop;
@@ -647,10 +656,7 @@ export class Run<_T extends t.BaseGraphState> {
 
   async processStream(
     inputs: t.IState | Command,
-    callerConfig: Partial<RunnableConfig> & {
-      version: 'v1' | 'v2';
-      run_id?: string;
-    },
+    callerConfig: t.RunStreamConfig,
     streamOptions?: t.EventStreamOptions
   ): Promise<MessageContentComplex[] | undefined> {
     if (this.graphRunnable == null) {
@@ -676,10 +682,7 @@ export class Run<_T extends t.BaseGraphState> {
     const isResume = inputs instanceof Command;
     const stateInputs = isResume ? undefined : (inputs as t.IState);
 
-    const config: Partial<RunnableConfig> & {
-      version: 'v1' | 'v2';
-      run_id?: string;
-    } = {
+    const config: t.RunStreamConfig = {
       recursionLimit: 50,
       ...callerConfig,
       configurable: { ...callerConfig.configurable },
@@ -763,6 +766,16 @@ export class Run<_T extends t.BaseGraphState> {
       run_id: this.id,
     });
 
+    /**
+     * Default `durability: 'exit'` whenever a checkpointer is active so
+     * runs skip per-superstep checkpoint writes and persist only at the
+     * exit/interrupt boundary (all HITL/resume needs). An explicit caller
+     * value wins; no checkpointer leaves it unset (langgraph default).
+     */
+    if (config.durability == null && this.hasCheckpointer) {
+      config.durability = 'exit';
+    }
+
     const threadId = config.configurable.thread_id as string | undefined;
 
     if (this.hookRegistry != null && stateInputs != null) {
@@ -1155,10 +1168,7 @@ export class Run<_T extends t.BaseGraphState> {
    */
   async resume<TResume = t.ToolApprovalDecision[] | t.ToolApprovalDecisionMap>(
     resumeValue: TResume,
-    callerConfig: Partial<RunnableConfig> & {
-      version: 'v1' | 'v2';
-      run_id?: string;
-    },
+    callerConfig: t.RunStreamConfig,
     streamOptions?: t.EventStreamOptions,
     commandOptions?: Pick<
       ConstructorParameters<typeof Command>[0],
@@ -1191,16 +1201,8 @@ export class Run<_T extends t.BaseGraphState> {
   }
 
   private async resolveInterruptResumeConfig(
-    callerConfig: Partial<RunnableConfig> & {
-      version: 'v1' | 'v2';
-      run_id?: string;
-    }
-  ): Promise<
-    Partial<RunnableConfig> & {
-      version: 'v1' | 'v2';
-      run_id?: string;
-    }
-  > {
+    callerConfig: t.RunStreamConfig
+  ): Promise<t.RunStreamConfig> {
     const interrupt = this._interrupt;
     const interruptId = interrupt?.interruptId;
     const workflow = this.graphRunnable as

package/src/session/types.ts

@@ -209,7 +209,10 @@ export type AgentSessionInput = string | BaseMessage | BaseMessage[] | t.IState;
 export interface AgentSessionRunOptions {
   runId?: string;
   threadId?: string;
-  config?: Partial<RunnableConfig> & { version?: 'v1' | 'v2' };
+  config?: Partial<RunnableConfig> & {
+    version?: 'v1' | 'v2';
+    durability?: t.Durability;
+  };
   streamOptions?: t.EventStreamOptions;
 }
 

package/src/specs/durability-checkpoint.integration.test.ts

@@ -0,0 +1,243 @@
+import { MongoClient } from 'mongodb';
+import { HumanMessage } from '@langchain/core/messages';
+import { MongoMemoryServer } from 'mongodb-memory-server-core';
+import { MongoDBSaver } from '@langchain/langgraph-checkpoint-mongodb';
+import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
+import {
+  END,
+  START,
+  Command,
+  Annotation,
+  StateGraph,
+  interrupt,
+} from '@langchain/langgraph';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * End-to-end proof against a real Mongo store that the durability default is
+ * the storage optimization it claims to be, not just a config flag. A real
+ * `Run` with a fake streaming model (no provider API hit) writes through the
+ * official MongoDBSaver, and a langgraph interrupt graph exercises the HITL
+ * pause/resume boundary. `exit` persists only at the exit/interrupt boundary
+ * with no per-superstep writes; `async` checkpoints every superstep.
+ */
+describe('durability default — real Mongo checkpointer', () => {
+  let mongod: MongoMemoryServer;
+  let client: MongoClient;
+
+  beforeAll(async () => {
+    // First CI run downloads a mongod binary — allow time beyond the 60s default.
+    mongod = await MongoMemoryServer.create();
+    client = new MongoClient(mongod.getUri());
+    await client.connect();
+  }, 120000);
+
+  afterAll(async () => {
+    await client.close();
+    await mongod.stop();
+  });
+
+  const counts = async (
+    dbName: string
+  ): Promise<{ checkpoints: number; writes: number }> => {
+    const db = client.db(dbName);
+    const [checkpoints, writes] = await Promise.all([
+      db.collection('checkpoints').countDocuments({}),
+      db.collection('checkpoint_writes').countDocuments({}),
+    ]);
+    return { checkpoints, writes };
+  };
+
+  describe('normal run (real Run + fake model)', () => {
+    const runOnce = async (
+      dbName: string,
+      durability?: t.Durability
+    ): Promise<void> => {
+      const run = await Run.create<t.IState>({
+        runId: `durability-${dbName}`,
+        graphConfig: {
+          type: 'standard',
+          agents: [
+            {
+              agentId: 'a',
+              provider: Providers.OPENAI,
+              clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+              instructions: 'noop',
+              maxContextTokens: 8000,
+            },
+          ],
+          compileOptions: {
+            checkpointer: new MongoDBSaver({ client, dbName }),
+          },
+        },
+      });
+      // Fake streaming model: one assistant turn, no tool calls -> agent -> END.
+      run.Graph?.overrideTestModel(['done'], 1);
+      await run.processStream(
+        { messages: [new HumanMessage('hi')] },
+        {
+          version: 'v2',
+          ...(durability != null ? { durability } : {}),
+          configurable: { thread_id: dbName },
+        }
+      );
+    };
+
+    it('exit default writes one checkpoint and no per-superstep writes; async writes more of both', async () => {
+      await runOnce('normal_exit');
+      await runOnce('normal_async', 'async');
+
+      const exitCounts = await counts('normal_exit');
+      const asyncCounts = await counts('normal_async');
+
+      // exit: only the final checkpoint, zero per-superstep pending writes.
+      expect(exitCounts).toEqual({ checkpoints: 1, writes: 0 });
+      // async: a checkpoint plus pending writes for every superstep.
+      expect(asyncCounts.checkpoints).toBeGreaterThan(exitCounts.checkpoints);
+      expect(asyncCounts.writes).toBeGreaterThan(exitCounts.writes);
+    });
+  });
+
+  describe('HITL interrupt (langgraph graph + real saver)', () => {
+    const State = Annotation.Root({
+      steps: Annotation<string[]>({
+        reducer: (a, b) => a.concat(b),
+        default: () => [],
+      }),
+    });
+
+    const drain = async (stream: AsyncIterable<unknown>): Promise<void> => {
+      for await (const _event of stream) {
+        // Consume the event stream exactly like Run.processStream does.
+      }
+    };
+
+    const runInterruptGraph = async (
+      dbName: string,
+      durability: t.Durability
+    ): Promise<{
+      atPause: { checkpoints: number; writes: number };
+      done: { checkpoints: number; writes: number };
+    }> => {
+      const saver = new MongoDBSaver({ client, dbName });
+      const graph = new StateGraph(State)
+        .addNode('a', () => ({ steps: ['a'] }))
+        .addNode('b', () => {
+          interrupt({ ask: 'approve?' });
+          return { steps: ['b'] };
+        })
+        .addNode('c', () => ({ steps: ['c'] }))
+        .addEdge(START, 'a')
+        .addEdge('a', 'b')
+        .addEdge('b', 'c')
+        .addEdge('c', END)
+        .compile({ checkpointer: saver });
+
+      // durability rides in the 2nd-arg config, exactly as run.ts threads it.
+      const cfg = {
+        configurable: { thread_id: dbName },
+        durability,
+        version: 'v2' as const,
+      };
+
+      await drain(graph.streamEvents({ steps: [] }, cfg, { raiseError: true }));
+      const atPause = await counts(dbName);
+
+      await drain(
+        graph.streamEvents(new Command({ resume: 'ok' }), cfg, {
+          raiseError: true,
+        })
+      );
+      const done = await counts(dbName);
+
+      return { atPause, done };
+    };
+
+    it('exit checkpoints only at the interrupt boundary and final exit; async checkpoints every superstep', async () => {
+      const exitRun = await runInterruptGraph('hitl_exit', 'exit');
+      const asyncRun = await runInterruptGraph('hitl_async', 'async');
+
+      // exit: one checkpoint at the pause (the interrupt), two once resumed
+      // (interrupt boundary + final exit).
+      expect(exitRun.atPause.checkpoints).toBe(1);
+      expect(exitRun.done.checkpoints).toBe(2);
+
+      // async: a checkpoint for every superstep, strictly more at each stage.
+      expect(asyncRun.atPause.checkpoints).toBeGreaterThan(
+        exitRun.atPause.checkpoints
+      );
+      expect(asyncRun.done.checkpoints).toBeGreaterThan(
+        exitRun.done.checkpoints
+      );
+      expect(asyncRun.done.writes).toBeGreaterThan(exitRun.done.writes);
+    });
+  });
+
+  describe('multiple interrupts (sequential ask-user-questions)', () => {
+    const State = Annotation.Root({
+      qa: Annotation<string[]>({
+        reducer: (a, b) => a.concat(b),
+        default: () => [],
+      }),
+    });
+
+    const drain = async (stream: AsyncIterable<unknown>): Promise<void> => {
+      for await (const _event of stream) {
+        // Consume the event stream.
+      }
+    };
+
+    it('checkpoints each interrupt boundary, chains them, and discards none across resumes', async () => {
+      const dbName = 'multi_exit';
+      const saver = new MongoDBSaver({ client, dbName });
+      const graph = new StateGraph(State)
+        .addNode('ask1', () => ({ qa: [`Q1=${interrupt({ q: 'Q1' })}`] }))
+        .addNode('ask2', () => ({ qa: [`Q2=${interrupt({ q: 'Q2' })}`] }))
+        .addNode('done', () => ({ qa: ['done'] }))
+        .addEdge(START, 'ask1')
+        .addEdge('ask1', 'ask2')
+        .addEdge('ask2', 'done')
+        .addEdge('done', END)
+        .compile({ checkpointer: saver });
+
+      const cfg = {
+        configurable: { thread_id: dbName },
+        durability: 'exit' as const,
+        version: 'v2' as const,
+      };
+
+      // First question -> pauses at ask1, one checkpoint at that boundary.
+      await drain(graph.streamEvents({ qa: [] }, cfg, { raiseError: true }));
+      let state = await graph.getState(cfg);
+      expect(state.next).toEqual(['ask1']);
+      expect((await counts(dbName)).checkpoints).toBe(1);
+
+      // Answer 1 -> the run continues and the LLM asks a second question.
+      // The chain grows to 2: the first interrupt checkpoint is retained as
+      // the parent, not discarded or overwritten.
+      await drain(
+        graph.streamEvents(new Command({ resume: 'A1' }), cfg, {
+          raiseError: true,
+        })
+      );
+      state = await graph.getState(cfg);
+      expect(state.next).toEqual(['ask2']);
+      expect(state.values.qa).toEqual(['Q1=A1']);
+      expect((await counts(dbName)).checkpoints).toBe(2);
+
+      // Answer 2 -> run completes; both answers applied, three checkpoints
+      // total (two interrupt boundaries + final exit).
+      await drain(
+        graph.streamEvents(new Command({ resume: 'A2' }), cfg, {
+          raiseError: true,
+        })
+      );
+      state = await graph.getState(cfg);
+      expect(state.next).toEqual([]);
+      expect(state.values.qa).toEqual(['Q1=A1', 'Q2=A2', 'done']);
+      expect((await counts(dbName)).checkpoints).toBe(3);
+    });
+  });
+});

package/src/tools/__tests__/hitl.test.ts

@@ -761,6 +761,173 @@ describe('Run integration — HITL fallback checkpointer + resume', () => {
     expect(run.Graph?.compileOptions?.checkpointer).toBe(hostCheckpointer);
   });
 
+  it('processStream defaults durability to "exit" when a checkpointer is active', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'durability-exit-default',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+      },
+      humanInTheLoop: { enabled: true },
+    });
+    expect(run.Graph?.compileOptions?.checkpointer).toBeInstanceOf(MemorySaver);
+
+    const graph = new StateGraph(MessagesAnnotation)
+      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
+      .addEdge(START, 'noop')
+      .addEdge('noop', END)
+      .compile();
+    const spy = jest.spyOn(graph, 'streamEvents');
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    await run.processStream(
+      { messages: [] },
+      { version: 'v2', configurable: { thread_id: 't' } }
+    );
+
+    const streamedConfig = spy.mock.calls[0]?.[1] as
+      | t.RunStreamConfig
+      | undefined;
+    expect(streamedConfig?.durability).toBe('exit');
+  });
+
+  it('processStream respects an explicit caller durability over the checkpointer default', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'durability-explicit-override',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+      },
+      humanInTheLoop: { enabled: true },
+    });
+
+    const graph = new StateGraph(MessagesAnnotation)
+      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
+      .addEdge(START, 'noop')
+      .addEdge('noop', END)
+      .compile();
+    const spy = jest.spyOn(graph, 'streamEvents');
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    await run.processStream(
+      { messages: [] },
+      { version: 'v2', durability: 'sync', configurable: { thread_id: 't' } }
+    );
+
+    const streamedConfig = spy.mock.calls[0]?.[1] as
+      | t.RunStreamConfig
+      | undefined;
+    expect(streamedConfig?.durability).toBe('sync');
+  });
+
+  it('processStream leaves durability unset when no checkpointer is active', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'durability-no-checkpointer',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+      },
+      // humanInTheLoop omitted — no checkpointer installed
+    });
+    expect(run.Graph?.compileOptions?.checkpointer).toBeUndefined();
+
+    const graph = new StateGraph(MessagesAnnotation)
+      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
+      .addEdge(START, 'noop')
+      .addEdge('noop', END)
+      .compile();
+    const spy = jest.spyOn(graph, 'streamEvents');
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    await run.processStream(
+      { messages: [] },
+      { version: 'v2', configurable: { thread_id: 't' } }
+    );
+
+    const streamedConfig = spy.mock.calls[0]?.[1] as
+      | t.RunStreamConfig
+      | undefined;
+    expect(streamedConfig?.durability).toBeUndefined();
+  });
+
+  it('defaults durability to "exit" when HITL installs the fallback checkpointer but caller compileOptions omit it', async () => {
+    const { Run } = await import('@/run');
+    const { Providers } = await import('@/common');
+
+    const run = await Run.create<t.IState>({
+      runId: 'durability-hitl-fallback-compileopts',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'a',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'noop',
+            maxContextTokens: 8000,
+          },
+        ],
+        // Caller compileOptions without a checkpointer: HITL adds a MemorySaver
+        // fallback to the compiled graph, but the constructor restores this raw
+        // metadata (no checkpointer) onto Graph.compileOptions.
+        compileOptions: { interruptBefore: [] },
+      },
+      humanInTheLoop: { enabled: true },
+    });
+    expect(run.Graph?.compileOptions?.checkpointer).toBeUndefined();
+
+    const graph = new StateGraph(MessagesAnnotation)
+      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
+      .addEdge(START, 'noop')
+      .addEdge('noop', END)
+      .compile();
+    const spy = jest.spyOn(graph, 'streamEvents');
+    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
+
+    await run.processStream(
+      { messages: [] },
+      { version: 'v2', configurable: { thread_id: 't' } }
+    );
+
+    const streamedConfig = spy.mock.calls[0]?.[1] as
+      | t.RunStreamConfig
+      | undefined;
+    expect(streamedConfig?.durability).toBe('exit');
+  });
+
   it('Run.resume forwards update + goto into the resume Command (langgraph 1.4.5)', async () => {
     const { Run } = await import('@/run');
     const { Providers } = await import('@/common');

package/src/types/run.ts

@@ -261,3 +261,22 @@ export type EventStreamOptions = {
   callbacks?: g.ClientCallbacks;
   keepContent?: boolean;
 };
+
+/**
+ * When to persist checkpoints during a run. Mirrors langgraph's option:
+ * `'async'`/`'sync'` checkpoint every superstep; `'exit'` checkpoints only
+ * at the graph's exit/interrupt boundary. Kept as a local union to avoid
+ * coupling to langgraph internals (it is not exported from the root).
+ */
+export type Durability = 'async' | 'sync' | 'exit';
+
+/**
+ * Config accepted by `processStream`/`resume`. Extends `RunnableConfig` with
+ * the stream `version`, an optional `run_id`, and an optional `durability`
+ * override forwarded to langgraph's run options.
+ */
+export type RunStreamConfig = Partial<RunnableConfig> & {
+  version: 'v1' | 'v2';
+  run_id?: string;
+  durability?: Durability;
+};