@langchain/langgraph 1.3.7 → 1.4.1

package/dist/graph/state.cjs

@@ -1,3 +1,4 @@
+const require_timeout = require("../pregel/utils/timeout.cjs");
 const require_constants = require("../constants.cjs");
 const require_errors = require("../errors.cjs");
 const require_last_value = require("../channels/last_value.cjs");
@@ -5,6 +6,7 @@ const require_annotation = require("./annotation.cjs");
 const require_utils = require("../utils.cjs");
 const require_write = require("../pregel/write.cjs");
 const require_read = require("../pregel/read.cjs");
+require("../pregel/utils/index.cjs");
 const require_subgraph = require("../pregel/utils/subgraph.cjs");
 const require_ephemeral_value = require("../channels/ephemeral_value.cjs");
 const require_graph = require("./graph.cjs");
@@ -17,6 +19,14 @@ let _langchain_core_runnables = require("@langchain/core/runnables");
 let _langchain_core_utils_types = require("@langchain/core/utils/types");
 //#region src/graph/state.ts
 const ROOT = "__root__";
+/**
+* Reserved node name for the single shared error handler that is materialized
+* when a graph-wide default error handler is set via
+* {@link StateGraph.setNodeDefaults}. Every regular node that lacks its own
+* `errorHandler` routes failures to this node. Mirrors Python's
+* `__default_error_handler__`.
+*/
+const DEFAULT_ERROR_HANDLER_NODE = "__default_error_handler__";
 const PartialStateSchema = Symbol.for("langgraph.state.partial");
 /**
 * A graph whose nodes communicate by reading and writing to a shared state.
@@ -140,6 +150,11 @@ var StateGraph = class extends require_graph.Graph {
 	_interrupt;
 	/** @internal */
 	_writer;
+	/**
+	* Graph-wide default node policies, resolved at `compile()` time.
+	* @internal
+	*/
+	_nodeDefaults = {};
 	constructor(stateOrInit, options) {
 		super();
 		const init = this._normalizeToStateGraphInit(stateOrInit, options);
@@ -171,6 +186,89 @@ var StateGraph = class extends require_graph.Graph {
 		this._writer = init.writer;
 	}
 	/**
+	* Set graph-wide default node policies that apply to every node in this
+	* graph.
+	*
+	* Per-node values passed to {@link addNode} always take precedence over these
+	* defaults. Defaults are resolved at {@link compile} time, so call order does
+	* not matter — you may call this before or after `addNode`, including as the
+	* last step before `compile()`. Calling it multiple times merges the provided
+	* fields, with later calls overriding earlier ones on a per-field basis.
+	*
+	* Policies set here are **not** inherited by subgraphs.
+	*
+	* `retryPolicy` and `timeout` defaults apply to **all** nodes, including
+	* auto-generated error-handler nodes. `cachePolicy` and `errorHandler`
+	* defaults apply to **regular nodes only** — caching an error-handler result
+	* is unsafe, and a handler must never catch its own (or another handler's)
+	* failure.
+	*
+	* @param defaults - The default node policies to apply.
+	* @returns The builder instance, for chaining.
+	*
+	* @example Call before `addNode`
+	* ```ts
+	* const graph = new StateGraph(State)
+	*   .setNodeDefaults({
+	*     retryPolicy: { maxAttempts: 3 },
+	*     cachePolicy: { ttl: 60 },
+	*     timeout: 60_000,
+	*     errorHandler: (state, { node, error }) => ({ lastError: error.message }),
+	*   })
+	*   .addNode("a", nodeA)
+	*   .addNode("b", nodeB, { retryPolicy: { maxAttempts: 5 } }) // overrides default
+	*   .addEdge(START, "a")
+	*   .compile();
+	* ```
+	*
+	* @example Call after `addNode`, immediately before `compile()`
+	* ```ts
+	* const graph = new StateGraph(State)
+	*   .addNode("a", nodeA)
+	*   .addNode("b", nodeB, { retryPolicy: { maxAttempts: 5 } }) // overrides default
+	*   .addEdge(START, "a")
+	*   .setNodeDefaults({
+	*     retryPolicy: { maxAttempts: 3 },
+	*     cachePolicy: { ttl: 60 },
+	*   })
+	*   .compile();
+	* ```
+	*/
+	setNodeDefaults(defaults) {
+		if (defaults.retryPolicy !== void 0) this._nodeDefaults.retryPolicy = defaults.retryPolicy;
+		if (defaults.cachePolicy !== void 0) this._nodeDefaults.cachePolicy = typeof defaults.cachePolicy === "boolean" ? defaults.cachePolicy ? {} : void 0 : defaults.cachePolicy;
+		if (defaults.timeout !== void 0) this._nodeDefaults.timeout = require_timeout.coerceTimeoutPolicy(defaults.timeout);
+		if (defaults.errorHandler !== void 0) this._nodeDefaults.errorHandler = defaults.errorHandler;
+		return this;
+	}
+	/**
+	* Build the shared spec for a graph-wide default error handler, or
+	* `undefined` when {@link setNodeDefaults} did not configure one. The spec is
+	* installed under {@link DEFAULT_ERROR_HANDLER_NODE} for the duration of a
+	* single {@link compile} call and routes failures from every regular node
+	* that lacks its own handler.
+	* @internal
+	*/
+	_createDefaultErrorHandlerSpec() {
+		const userHandler = this._nodeDefaults.errorHandler;
+		if (userHandler === void 0) return;
+		return {
+			runnable: new require_utils.RunnableCallable({
+				func: (state, config) => {
+					const nodeError = config?.configurable?.[require_constants.CONFIG_KEY_NODE_ERROR];
+					return userHandler(state, nodeError, config);
+				},
+				name: DEFAULT_ERROR_HANDLER_NODE,
+				trace: false
+			}),
+			metadata: void 0,
+			input: this._schemaDefinition,
+			retryPolicy: void 0,
+			cachePolicy: void 0,
+			isErrorHandler: true
+		};
+	}
+	/**
 	* Normalize all constructor input patterns to a unified StateGraphInit object.
 	* @internal
 	*/
@@ -265,17 +363,42 @@ var StateGraph = class extends require_graph.Graph {
 				trace: false
 			});
 			else runnable = (0, _langchain_core_runnables._coerceToRunnable)(action);
