feat(langgraph): Allow option to prevent subgraphs inheriting checkpointer

libs/langgraph/src/errors.ts

@@ -97,3 +97,29 @@ export class InvalidUpdateError extends Error {
     return "InvalidUpdateError";
   }
 }
+
+export class MultipleSubgraphsError extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "MultipleSubgraphError";
+  }
+
+  static get unminifiable_name() {
+    return "MultipleSubgraphError";
+  }
+}
+
+/**
+ * Used for subgraph detection.
+ */
+export const getSubgraphsSeenSet = () => {
+  if (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (globalThis as any)[Symbol.for("LG_CHECKPOINT_SEEN_NS_SET")] === undefined
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (globalThis as any)[Symbol.for("LG_CHECKPOINT_SEEN_NS_SET")] = new Set();
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (globalThis as any)[Symbol.for("LG_CHECKPOINT_SEEN_NS_SET")];
+};

libs/langgraph/src/graph/graph.ts

@@ -282,7 +282,7 @@ export class Graph<
     interruptBefore,
     interruptAfter,
   }: {
-    checkpointer?: BaseCheckpointSaver;
+    checkpointer?: BaseCheckpointSaver | false;
     interruptBefore?: N[] | All;
     interruptAfter?: N[] | All;
   } = {}): CompiledGraph<N> {

libs/langgraph/src/graph/state.ts

@@ -362,7 +362,7 @@ export class StateGraph<
     interruptBefore,
     interruptAfter,
   }: {
-    checkpointer?: BaseCheckpointSaver;
+    checkpointer?: BaseCheckpointSaver | false;
     store?: BaseStore;
     interruptBefore?: N[] | All;
     interruptAfter?: N[] | All;

libs/langgraph/src/pregel/index.ts

@@ -274,7 +274,7 @@ export class Pregel<
 
   debug: boolean = false;
 
-  checkpointer?: BaseCheckpointSaver;
+  checkpointer?: BaseCheckpointSaver | false;
 
   retryPolicy?: RetryPolicy;
 
@@ -877,15 +877,16 @@ export class Pregel<
     }
 
     let defaultCheckpointer: BaseCheckpointSaver | undefined;
-    if (
+    if (this.checkpointer === false) {
+      defaultCheckpointer = undefined;
+    } else if (
       config !== undefined &&
       config.configurable?.[CONFIG_KEY_CHECKPOINTER] !== undefined
     ) {
       defaultCheckpointer = config.configurable[CONFIG_KEY_CHECKPOINTER];
     } else {
       defaultCheckpointer = this.checkpointer;
     }
-
     const defaultStore: BaseStore | undefined = config.store ?? this.store;
 
     return [
@@ -1000,6 +1001,7 @@ export class Pregel<
     }
     if (
       this.checkpointer !== undefined &&
+      this.checkpointer !== false &&
       inputConfig.configurable === undefined
     ) {
       throw new Error(

libs/langgraph/src/pregel/io.ts

@@ -72,7 +72,7 @@ export function* mapInput<C extends PropertyKey>(
       }
     } else if (Array.isArray(inputChannels)) {
       throw new Error(
-        "Input chunk must be an object when inputChannels is an array"
+        `Input chunk must be an object when "inputChannels" is an array`
       );
     } else {
       yield [inputChannels, chunk];

libs/langgraph/src/pregel/loop.ts

@@ -50,9 +50,11 @@ import {
   readChannels,
 } from "./io.js";
 import {
+  getSubgraphsSeenSet,
   EmptyInputError,
   GraphInterrupt,
   isGraphInterrupt,
+  MultipleSubgraphsError,
 } from "../errors.js";
 import { getNewChannelVersions, patchConfigurable } from "./utils/index.js";
 import {
@@ -84,6 +86,7 @@ export type PregelLoopInitializeParams = {
   managed: ManagedValueMapping;
   stream: StreamProtocol;
   store?: BaseStore;
+  checkSubgraphs?: boolean;
 };
 
 type PregelLoopParams = {
@@ -232,6 +235,7 @@ export class PregelLoop {
 
   static async initialize(params: PregelLoopInitializeParams) {
     let { config, stream } = params;
+    const { checkSubgraphs = true } = params;
     if (
       stream !== undefined &&
       config.configurable?.[CONFIG_KEY_STREAM] !== undefined
@@ -311,7 +315,20 @@ export class PregelLoop {
       // Start the store. This is a batch store, so it will run continuously
       store.start();
     }
-
+    if (checkSubgraphs && isNested && params.checkpointer !== undefined) {
+      if (getSubgraphsSeenSet().has(config.configurable?.checkpoint_ns)) {
+        throw new MultipleSubgraphsError(
+          [
+            "Detected the same subgraph called multiple times by the same node.",
+            "This is not allowed if checkpointing is enabled.",
+            "",
+            `You can disable checkpointing for a subgraph by compiling it with ".compile({ checkpointer: false });"`,
+          ].join("\n")
+        );
+      } else {
+        getSubgraphsSeenSet().add(config.configurable?.checkpoint_ns);
+      }
+    }
     return new PregelLoop({
       input: params.input,
       config,

libs/langgraph/src/pregel/retry.ts

@@ -1,4 +1,4 @@
-import { isGraphInterrupt } from "../errors.js";
+import { getSubgraphsSeenSet, isGraphInterrupt } from "../errors.js";
 import { PregelExecutableTask } from "./types.js";
 import type { RetryPolicy } from "./utils/index.js";
 
@@ -167,6 +167,16 @@ async function _runWithRetry(
           2
         )} seconds (attempt ${attempts}) after ${errorName}: ${error}`
       );
+      // Clear checkpoint_ns seen (for subgraph detection)
+      const checkpointNs = pregelTask.config?.configurable?.checkpoint_ns;
+      if (checkpointNs) {
+        getSubgraphsSeenSet().delete(checkpointNs);
+      }
+    } finally {
+      const checkpointNs = pregelTask.config?.configurable?.checkpoint_ns;
+      if (checkpointNs) {
+        getSubgraphsSeenSet().delete(checkpointNs);
+      }
     }
   }
   return {

libs/langgraph/src/pregel/types.ts

@@ -68,7 +68,7 @@ export interface PregelInterface<
    */
   debug?: boolean;
 
-  checkpointer?: BaseCheckpointSaver;
+  checkpointer?: BaseCheckpointSaver | false;
 
   retryPolicy?: RetryPolicy;
 

libs/langgraph/src/tests/pregel.io.test.ts

@@ -199,7 +199,9 @@ describe("mapInput", () => {
         // do nothing, error will be thrown
         continue;
       }
-    }).toThrow("Input chunk must be an object when inputChannels is an array");
+    }).toThrow(
+      `Input chunk must be an object when "inputChannels" is an array`
+    );
   });
 });