@langchain/langgraph 0.2.27 → 0.2.29

package/dist/graph/state.cjs

@@ -240,6 +240,7 @@ class StateGraph extends graph_js_1.Graph {
                 ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     [runnable]
                 : options?.subgraphs,
+            ends: options?.ends,
         };
         this.nodes[key] = nodeSpec;
         return this;
@@ -303,6 +304,14 @@ class StateGraph extends graph_js_1.Graph {
         for (const [key, node] of Object.entries(this.nodes)) {
             compiled.attachNode(key, node);
         }
+        compiled.attachBranch(graph_js_1.START, constants_js_1.SELF, _getControlBranch(), {
+            withReader: false,
+        });
+        for (const [key] of Object.entries(this.nodes)) {
+            compiled.attachBranch(key, constants_js_1.SELF, _getControlBranch(), {
+                withReader: false,
+            });
+        }
         for (const [start, end] of this.edges) {
             compiled.attachEdge(start, end);
         }
@@ -339,13 +348,30 @@ function _getChannels(schema) {
 class CompiledStateGraph extends graph_js_1.CompiledGraph {
     attachNode(key, node) {
         const stateKeys = Object.keys(this.builder.channels);
+        function _getRoot(input) {
+            if ((0, constants_js_1._isCommand)(input)) {
+                if (input.graph === constants_js_1.Command.PARENT) {
+                    return write_js_1.SKIP_WRITE;
+                }
+                return input.update;
+            }
+            return input;
+        }
+        // to avoid name collision below
+        const nodeKey = key;
         function getStateKey(key, input) {
             if (!input) {
                 return write_js_1.SKIP_WRITE;
             }
+            else if ((0, constants_js_1._isCommand)(input)) {
+                if (input.graph === constants_js_1.Command.PARENT) {
+                    return write_js_1.SKIP_WRITE;
+                }
+                return getStateKey(key, input.update);
+            }
             else if (typeof input !== "object" || Array.isArray(input)) {
                 const typeofInput = Array.isArray(input) ? "array" : typeof input;
-                throw new errors_js_1.InvalidUpdateError(`Expected node "${key.toString()}" to return an object, received ${typeofInput}`, {
+                throw new errors_js_1.InvalidUpdateError(`Expected node "${nodeKey.toString()}" to return an object, received ${typeofInput}`, {
                     lc_error_code: "INVALID_GRAPH_NODE_RETURN_VALUE",
                 });
             }
@@ -355,7 +381,16 @@ class CompiledStateGraph extends graph_js_1.CompiledGraph {
         }
         // state updaters
         const stateWriteEntries = stateKeys.map((key) => key === ROOT
-            ? { channel: key, value: write_js_1.PASSTHROUGH, skipNone: true }
+            ? {
+                channel: key,
+                value: write_js_1.PASSTHROUGH,
+                skipNone: true,
+                mapper: new utils_js_1.RunnableCallable({
+                    func: _getRoot,
+                    trace: false,
+                    recurse: false,
+                }),
+            }
             : {
                 channel: key,
                 value: write_js_1.PASSTHROUGH,
@@ -397,6 +432,7 @@ class CompiledStateGraph extends graph_js_1.CompiledGraph {
                 metadata: node?.metadata,
                 retryPolicy: node?.retryPolicy,
                 subgraphs: node?.subgraphs,
+                ends: node?.ends,
             });
         }
     }
@@ -430,28 +466,29 @@ class CompiledStateGraph extends graph_js_1.CompiledGraph {
             this.nodes[end].triggers.push(start);
         }
     }
-    attachBranch(start, name, branch) {
-        // attach branch publisher
-        this.nodes[start].writers.push(branch.compile(
-        // writer
-        (dests) => {
-            const filteredDests = dests.filter((dest) => dest !== graph_js_1.END);
-            if (!filteredDests.length) {
+    attachBranch(start, name, branch, options = { withReader: true }) {
+        const branchWriter = async (packets, config) => {
+            const filteredPackets = packets.filter((p) => p !== graph_js_1.END);
+            if (!filteredPackets.length) {
                 return;
             }
-            const writes = filteredDests.map((dest) => {
-                if ((0, constants_js_1._isSend)(dest)) {
-                    return dest;
+            const writes = filteredPackets.map((p) => {
+                if ((0, constants_js_1._isSend)(p)) {
+                    return p;
                 }
                 return {
-                    channel: `branch:${start}:${name}:${dest}`,
+                    channel: `branch:${start}:${name}:${p}`,
                     value: start,
                 };
             });
-            return new write_js_1.ChannelWrite(writes, [constants_js_1.TAG_HIDDEN]);
-        }, 
+            await write_js_1.ChannelWrite.doWrite({ ...config, tags: (config.tags ?? []).concat([constants_js_1.TAG_HIDDEN]) }, writes);
+        };
+        // attach branch publisher
+        this.nodes[start].writers.push(branch.run(branchWriter, 
         // reader
-        (config) => read_js_1.ChannelRead.doRead(config, this.streamChannels ?? this.outputChannels, true)));
+        options.withReader
+            ? (config) => read_js_1.ChannelRead.doRead(config, this.streamChannels ?? this.outputChannels, true)
+            : undefined));
         // attach branch subscribers
         const ends = branch.ends
             ? Object.values(branch.ends)
@@ -499,3 +536,28 @@ function isStateGraphArgsWithInputOutputSchemas(obj) {
         obj.input !== undefined &&
         obj.output !== undefined);
 }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function _controlBranch(value) {
+    if ((0, constants_js_1._isSend)(value)) {
+        return [value];
+    }
+    if (!(0, constants_js_1._isCommand)(value)) {
+        return [];
+    }
+    if (value.graph === constants_js_1.Command.PARENT) {
+        throw new errors_js_1.ParentCommand(value);
+    }
+    return Array.isArray(value.goto) ? value.goto : [value.goto];
+}
+function _getControlBranch() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const CONTROL_BRANCH_PATH = new utils_js_1.RunnableCallable({
+        func: _controlBranch,
+        tags: [constants_js_1.TAG_HIDDEN],
+        trace: false,
+        recurse: false,
+    });
+    return new graph_js_1.Branch({
+        path: CONTROL_BRANCH_PATH,
+    });
+}

package/dist/graph/state.d.ts

@@ -133,5 +133,7 @@ export declare class CompiledStateGraph<S, U, N extends string = typeof START, I
     attachNode(key: typeof START, node?: never): void;
     attachNode(key: N, node: StateGraphNodeSpec<S, U>): void;
     attachEdge(start: N | N[] | "__start__", end: N | "__end__"): void;
-    attachBranch(start: N | typeof START, name: string, branch: Branch<S, N>): void;
+    attachBranch(start: N | typeof START, name: string, branch: Branch<S, N>, options?: {
+        withReader?: boolean;
+    }): void;
 }

package/dist/graph/state.js

@@ -1,14 +1,14 @@
 /* eslint-disable @typescript-eslint/no-use-before-define */
 import { _coerceToRunnable, Runnable, } from "@langchain/core/runnables";
 import { isBaseChannel } from "../channels/base.js";
-import { END, CompiledGraph, Graph, START, } from "./graph.js";
+import { END, CompiledGraph, Graph, START, Branch, } from "./graph.js";
 import { ChannelWrite, PASSTHROUGH, SKIP_WRITE, } from "../pregel/write.js";
 import { ChannelRead, PregelNode } from "../pregel/read.js";
 import { NamedBarrierValue } from "../channels/named_barrier_value.js";
 import { EphemeralValue } from "../channels/ephemeral_value.js";
 import { RunnableCallable } from "../utils.js";
-import { _isSend, CHECKPOINT_NAMESPACE_END, CHECKPOINT_NAMESPACE_SEPARATOR, TAG_HIDDEN, } from "../constants.js";
-import { InvalidUpdateError } from "../errors.js";
+import { _isCommand, _isSend, CHECKPOINT_NAMESPACE_END, CHECKPOINT_NAMESPACE_SEPARATOR, Command, SELF, TAG_HIDDEN, } from "../constants.js";
+import { InvalidUpdateError, ParentCommand } from "../errors.js";
 import { getChannel, } from "./annotation.js";
 import { isConfiguredManagedValue } from "../managed/base.js";
 import { isPregelLike } from "../pregel/utils/subgraph.js";
@@ -237,6 +237,7 @@ export class StateGraph extends Graph {
                 ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     [runnable]
                 : options?.subgraphs,
+            ends: options?.ends,
         };
         this.nodes[key] = nodeSpec;
         return this;
@@ -300,6 +301,14 @@ export class StateGraph extends Graph {
         for (const [key, node] of Object.entries(this.nodes)) {
             compiled.attachNode(key, node);
         }
+        compiled.attachBranch(START, SELF, _getControlBranch(), {
+            withReader: false,
+        });
+        for (const [key] of Object.entries(this.nodes)) {
+            compiled.attachBranch(key, SELF, _getControlBranch(), {
+                withReader: false,
+            });
+        }
         for (const [start, end] of this.edges) {
             compiled.attachEdge(start, end);
         }
@@ -335,13 +344,30 @@ function _getChannels(schema) {
 export class CompiledStateGraph extends CompiledGraph {
     attachNode(key, node) {
         const stateKeys = Object.keys(this.builder.channels);
+        function _getRoot(input) {
+            if (_isCommand(input)) {
+                if (input.graph === Command.PARENT) {
+                    return SKIP_WRITE;
+                }
+                return input.update;
+            }
+            return input;
+        }
+        // to avoid name collision below
+        const nodeKey = key;
         function getStateKey(key, input) {
             if (!input) {
                 return SKIP_WRITE;
             }
+            else if (_isCommand(input)) {
+                if (input.graph === Command.PARENT) {
+                    return SKIP_WRITE;
+                }
+                return getStateKey(key, input.update);
+            }
             else if (typeof input !== "object" || Array.isArray(input)) {
                 const typeofInput = Array.isArray(input) ? "array" : typeof input;
-                throw new InvalidUpdateError(`Expected node "${key.toString()}" to return an object, received ${typeofInput}`, {
+                throw new InvalidUpdateError(`Expected node "${nodeKey.toString()}" to return an object, received ${typeofInput}`, {
                     lc_error_code: "INVALID_GRAPH_NODE_RETURN_VALUE",
                 });
             }
@@ -351,7 +377,16 @@ export class CompiledStateGraph extends CompiledGraph {
         }
         // state updaters
         const stateWriteEntries = stateKeys.map((key) => key === ROOT
-            ? { channel: key, value: PASSTHROUGH, skipNone: true }
+            ? {
+                channel: key,
+                value: PASSTHROUGH,
+                skipNone: true,
+                mapper: new RunnableCallable({
+                    func: _getRoot,
+                    trace: false,
+                    recurse: false,
+                }),
+            }
             : {
                 channel: key,
                 value: PASSTHROUGH,
@@ -393,6 +428,7 @@ export class CompiledStateGraph extends CompiledGraph {
                 metadata: node?.metadata,
                 retryPolicy: node?.retryPolicy,
                 subgraphs: node?.subgraphs,
+                ends: node?.ends,
             });
         }
     }
@@ -426,28 +462,29 @@ export class CompiledStateGraph extends CompiledGraph {
             this.nodes[end].triggers.push(start);
         }
     }
-    attachBranch(start, name, branch) {
-        // attach branch publisher
-        this.nodes[start].writers.push(branch.compile(
-        // writer
-        (dests) => {
-            const filteredDests = dests.filter((dest) => dest !== END);
-            if (!filteredDests.length) {
+    attachBranch(start, name, branch, options = { withReader: true }) {
+        const branchWriter = async (packets, config) => {
+            const filteredPackets = packets.filter((p) => p !== END);
+            if (!filteredPackets.length) {
                 return;
             }
-            const writes = filteredDests.map((dest) => {
-                if (_isSend(dest)) {
-                    return dest;
+            const writes = filteredPackets.map((p) => {
+                if (_isSend(p)) {
+                    return p;
                 }
                 return {
-                    channel: `branch:${start}:${name}:${dest}`,
+                    channel: `branch:${start}:${name}:${p}`,
                     value: start,
                 };
             });
-            return new ChannelWrite(writes, [TAG_HIDDEN]);
-        }, 
+            await ChannelWrite.doWrite({ ...config, tags: (config.tags ?? []).concat([TAG_HIDDEN]) }, writes);
+        };
+        // attach branch publisher
+        this.nodes[start].writers.push(branch.run(branchWriter, 
         // reader
-        (config) => ChannelRead.doRead(config, this.streamChannels ?? this.outputChannels, true)));
+        options.withReader
+            ? (config) => ChannelRead.doRead(config, this.streamChannels ?? this.outputChannels, true)
+            : undefined));
         // attach branch subscribers
         const ends = branch.ends
             ? Object.values(branch.ends)
@@ -494,3 +531,28 @@ function isStateGraphArgsWithInputOutputSchemas(obj) {
         obj.input !== undefined &&
         obj.output !== undefined);
 }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function _controlBranch(value) {
+    if (_isSend(value)) {
+        return [value];
+    }
+    if (!_isCommand(value)) {
+        return [];
+    }
+    if (value.graph === Command.PARENT) {
+        throw new ParentCommand(value);
+    }
+    return Array.isArray(value.goto) ? value.goto : [value.goto];
+}
+function _getControlBranch() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const CONTROL_BRANCH_PATH = new RunnableCallable({
+        func: _controlBranch,
+        tags: [TAG_HIDDEN],
+        trace: false,
+        recurse: false,
+    });
+    return new Branch({
+        path: CONTROL_BRANCH_PATH,
+    });
+}

package/dist/prebuilt/tool_node.cjs

@@ -4,6 +4,7 @@ exports.toolsCondition = exports.ToolNode = void 0;
 const messages_1 = require("@langchain/core/messages");
 const utils_js_1 = require("../utils.cjs");
 const graph_js_1 = require("../graph/graph.cjs");
+const errors_js_1 = require("../errors.cjs");
 /**
  * A node that runs the tools requested in the last AIMessage. It can be used
  * either in StateGraph with a "messages" key or in MessageGraph. If multiple
@@ -178,6 +179,12 @@ class ToolNode extends utils_js_1.RunnableCallable {
                 if (!this.handleToolErrors) {
                     throw e;
                 }
+                if ((0, errors_js_1.isGraphInterrupt)(e.name)) {
+                    // `NodeInterrupt` errors are a breakpoint to bring a human into the loop.
+                    // As such, they are not recoverable by the agent and shouldn't be fed
+                    // back. Instead, re-throw these errors even when `handleToolErrors = true`.
+                    throw e;
+                }
                 return new messages_1.ToolMessage({
                     content: `Error: ${e.message}\n Please fix your mistakes.`,
                     name: call.name,

package/dist/prebuilt/tool_node.js

@@ -1,6 +1,7 @@
 import { ToolMessage, isBaseMessage, } from "@langchain/core/messages";
 import { RunnableCallable } from "../utils.js";
 import { END } from "../graph/graph.js";
+import { isGraphInterrupt } from "../errors.js";
 /**
  * A node that runs the tools requested in the last AIMessage. It can be used
  * either in StateGraph with a "messages" key or in MessageGraph. If multiple
@@ -175,6 +176,12 @@ export class ToolNode extends RunnableCallable {
                 if (!this.handleToolErrors) {
                     throw e;
                 }
+                if (isGraphInterrupt(e.name)) {
+                    // `NodeInterrupt` errors are a breakpoint to bring a human into the loop.
+                    // As such, they are not recoverable by the agent and shouldn't be fed
+                    // back. Instead, re-throw these errors even when `handleToolErrors = true`.
+                    throw e;
+                }
                 return new ToolMessage({
                     content: `Error: ${e.message}\n Please fix your mistakes.`,
                     name: call.name,

package/dist/pregel/algo.cjs

@@ -100,6 +100,21 @@ const IGNORE = new Set([constants_js_1.PUSH, constants_js_1.RESUME, constants_js
 function _applyWrites(checkpoint, channels, tasks, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 getNextVersion) {
+    // Sort tasks by first 3 path elements for deterministic order
+    // Later path parts (like task IDs) are ignored for sorting
+    tasks.sort((a, b) => {
+        const aPath = a.path?.slice(0, 3) || [];
+        const bPath = b.path?.slice(0, 3) || [];
+        // Compare each path element
+        for (let i = 0; i < Math.min(aPath.length, bPath.length); i += 1) {
+            if (aPath[i] < bPath[i])
+                return -1;
+            if (aPath[i] > bPath[i])
+                return 1;
+        }
+        // If one path is shorter, it comes first
+        return aPath.length - bPath.length;
+    });
     // if no task has triggers this is applying writes from the null task only
     // so we don't do anything other than update the channels written to
     const bumpStep = tasks.some((task) => task.triggers.length > 0);
@@ -146,6 +161,7 @@ getNextVersion) {
                 // do nothing
             }
             else if (chan === constants_js_1.TASKS) {
+                // TODO: remove branch in 1.0
                 checkpoint.pending_sends.push({
                     node: val.node,
                     args: val.args,
@@ -214,6 +230,11 @@ getNextVersion) {
     return pendingWritesByManaged;
 }
 exports._applyWrites = _applyWrites;
+/**
+ * Prepare the set of tasks that will make up the next Pregel step.
+ * This is the union of all PUSH tasks (Sends) and PULL tasks (nodes triggered
+ * by edges).
+ */
 function _prepareNextTasks(checkpoint, pendingWrites, processes, channels, managed, config, forExecution, extra) {
     const tasks = {};
     // Consume pending packets
@@ -234,12 +255,18 @@ function _prepareNextTasks(checkpoint, pendingWrites, processes, channels, manag
     return tasks;
 }
 exports._prepareNextTasks = _prepareNextTasks;
+/**
+ * Prepares a single task for the next Pregel step, given a task path, which
+ * uniquely identifies a PUSH or PULL task within the graph.
+ */
 function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processes, channels, managed, config, forExecution, extra) {
     const { step, checkpointer, manager } = extra;
     const configurable = config.configurable ?? {};
     const parentNamespace = configurable.checkpoint_ns ?? "";
     if (taskPath[0] === constants_js_1.PUSH) {
-        const index = typeof taskPath[1] === "number" ? taskPath[1] : parseInt(taskPath[1], 10);
+        const index = typeof taskPath[1] === "number"
+            ? taskPath[1]
+            : parseInt(taskPath[1], 10);
         if (index >= checkpoint.pending_sends.length) {
             return undefined;
         }
@@ -302,6 +329,7 @@ function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processes, chan
                                 name: packet.node,
                                 writes: writes,
                                 triggers,
+                                path: taskPath,
                             }, select_, fresh_),
                             [constants_js_1.CONFIG_KEY_CHECKPOINTER]: checkpointer ?? configurable[constants_js_1.CONFIG_KEY_CHECKPOINTER],
                             [constants_js_1.CONFIG_KEY_CHECKPOINT_MAP]: {
@@ -319,6 +347,7 @@ function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processes, chan
                     retry_policy: proc.retryPolicy,
                     id: taskId,
                     path: taskPath,
+                    writers: proc.getWriters(),
                 };
             }
         }
@@ -405,6 +434,7 @@ function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processes, chan
                                     name,
                                     writes: writes,
                                     triggers,
+                                    path: taskPath,
                                 }, select_, fresh_),
                                 [constants_js_1.CONFIG_KEY_CHECKPOINTER]: checkpointer ?? configurable[constants_js_1.CONFIG_KEY_CHECKPOINTER],
                                 [constants_js_1.CONFIG_KEY_CHECKPOINT_MAP]: {
@@ -422,6 +452,7 @@ function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processes, chan
                         retry_policy: proc.retryPolicy,
                         id: taskId,
                         path: taskPath,
+                        writers: proc.getWriters(),
                     };
                 }
             }

package/dist/pregel/algo.d.ts

@@ -15,6 +15,7 @@ export type WritesProtocol<C = string> = {
     name: string;
     writes: PendingWrite<C>[];
     triggers: string[];
+    path?: [string, ...(string | number)[]];
 };
 export declare const increment: (current?: number) => number;
 export declare function shouldInterrupt<N extends PropertyKey, C extends PropertyKey>(checkpoint: Checkpoint, interruptNodes: All | N[], tasks: PregelExecutableTask<N, C>[]): boolean;
@@ -37,5 +38,5 @@ export type NextTaskExtraFieldsWithoutStore = NextTaskExtraFields & {
 export declare function _prepareNextTasks<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>>(checkpoint: ReadonlyCheckpoint, pendingWrites: [string, string, unknown][] | undefined, processes: Nn, channels: Cc, managed: ManagedValueMapping, config: RunnableConfig, forExecution: false, extra: NextTaskExtraFieldsWithoutStore): Record<string, PregelTaskDescription>;
 export declare function _prepareNextTasks<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>>(checkpoint: ReadonlyCheckpoint, pendingWrites: [string, string, unknown][] | undefined, processes: Nn, channels: Cc, managed: ManagedValueMapping, config: RunnableConfig, forExecution: true, extra: NextTaskExtraFieldsWithStore): Record<string, PregelExecutableTask<keyof Nn, keyof Cc>>;
 export declare function _prepareSingleTask<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>>(taskPath: [string, string | number], checkpoint: ReadonlyCheckpoint, pendingWrites: [string, string, unknown][] | undefined, processes: Nn, channels: Cc, managed: ManagedValueMapping, config: RunnableConfig, forExecution: false, extra: NextTaskExtraFields): PregelTaskDescription | undefined;
-export declare function _prepareSingleTask<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>>(taskPath: [string, string | number], checkpoint: ReadonlyCheckpoint, pendingWrites: [string, string, unknown][] | undefined, processes: Nn, channels: Cc, managed: ManagedValueMapping, config: RunnableConfig, forExecution: true, extra: NextTaskExtraFields): PregelExecutableTask<keyof Nn, keyof Cc> | undefined;
-export declare function _prepareSingleTask<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>>(taskPath: [string, string | number], checkpoint: ReadonlyCheckpoint, pendingWrites: [string, string, unknown][] | undefined, processes: Nn, channels: Cc, managed: ManagedValueMapping, config: RunnableConfig, forExecution: boolean, extra: NextTaskExtraFieldsWithStore): PregelTaskDescription | PregelExecutableTask<keyof Nn, keyof Cc> | undefined;
+export declare function _prepareSingleTask<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>>(taskPath: [string, ...(string | number)[]], checkpoint: ReadonlyCheckpoint, pendingWrites: [string, string, unknown][] | undefined, processes: Nn, channels: Cc, managed: ManagedValueMapping, config: RunnableConfig, forExecution: true, extra: NextTaskExtraFields): PregelExecutableTask<keyof Nn, keyof Cc> | undefined;
+export declare function _prepareSingleTask<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>>(taskPath: [string, ...(string | number)[]], checkpoint: ReadonlyCheckpoint, pendingWrites: [string, string, unknown][] | undefined, processes: Nn, channels: Cc, managed: ManagedValueMapping, config: RunnableConfig, forExecution: boolean, extra: NextTaskExtraFieldsWithStore): PregelTaskDescription | PregelExecutableTask<keyof Nn, keyof Cc> | undefined;

package/dist/pregel/algo.js

@@ -93,6 +93,21 @@ const IGNORE = new Set([PUSH, RESUME, INTERRUPT]);
 export function _applyWrites(checkpoint, channels, tasks, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 getNextVersion) {
+    // Sort tasks by first 3 path elements for deterministic order
+    // Later path parts (like task IDs) are ignored for sorting
+    tasks.sort((a, b) => {
+        const aPath = a.path?.slice(0, 3) || [];
+        const bPath = b.path?.slice(0, 3) || [];
+        // Compare each path element
+        for (let i = 0; i < Math.min(aPath.length, bPath.length); i += 1) {
+            if (aPath[i] < bPath[i])
+                return -1;
+            if (aPath[i] > bPath[i])
+                return 1;
+        }
+        // If one path is shorter, it comes first
+        return aPath.length - bPath.length;
+    });
     // if no task has triggers this is applying writes from the null task only
     // so we don't do anything other than update the channels written to
     const bumpStep = tasks.some((task) => task.triggers.length > 0);
@@ -139,6 +154,7 @@ getNextVersion) {
                 // do nothing
             }
             else if (chan === TASKS) {
+                // TODO: remove branch in 1.0
                 checkpoint.pending_sends.push({
                     node: val.node,
                     args: val.args,
@@ -206,6 +222,11 @@ getNextVersion) {
     // Return managed values writes to be applied externally
     return pendingWritesByManaged;
 }
+/**
+ * Prepare the set of tasks that will make up the next Pregel step.
+ * This is the union of all PUSH tasks (Sends) and PULL tasks (nodes triggered
+ * by edges).
+ */
 export function _prepareNextTasks(checkpoint, pendingWrites, processes, channels, managed, config, forExecution, extra) {
     const tasks = {};
     // Consume pending packets
@@ -225,12 +246,18 @@ export function _prepareNextTasks(checkpoint, pendingWrites, processes, channels
     }
     return tasks;
 }
+/**
+ * Prepares a single task for the next Pregel step, given a task path, which
+ * uniquely identifies a PUSH or PULL task within the graph.
+ */
 export function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processes, channels, managed, config, forExecution, extra) {
     const { step, checkpointer, manager } = extra;
     const configurable = config.configurable ?? {};
     const parentNamespace = configurable.checkpoint_ns ?? "";
     if (taskPath[0] === PUSH) {
-        const index = typeof taskPath[1] === "number" ? taskPath[1] : parseInt(taskPath[1], 10);
+        const index = typeof taskPath[1] === "number"
+            ? taskPath[1]
+            : parseInt(taskPath[1], 10);
         if (index >= checkpoint.pending_sends.length) {
             return undefined;
         }
@@ -293,6 +320,7 @@ export function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processe
                                 name: packet.node,
                                 writes: writes,
                                 triggers,
+                                path: taskPath,
                             }, select_, fresh_),
                             [CONFIG_KEY_CHECKPOINTER]: checkpointer ?? configurable[CONFIG_KEY_CHECKPOINTER],
                             [CONFIG_KEY_CHECKPOINT_MAP]: {
@@ -310,6 +338,7 @@ export function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processe
                     retry_policy: proc.retryPolicy,
                     id: taskId,
                     path: taskPath,
+                    writers: proc.getWriters(),
                 };
             }
         }
@@ -396,6 +425,7 @@ export function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processe
                                     name,
                                     writes: writes,
                                     triggers,
+                                    path: taskPath,
                                 }, select_, fresh_),
                                 [CONFIG_KEY_CHECKPOINTER]: checkpointer ?? configurable[CONFIG_KEY_CHECKPOINTER],
                                 [CONFIG_KEY_CHECKPOINT_MAP]: {
@@ -413,6 +443,7 @@ export function _prepareSingleTask(taskPath, checkpoint, pendingWrites, processe
                         retry_policy: proc.retryPolicy,
                         id: taskId,
                         path: taskPath,
+                        writers: proc.getWriters(),
                     };
                 }
             }

package/dist/pregel/index.cjs

@@ -602,6 +602,7 @@ class Pregel extends runnables_1.Runnable {
             writes: [],
             triggers: [constants_js_1.INTERRUPT],
             id: (0, langgraph_checkpoint_1.uuid5)(constants_js_1.INTERRUPT, checkpoint.id),
+            writers: [],
         };
         // execute task
         await task.proc.invoke(task.input, (0, runnables_1.patchConfig)({
@@ -617,8 +618,15 @@ class Pregel extends runnables_1.Runnable {
             },
         }));
         // save task writes
-        if (saved !== undefined) {
-            await checkpointer.putWrites(checkpointConfig, task.writes, task.id);
+        // channel writes are saved to current checkpoint
+        // push writes are saved to next checkpoint
+        const [channelWrites, pushWrites] = [
+            task.writes.filter((w) => w[0] !== constants_js_1.PUSH),
+            task.writes.filter((w) => w[0] === constants_js_1.PUSH),
+        ];
+        // save task writes
+        if (saved !== undefined && channelWrites.length > 0) {
+            await checkpointer.putWrites(checkpointConfig, channelWrites, task.id);
         }
         // apply to checkpoint
         // TODO: Why does keyof StrRecord allow number and symbol?
@@ -630,6 +638,9 @@ class Pregel extends runnables_1.Runnable {
             writes: { [asNode]: values },
             parents: saved?.metadata?.parents ?? {},
         }, newVersions);
+        if (pushWrites.length > 0) {
+            await checkpointer.putWrites(nextConfig, pushWrites, task.id);
+        }
         return (0, index_js_1.patchCheckpointMap)(nextConfig, saved ? saved.metadata : undefined);
     }
     _defaults(config) {

package/dist/pregel/index.js

@@ -7,7 +7,7 @@ import { validateGraph, validateKeys } from "./validate.js";
 import { readChannels } from "./io.js";
 import { printStepCheckpoint, printStepTasks, printStepWrites, tasksWithWrites, } from "./debug.js";
 import { ChannelWrite, PASSTHROUGH } from "./write.js";
-import { CONFIG_KEY_CHECKPOINTER, CONFIG_KEY_READ, CONFIG_KEY_SEND, ERROR, INTERRUPT, CHECKPOINT_NAMESPACE_SEPARATOR, CHECKPOINT_NAMESPACE_END, CONFIG_KEY_STREAM, CONFIG_KEY_TASK_ID, NULL_TASK_ID, INPUT, } from "../constants.js";
+import { CONFIG_KEY_CHECKPOINTER, CONFIG_KEY_READ, CONFIG_KEY_SEND, ERROR, INTERRUPT, CHECKPOINT_NAMESPACE_SEPARATOR, CHECKPOINT_NAMESPACE_END, CONFIG_KEY_STREAM, CONFIG_KEY_TASK_ID, NULL_TASK_ID, INPUT, PUSH, } from "../constants.js";
 import { GraphRecursionError, GraphValueError, InvalidUpdateError, isGraphBubbleUp, isGraphInterrupt, } from "../errors.js";
 import { _prepareNextTasks, _localRead, _applyWrites, } from "./algo.js";
 import { _coerceToDict, getNewChannelVersions, patchCheckpointMap, } from "./utils/index.js";
@@ -598,6 +598,7 @@ export class Pregel extends Runnable {
             writes: [],
             triggers: [INTERRUPT],
             id: uuid5(INTERRUPT, checkpoint.id),
+            writers: [],
         };
         // execute task
         await task.proc.invoke(task.input, patchConfig({
@@ -613,8 +614,15 @@ export class Pregel extends Runnable {
             },
         }));
         // save task writes
-        if (saved !== undefined) {
-            await checkpointer.putWrites(checkpointConfig, task.writes, task.id);
+        // channel writes are saved to current checkpoint
+        // push writes are saved to next checkpoint
+        const [channelWrites, pushWrites] = [
+            task.writes.filter((w) => w[0] !== PUSH),
+            task.writes.filter((w) => w[0] === PUSH),
+        ];
+        // save task writes
+        if (saved !== undefined && channelWrites.length > 0) {
+            await checkpointer.putWrites(checkpointConfig, channelWrites, task.id);
         }
         // apply to checkpoint
         // TODO: Why does keyof StrRecord allow number and symbol?
@@ -626,6 +634,9 @@ export class Pregel extends Runnable {
             writes: { [asNode]: values },
             parents: saved?.metadata?.parents ?? {},
         }, newVersions);
+        if (pushWrites.length > 0) {
+            await checkpointer.putWrites(nextConfig, pushWrites, task.id);
+        }
         return patchCheckpointMap(nextConfig, saved ? saved.metadata : undefined);
     }
     _defaults(config) {