-			let cachePolicy = options?.cachePolicy;
-			if (typeof cachePolicy === "boolean") cachePolicy = cachePolicy ? {} : void 0;
+			const rawCachePolicy = options?.cachePolicy;
+			let cachePolicy;
+			if (rawCachePolicy !== void 0) cachePolicy = typeof rawCachePolicy === "boolean" ? rawCachePolicy ? {} : false : rawCachePolicy;
+			let errorHandlerNode;
+			if (options?.errorHandler !== void 0) {
+				errorHandlerNode = `__error_handler__${key}`;
+				if (errorHandlerNode in this.nodes) throw new Error(`Cannot add error handler to node \`${key}\`: the reserved name \`${errorHandlerNode}\` is already in use. StateGraph registers \`__error_handler__<nodeName>\` when you pass \`errorHandler\` in addNode options. Remove or rename the existing node with that name (for example, you may have added it manually).`);
+				const userHandler = options.errorHandler;
+				const handlerSpec = {
+					runnable: new require_utils.RunnableCallable({
+						func: (state, config) => {
+							const nodeError = config?.configurable?.[require_constants.CONFIG_KEY_NODE_ERROR];
+							return userHandler(state, nodeError, config);
+						},
+						name: errorHandlerNode,
+						trace: false
+					}),
+					metadata: void 0,
+					input: inputSpec ?? this._schemaDefinition,
+					retryPolicy: void 0,
+					cachePolicy: void 0,
+					isErrorHandler: true
+				};
+				this.nodes[errorHandlerNode] = handlerSpec;
+			}
 			const nodeSpec = {
 				runnable,
 				retryPolicy: options?.retryPolicy,
 				cachePolicy,
+				timeout: require_timeout.coerceTimeoutPolicy(options?.timeout),
 				metadata: options?.metadata,
 				input: inputSpec ?? this._schemaDefinition,
 				subgraphs: require_subgraph.isPregelLike(runnable) ? [runnable] : options?.subgraphs,
 				ends: options?.ends,
-				defer: options?.defer
+				defer: options?.defer,
+				errorHandlerNode
 			};
 			this.nodes[key] = nodeSpec;
 		}
