@langchain/langgraph 0.2.45 → 0.2.47

package/dist/pregel/runner.cjs

@@ -37,7 +37,7 @@ class PregelRunner {
      */
     async tick(options = {}) {
         const { timeout, signal, retryPolicy, onStepWrite } = options;
-        let graphInterrupt;
+        let graphBubbleUp;
         // Start task execution
         const pendingTasks = Object.values(this.loop.tasks).filter((t) => t.writes.length === 0);
         const taskStream = this._executeTasksWithRetry(pendingTasks, {
@@ -46,13 +46,22 @@ class PregelRunner {
             retryPolicy,
         });
         for await (const { task, error } of taskStream) {
-            graphInterrupt = this._commit(task, error) ?? graphInterrupt;
+            this._commit(task, error);
+            if ((0, errors_js_1.isGraphInterrupt)(error)) {
+                graphBubbleUp = error;
+            }
+            else if ((0, errors_js_1.isGraphBubbleUp)(error) && !(0, errors_js_1.isGraphInterrupt)(graphBubbleUp)) {
+                graphBubbleUp = error;
+            }
         }
         onStepWrite?.(this.loop.step, Object.values(this.loop.tasks)
             .map((task) => task.writes)
             .flat());
-        if (graphInterrupt) {
-            throw graphInterrupt;
+        if ((0, errors_js_1.isGraphInterrupt)(graphBubbleUp)) {
+            throw graphBubbleUp;
+        }
+        if ((0, errors_js_1.isGraphBubbleUp)(graphBubbleUp) && this.loop.isNested) {
+            throw graphBubbleUp;
         }
     }
     /**
@@ -225,35 +234,29 @@ class PregelRunner {
      *
      * Throws an error if the error is a {@link GraphBubbleUp} error and {@link PregelLoop}#isNested is true.
      *
-     * Note that in the case of a {@link GraphBubbleUp} error that is not a {@link GraphInterrupt}, like a {@link Command}, this method does not apply any writes.
-     *
      * @param task - The task to commit.
      * @param error - The error that occurred, if any.
-     * @returns The {@link GraphInterrupt} that occurred, if the user's code threw one.
      */
     _commit(task, error) {
-        let graphInterrupt;
         if (error !== undefined) {
-            if ((0, errors_js_1.isGraphBubbleUp)(error)) {
-                if (this.loop.isNested) {
-                    throw error;
-                }
-                if ((0, errors_js_1.isGraphInterrupt)(error)) {
-                    graphInterrupt = error;
-                    if (error.interrupts.length) {
-                        const interrupts = error.interrupts.map((interrupt) => [constants_js_1.INTERRUPT, interrupt]);
-                        const resumes = task.writes.filter((w) => w[0] === constants_js_1.RESUME);
-                        if (resumes.length) {
-                            interrupts.push(...resumes);
-                        }
-                        this.loop.putWrites(task.id, interrupts);
+            if ((0, errors_js_1.isGraphInterrupt)(error)) {
+                if (error.interrupts.length) {
+                    const interrupts = error.interrupts.map((interrupt) => [constants_js_1.INTERRUPT, interrupt]);
+                    const resumes = task.writes.filter((w) => w[0] === constants_js_1.RESUME);
+                    if (resumes.length) {
+                        interrupts.push(...resumes);
                     }
+                    this.loop.putWrites(task.id, interrupts);
                 }
             }
+            else if ((0, errors_js_1.isGraphBubbleUp)(error) && task.writes.length) {
+                this.loop.putWrites(task.id, task.writes);
+            }
             else {
                 this.loop.putWrites(task.id, [
                     [constants_js_1.ERROR, { message: error.message, name: error.name }],
                 ]);
+                // TODO: is throwing here safe? what about commits from other concurrent tasks?
                 throw error;
             }
         }
@@ -269,7 +272,6 @@ class PregelRunner {
             // Save task writes to checkpointer
             this.loop.putWrites(task.id, task.writes);
         }
-        return graphInterrupt;
     }
 }
 exports.PregelRunner = PregelRunner;

package/dist/pregel/runner.d.ts

@@ -54,11 +54,8 @@ export declare class PregelRunner {
      *
      * Throws an error if the error is a {@link GraphBubbleUp} error and {@link PregelLoop}#isNested is true.
      *
-     * Note that in the case of a {@link GraphBubbleUp} error that is not a {@link GraphInterrupt}, like a {@link Command}, this method does not apply any writes.
-     *
      * @param task - The task to commit.
      * @param error - The error that occurred, if any.
-     * @returns The {@link GraphInterrupt} that occurred, if the user's code threw one.
      */
     private _commit;
 }

package/dist/pregel/runner.js

@@ -1,6 +1,6 @@
 import { Call } from "./types.js";
 import { CONFIG_KEY_SEND, CONFIG_KEY_SCRATCHPAD, PUSH, ERROR, INTERRUPT, RESUME, NO_WRITES, TAG_HIDDEN, RETURN, CONFIG_KEY_CALL, } from "../constants.js";
-import { isGraphBubbleUp, isGraphInterrupt, } from "../errors.js";
+import { isGraphBubbleUp, isGraphInterrupt } from "../errors.js";
 import { _runWithRetry } from "./retry.js";
 /**
  * Responsible for handling task execution on each tick of the {@link PregelLoop}.
@@ -34,7 +34,7 @@ export class PregelRunner {
      */
     async tick(options = {}) {
         const { timeout, signal, retryPolicy, onStepWrite } = options;
-        let graphInterrupt;
+        let graphBubbleUp;
         // Start task execution
         const pendingTasks = Object.values(this.loop.tasks).filter((t) => t.writes.length === 0);
         const taskStream = this._executeTasksWithRetry(pendingTasks, {
@@ -43,13 +43,22 @@ export class PregelRunner {
             retryPolicy,
         });
         for await (const { task, error } of taskStream) {
-            graphInterrupt = this._commit(task, error) ?? graphInterrupt;
+            this._commit(task, error);
+            if (isGraphInterrupt(error)) {
+                graphBubbleUp = error;
+            }
+            else if (isGraphBubbleUp(error) && !isGraphInterrupt(graphBubbleUp)) {
+                graphBubbleUp = error;
+            }
         }
         onStepWrite?.(this.loop.step, Object.values(this.loop.tasks)
             .map((task) => task.writes)
             .flat());
-        if (graphInterrupt) {
-            throw graphInterrupt;
+        if (isGraphInterrupt(graphBubbleUp)) {
+            throw graphBubbleUp;
+        }
+        if (isGraphBubbleUp(graphBubbleUp) && this.loop.isNested) {
+            throw graphBubbleUp;
         }
     }
     /**
@@ -222,35 +231,29 @@ export class PregelRunner {
      *
      * Throws an error if the error is a {@link GraphBubbleUp} error and {@link PregelLoop}#isNested is true.
      *
-     * Note that in the case of a {@link GraphBubbleUp} error that is not a {@link GraphInterrupt}, like a {@link Command}, this method does not apply any writes.
-     *
      * @param task - The task to commit.
      * @param error - The error that occurred, if any.
-     * @returns The {@link GraphInterrupt} that occurred, if the user's code threw one.
      */
     _commit(task, error) {
-        let graphInterrupt;
         if (error !== undefined) {
-            if (isGraphBubbleUp(error)) {
-                if (this.loop.isNested) {
-                    throw error;
-                }
-                if (isGraphInterrupt(error)) {
-                    graphInterrupt = error;
-                    if (error.interrupts.length) {
-                        const interrupts = error.interrupts.map((interrupt) => [INTERRUPT, interrupt]);
-                        const resumes = task.writes.filter((w) => w[0] === RESUME);
-                        if (resumes.length) {
-                            interrupts.push(...resumes);
-                        }
-                        this.loop.putWrites(task.id, interrupts);
+            if (isGraphInterrupt(error)) {
+                if (error.interrupts.length) {
+                    const interrupts = error.interrupts.map((interrupt) => [INTERRUPT, interrupt]);
+                    const resumes = task.writes.filter((w) => w[0] === RESUME);
+                    if (resumes.length) {
+                        interrupts.push(...resumes);
                     }
+                    this.loop.putWrites(task.id, interrupts);
                 }
             }
+            else if (isGraphBubbleUp(error) && task.writes.length) {
+                this.loop.putWrites(task.id, task.writes);
+            }
             else {
                 this.loop.putWrites(task.id, [
                     [ERROR, { message: error.message, name: error.name }],
                 ]);
+                // TODO: is throwing here safe? what about commits from other concurrent tasks?
                 throw error;
             }
         }
@@ -266,6 +269,5 @@ export class PregelRunner {
             // Save task writes to checkpointer
             this.loop.putWrites(task.id, task.writes);
         }
-        return graphInterrupt;
     }
 }

package/dist/pregel/types.d.ts

@@ -15,27 +15,112 @@ export type StreamMode = "values" | "updates" | "debug" | "messages" | "custom";
 export type PregelInputType = any;
 export type PregelOutputType = any;
 /**
- * Config for executing the graph.
+ * Configuration options for executing a Pregel graph.
+ * These options control how the graph executes, what data is streamed, and how interrupts are handled.
+ *
+ * @typeParam Nodes - Mapping of node names to their {@link PregelNode} implementations
+ * @typeParam Channels - Mapping of channel names to their {@link BaseChannel} or {@link ManagedValueSpec} implementations
+ * @typeParam ConfigurableFieldType - Type of configurable fields in the {@link RunnableConfig} that is passed to the graph
  */
-export interface PregelOptions<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel | ManagedValueSpec>, ConfigurableFieldType extends Record<string, any> = Record<string, any>> extends RunnableConfig<ConfigurableFieldType> {
+export interface PregelOptions<Nodes extends StrRecord<string, PregelNode>, Channels extends StrRecord<string, BaseChannel | ManagedValueSpec>, ConfigurableFieldType extends Record<string, any> = Record<string, any>> extends RunnableConfig<ConfigurableFieldType> {
     /**
-     * The stream mode for the graph run. See [Streaming](/langgraphjs/how-tos/#streaming) for more details.
+     * Controls what information is streamed during graph execution.
+     * Multiple modes can be enabled simultaneously.
+     *
+     * Supported modes:
+     * - "values": Streams complete state after each step
+     * - "updates": Streams only state changes after each step
+     * - "messages": Streams messages from within nodes
+     * - "custom": Streams custom events from within nodes
+     * - "debug": Streams detailed execution events for tracing & debugging
+     *
+     * @example
+     * ```typescript
+     * // Stream only values
+     * streamMode: "values"
+     *
+     * // Stream both values and debug info
+     * streamMode: ["values", "debug"]
+     * ```
+     *
      * @default ["values"]
      */
     streamMode?: StreamMode | StreamMode[];
-    /** The input keys to retrieve from the checkpoint on resume. You generally don't need to set this. */
-    inputKeys?: keyof Cc | Array<keyof Cc>;
-    /** The output keys to retrieve from the graph run. */
-    outputKeys?: keyof Cc | Array<keyof Cc>;
-    /** The nodes to interrupt the graph run before. */
-    interruptBefore?: All | Array<keyof Nn>;
-    /** The nodes to interrupt the graph run after. */
-    interruptAfter?: All | Array<keyof Nn>;
-    /** Enable debug mode for the graph run. */
+    /**
+     * Specifies which channel keys to retrieve from the checkpoint when resuming execution.
+     * This is an advanced option that you generally don't need to set manually.
+     * The graph will automatically determine the appropriate input keys based on its configuration.
+     */
+    inputKeys?: keyof Channels | Array<keyof Channels>;
+    /**
+     * Specifies which channel keys to include in the output stream and final result.
+     * Use this to filter which parts of the graph state you want to observe.
+     *
+     * @example
+     * ```typescript
+     * // Stream only the 'result' channel
+     * outputKeys: "result"
+     *
+     * // Stream multiple channels
+     * outputKeys: ["result", "intermediateState"]
+     * ```
+     */
+    outputKeys?: keyof Channels | Array<keyof Channels>;
+    /**
+     * List of nodes where execution should be interrupted BEFORE the node runs.
+     * Can be used for debugging and advanced state manipulation use cases. For
+     * human-in-the-loop workflows, developers should prefer the
+     * @link {interrupt} function instead.
+     *
+     * When interrupted, a resume @link {Command} must be provided to continue
+     * execution.
+     *
+     * @example
+     * ```typescript
+     * // Interrupt before specific nodes
+     * interruptBefore: ["humanReview", "qualityCheck"]
+     *
+     * // Interrupt before all nodes
+     * interruptBefore: "all"
+     * ```
+     */
+    interruptBefore?: All | Array<keyof Nodes>;
+    /**
+     * List of nodes where execution should be interrupted AFTER the node runs.
+     * Similar to interruptBefore, but interrupts after node completion.
+     * Useful when the node's output needs to be reviewed before proceeding.
+     *
+     * @example
+     * ```typescript
+     * // Interrupt after specific nodes
+     * interruptAfter: ["generateContent", "analyze"]
+     *
+     * // Interrupt after all nodes
+     * interruptAfter: "all"
+     * ```
+     */
+    interruptAfter?: All | Array<keyof Nodes>;
+    /**
+     * Enables detailed debug logging during graph execution.
+     * When enabled, prints information about:
+     * - Task execution
+     * - Channel updates
+     * - Checkpoint writes
+     *
+     * @default false
+     */
     debug?: boolean;
-    /** Whether to stream subgraphs. */
+    /**
+     * Whether to include subgraph execution details in the stream.
+     * When true, state updates from nested graphs will also be streamed.
+     *
+     * @default false
+     */
     subgraphs?: boolean;
-    /** The shared value store */
+    /**
+     * A shared value store that allows you to store and retrieve state across
+     * threads. Useful for implementing long-term memory patterns.
+     */
     store?: BaseStore;
 }
 /**
@@ -44,9 +129,9 @@ export interface PregelOptions<Nn extends StrRecord<string, PregelNode>, Cc exte
 type StrRecord<K extends string, T> = {
     [P in K]: T;
 };
-export interface PregelInterface<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel | ManagedValueSpec>, ConfigurableFieldType extends Record<string, any> = StrRecord<string, any>> {
+export interface PregelInterface<Nodes extends StrRecord<string, PregelNode>, Channels extends StrRecord<string, BaseChannel | ManagedValueSpec>, ConfigurableFieldType extends Record<string, any> = StrRecord<string, any>> {
     lg_is_pregel: boolean;
-    withConfig(config: RunnableConfig): PregelInterface<Nn, Cc>;
+    withConfig(config: RunnableConfig): PregelInterface<Nodes, Channels>;
     getGraphAsync(config: RunnableConfig & {
         xray?: boolean | number;
     }): Promise<DrawableGraph>;
@@ -57,15 +142,15 @@ export interface PregelInterface<Nn extends StrRecord<string, PregelNode>, Cc ex
         subgraphs?: boolean;
     }): Promise<StateSnapshot>;
     getStateHistory(config: RunnableConfig, options?: CheckpointListOptions): AsyncIterableIterator<StateSnapshot>;
-    updateState(inputConfig: LangGraphRunnableConfig, values: Record<string, unknown> | unknown, asNode?: keyof Nn | string): Promise<RunnableConfig>;
-    stream(input: PregelInputType, options?: Partial<PregelOptions<Nn, Cc, ConfigurableFieldType>>): Promise<IterableReadableStream<PregelOutputType>>;
-    invoke(input: PregelInputType, options?: Partial<PregelOptions<Nn, Cc, ConfigurableFieldType>>): Promise<PregelOutputType>;
+    updateState(inputConfig: LangGraphRunnableConfig, values: Record<string, unknown> | unknown, asNode?: keyof Nodes | string): Promise<RunnableConfig>;
+    stream(input: PregelInputType, options?: Partial<PregelOptions<Nodes, Channels, ConfigurableFieldType>>): Promise<IterableReadableStream<PregelOutputType>>;
+    invoke(input: PregelInputType, options?: Partial<PregelOptions<Nodes, Channels, ConfigurableFieldType>>): Promise<PregelOutputType>;
 }
 /**
  * Parameters for creating a Pregel graph.
  * @internal
  */
-export type PregelParams<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel | ManagedValueSpec>> = {
+export type PregelParams<Nodes extends StrRecord<string, PregelNode>, Channels extends StrRecord<string, BaseChannel | ManagedValueSpec>> = {
     /**
      * The name of the graph. @see {@link Runnable.name}
      */
@@ -73,11 +158,11 @@ export type PregelParams<Nn extends StrRecord<string, PregelNode>, Cc extends St
     /**
      * The nodes in the graph.
      */
-    nodes: Nn;
+    nodes: Nodes;
     /**
      * The channels in the graph.
      */
-    channels: Cc;
+    channels: Channels;
     /**
      * Whether to validate the graph.
      *
@@ -93,26 +178,26 @@ export type PregelParams<Nn extends StrRecord<string, PregelNode>, Cc extends St
     /**
      * The input channels for the graph run.
      */
-    inputChannels: keyof Cc | Array<keyof Cc>;
+    inputChannels: keyof Channels | Array<keyof Channels>;
     /**
      * The output channels for the graph run.
      */
-    outputChannels: keyof Cc | Array<keyof Cc>;
+    outputChannels: keyof Channels | Array<keyof Channels>;
     /**
      * After processing one of the nodes named in this list, the graph will be interrupted and a resume {@link Command} must be provided to proceed with the execution of this thread.
      * @default []
      */
-    interruptAfter?: Array<keyof Nn> | All;
+    interruptAfter?: Array<keyof Nodes> | All;
     /**
      * Before processing one of the nodes named in this list, the graph will be interrupted and a resume {@link Command} must be provided to proceed with the execution of this thread.
      * @default []
      */
-    interruptBefore?: Array<keyof Nn> | All;
+    interruptBefore?: Array<keyof Nodes> | All;
     /**
      * The channels to stream from the graph run.
      * @default []
      */
-    streamChannels?: keyof Cc | Array<keyof Cc>;
+    streamChannels?: keyof Channels | Array<keyof Channels>;
     /**
      * @default undefined
      */
@@ -146,11 +231,11 @@ export interface PregelTaskDescription {
     readonly state?: LangGraphRunnableConfig | StateSnapshot;
     readonly path?: TaskPath;
 }
-export interface PregelExecutableTask<N extends PropertyKey, C extends PropertyKey> {
-    readonly name: N;
+export interface PregelExecutableTask<NodeKey extends PropertyKey, ChannelKey extends PropertyKey> {
+    readonly name: NodeKey;
     readonly input: unknown;
     readonly proc: Runnable<any, any, LangGraphRunnableConfig>;
-    readonly writes: PendingWrite<C>[];
+    readonly writes: PendingWrite<ChannelKey>[];
     readonly config?: LangGraphRunnableConfig;
     readonly triggers: Array<string>;
     readonly retry_policy?: RetryPolicy;
@@ -190,6 +275,45 @@ export interface StateSnapshot {
      */
     readonly tasks: PregelTaskDescription[];
 }
+/**
+ * Options for subscribing to multiple channels.
+ */
+export type MultipleChannelSubscriptionOptions = {
+    /**
+     * Optional tags to associate with the subscription.
+     */
+    tags?: string[];
+};
+/**
+ * Options for subscribing to a single channel.
+ */
+export type SingleChannelSubscriptionOptions = {
+    /**
+     * When specified, the channel mapping will be an object with this key pointing
+     * to the array of channels to subscribe to. Otherwise, the channel mapping
+     * will be an array of channels.
+     */
+    key?: string;
+    /**
+     * Optional tags to associate with the subscription.
+     */
+    tags?: string[];
+};
+/**
+ * Options for getting the state of the graph.
+ */
+export type GetStateOptions = {
+    /**
+     * Whether to include subgraph states.
+     * @default false
+     */
+    subgraphs?: boolean;
+};
+/**
+ * Used for storing/retrieving internal execution state.
+ *
+ * @internal
+ */
 export type PregelScratchpad<Resume = unknown> = {
     /** Counter for tracking call invocations */
     callCounter: number;

package/dist/web.d.ts

@@ -1,11 +1,11 @@
 export { Graph, type StateGraphArgs, StateGraph, CompiledStateGraph, MessageGraph, messagesStateReducer, messagesStateReducer as addMessages, type Messages, Annotation, type StateType, type UpdateType, type NodeType, type StateDefinition, type SingleReducer, type CompiledGraph, } from "./graph/index.js";
-export type { StateSnapshot, StreamMode, PregelParams, PregelOptions, } from "./pregel/types.js";
+export type { StateSnapshot, StreamMode, PregelParams, PregelOptions, SingleChannelSubscriptionOptions, MultipleChannelSubscriptionOptions, GetStateOptions, } from "./pregel/types.js";
 export type { PregelNode } from "./pregel/read.js";
 export type { Pregel } from "./pregel/index.js";
 export * from "./errors.js";
 export { BaseChannel, type BinaryOperator, BinaryOperatorAggregate, type AnyValue, type WaitForNames, type DynamicBarrierValue, type LastValue, type NamedBarrierValue, type Topic, } from "./channels/index.js";
 export type { EphemeralValue } from "./channels/ephemeral_value.js";
-export { type AnnotationRoot as _INTERNAL_ANNOTATION_ROOT } from "./graph/index.js";
+export { type AnnotationRoot } from "./graph/index.js";
 export { type RetryPolicy } from "./pregel/utils/index.js";
 export { Send, Command, type CommandParams, isCommand, START, END, type Interrupt, } from "./constants.js";
 export { MemorySaver, type Checkpoint, type CheckpointMetadata, type CheckpointTuple, copyCheckpoint, emptyCheckpoint, BaseCheckpointSaver, type Item, type GetOperation, type SearchOperation, type PutOperation, type Operation, type OperationResults, BaseStore, AsyncBatchedStore, InMemoryStore, type NameSpacePath, type NamespaceMatchType, type MatchCondition, type ListNamespacesOperation, } from "@langchain/langgraph-checkpoint";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph",
-  "version": "0.2.45",
+  "version": "0.2.47",
   "description": "LangGraph",
   "type": "module",
   "engines": {
@@ -37,13 +37,13 @@
     "zod": "^3.23.8"
   },
   "peerDependencies": {
-    "@langchain/core": ">=0.2.36 <0.3.0 || >=0.3.9 < 0.4.0"
+    "@langchain/core": ">=0.2.36 <0.3.0 || >=0.3.40 < 0.4.0"
   },
   "devDependencies": {
     "@jest/globals": "^29.5.0",
     "@langchain/anthropic": "^0.3.12",
     "@langchain/community": "^0.3.27",
-    "@langchain/core": "^0.3.36",
+    "@langchain/core": "^0.3.40",
     "@langchain/langgraph-checkpoint-postgres": "workspace:*",
     "@langchain/langgraph-checkpoint-sqlite": "workspace:*",
     "@langchain/openai": "^0.4.0",
@@ -72,7 +72,7 @@
     "pg": "^8.13.0",
     "prettier": "^2.8.3",
     "release-it": "^17.6.0",
-    "rollup": "^4.32.1",
+    "rollup": "^4.34.7",
     "ts-jest": "^29.1.0",
     "tsx": "^4.7.0",
     "typescript": "^4.9.5 || ^5.4.5",