@@ -300,13 +423,36 @@ var StateGraph = class extends require_graph.Graph {
 		for (const [key, action, options] of parsedNodes) {
 			if (key in this.nodes) throw new Error(`Node names must be unique: node with the name "${key}" already exists.`);
 			const validKey = key;
-			this.addNode(validKey, action, options);
+			this.addNode(key, action, options);
 			if (previousNode != null) this.addEdge(previousNode, validKey);
 			previousNode = validKey;
 		}
 		return this;
 	}
 	compile({ checkpointer, store, cache, interruptBefore, interruptAfter, name, description, transformers } = {}) {
+		const defaultErrorHandlerSpec = this._createDefaultErrorHandlerSpec();
+		if (defaultErrorHandlerSpec !== void 0) {
+			if (DEFAULT_ERROR_HANDLER_NODE in this.nodes) throw new Error(`Cannot apply a default error handler: the reserved node name \`${DEFAULT_ERROR_HANDLER_NODE}\` is already in use. setNodeDefaults({ errorHandler }) registers a node with that name; rename the conflicting node.`);
+			this.nodes[DEFAULT_ERROR_HANDLER_NODE] = defaultErrorHandlerSpec;
+		}
+		try {
+			return this._compileResolved({
+				checkpointer,
+				store,
+				cache,
+				interruptBefore,
+				interruptAfter,
+				name,
+				description,
+				transformers,
+				defaultErrorHandlerNode: defaultErrorHandlerSpec !== void 0 ? DEFAULT_ERROR_HANDLER_NODE : void 0
+			});
+		} finally {
+			if (defaultErrorHandlerSpec !== void 0) delete this.nodes[DEFAULT_ERROR_HANDLER_NODE];
+		}
+	}
+	/** @internal */
+	_compileResolved({ checkpointer, store, cache, interruptBefore, interruptAfter, name, description, transformers, defaultErrorHandlerNode }) {
 		this.validate([...Array.isArray(interruptBefore) ? interruptBefore : [], ...Array.isArray(interruptAfter) ? interruptAfter : []]);
 		const outputKeys = Object.keys(this._schemaDefinitions.get(this._outputDefinition));
 		const outputChannels = outputKeys.length === 1 && outputKeys[0] === ROOT ? ROOT : outputKeys;
@@ -336,7 +482,19 @@ var StateGraph = class extends require_graph.Graph {
 			streamTransformers: transformers
 		});
 		compiled.attachNode(require_constants.START);
-		for (const [key, node] of Object.entries(this.nodes)) compiled.attachNode(key, node);
+		const nodeDefaults = this._nodeDefaults;
+		const hasNodeDefaults = nodeDefaults.retryPolicy !== void 0 || nodeDefaults.cachePolicy !== void 0 || nodeDefaults.timeout !== void 0 || defaultErrorHandlerNode !== void 0;
+		for (const [key, node] of Object.entries(this.nodes)) {
+			const isErrorHandlerNode = node.isErrorHandler === true;
+			const resolvedNode = hasNodeDefaults ? {
+				...node,
+				retryPolicy: node.retryPolicy ?? nodeDefaults.retryPolicy,
+				cachePolicy: isErrorHandlerNode ? void 0 : node.cachePolicy === false ? void 0 : node.cachePolicy ?? nodeDefaults.cachePolicy,
+				timeout: node.timeout ?? nodeDefaults.timeout,
+				errorHandlerNode: !isErrorHandlerNode && defaultErrorHandlerNode !== void 0 && node.errorHandlerNode === void 0 ? defaultErrorHandlerNode : node.errorHandlerNode
+			} : node;
+			compiled.attachNode(key, resolvedNode);
+		}
 		compiled.attachBranch(require_constants.START, require_constants.SELF, _getControlBranch(), { withReader: false });
 		for (const [key] of Object.entries(this.nodes)) compiled.attachBranch(key, require_constants.SELF, _getControlBranch(), { withReader: false });
 		for (const [start, end] of this.edges) compiled.attachEdge(start, end);
@@ -384,6 +542,10 @@ function _getChannels(schema) {
 *
 * @typeParam WriterType - The type for custom stream writers. Used with the `writer`
 *   option to enable typed custom streaming from within nodes.
+*
+* @typeParam TStreamTransformers - Stream transformer factories registered at
+*   compile time via the `transformers` option. Used to type extensions on
+*   `streamEvents(..., { version: "v3" })`.
 */
 var CompiledStateGraph = class extends require_graph.CompiledGraph {
 	/**
@@ -416,22 +578,51 @@ var CompiledStateGraph = class extends require_graph.CompiledGraph {
 			return null;
 		}
 		const nodeKey = key;
-		function _getUpdates(input) {
+		const validateStateUpdates = async (updates) => {
+			if (updates == null || updates.length === 0) return updates;
+			const schemaDef = this.builder._schemaRuntimeDefinition;
+			if (require_schema.StateSchema.isInstance(schemaDef)) {
+				const schemaKeys = new Set(schemaDef.getChannelKeys());
+				return Promise.all(updates.map(async ([k, v]) => {
+					if (!schemaKeys.has(k)) return [k, v];
+					const parsed = await schemaDef.validateInput({ [k]: v });
+					return [k, Object.prototype.hasOwnProperty.call(parsed, k) ? parsed[k] : v];
+				}));
+			}
+			if ((0, _langchain_core_utils_types.isInteropZodObject)(schemaDef)) {
+				const schemaKeys = new Set(Object.keys((0, _langchain_core_utils_types.getInteropZodObjectShape)(schemaDef)));
+				if (updates.filter(([k]) => schemaKeys.has(k)).length === 0) return updates;
+				const updateSchema = (0, _langchain_core_utils_types.interopZodObjectPartial)(this._metaRegistry.getExtendedChannelSchemas(schemaDef, { withReducerSchema: true }));
+				const valueSchema = (0, _langchain_core_utils_types.interopZodObjectPartial)(schemaDef);
+				return updates.map(([k, v]) => {
+					if (!schemaKeys.has(k)) return [k, v];
+					const [isOverwrite, overwriteValue] = require_constants._getOverwriteValue(v);
+					if (isOverwrite) {
+						const parsed = (0, _langchain_core_utils_types.interopParse)(valueSchema, { [k]: overwriteValue });
+						return [k, Object.prototype.hasOwnProperty.call(parsed, k) ? { [require_constants.OVERWRITE]: parsed[k] } : v];
+					}
+					const parsed = (0, _langchain_core_utils_types.interopParse)(updateSchema, { [k]: v });
+					return [k, Object.prototype.hasOwnProperty.call(parsed, k) ? parsed[k] : v];
+				});
+			}
+			return updates;
+		};
+		async function _getUpdates(input) {
 			if (!input) return null;
 			else if (require_constants.isCommand(input)) {
 				if (input.graph === require_constants.Command.PARENT) return null;
-				return input._updateAsTuples().filter(([k]) => outputKeys.includes(k));
+				return validateStateUpdates(input._updateAsTuples().filter(([k]) => outputKeys.includes(k)));
 			} else if (Array.isArray(input) && input.length > 0 && input.some(require_constants.isCommand)) {
 				const updates = [];
 				for (const item of input) if (require_constants.isCommand(item)) {
 					if (item.graph === require_constants.Command.PARENT) continue;
 					updates.push(...item._updateAsTuples().filter(([k]) => outputKeys.includes(k)));
 				} else {
-					const itemUpdates = _getUpdates(item);
+					const itemUpdates = await _getUpdates(item);
 					if (itemUpdates) updates.push(...itemUpdates ?? []);
 				}
-				return updates;
-			} else if (typeof input === "object" && !Array.isArray(input)) return Object.entries(input).filter(([k]) => outputKeys.includes(k));
+				return validateStateUpdates(updates);
+			} else if (typeof input === "object" && !Array.isArray(input)) return validateStateUpdates(Object.entries(input).filter(([k]) => outputKeys.includes(k)));
 			else {
 				const typeofInput = Array.isArray(input) ? "array" : typeof input;
 				throw new require_errors.InvalidUpdateError(`Expected node "${nodeKey.toString()}" to return an object or an array containing at least one Command object, received ${typeofInput}`, { lc_error_code: "INVALID_GRAPH_NODE_RETURN_VALUE" });
@@ -457,6 +648,8 @@ var CompiledStateGraph = class extends require_graph.CompiledGraph {
 			const isSingleInput = Object.keys(inputValues).length === 1 && ROOT in inputValues;
 			const branchChannel = `branch:to:${key}`;
 			this.channels[branchChannel] = node?.defer ? new require_last_value.LastValueAfterFinish() : new require_ephemeral_value.EphemeralValue(false);
+			const nodeCachePolicy = node?.cachePolicy;
+			const cachePolicy = nodeCachePolicy === false ? void 0 : nodeCachePolicy;
 			this.nodes[key] = new require_read.PregelNode({
 				triggers: [branchChannel],
 				channels: isSingleInput ? Object.keys(inputValues) : inputValues,
@@ -467,9 +660,12 @@ var CompiledStateGraph = class extends require_graph.CompiledGraph {
 				bound: node?.runnable,
 				metadata: node?.metadata,
 				retryPolicy: node?.retryPolicy,
-				cachePolicy: node?.cachePolicy,
+				cachePolicy,
+				timeout: node?.timeout,
 				subgraphs: node?.subgraphs,
-				ends: node?.ends
+				ends: node?.ends,
+				isErrorHandler: node?.isErrorHandler,
+				errorHandlerNode: node?.errorHandlerNode
 			});
 		}
 	}