@langchain/langgraph 1.3.6 → 1.4.0

package/dist/errors.cjs

@@ -32,6 +32,27 @@ var GraphValueError = class extends BaseLangGraphError {
 		return "GraphValueError";
 	}
 };
+/**
+* Raised when a graph run exits early due to a drain request.
+*
+* This indicates the graph stopped cooperatively at a superstep boundary
+* because {@link RunControl#requestDrain} was called (e.g., in response to
+* SIGTERM). The checkpoint is saved and the run can be resumed later.
+*/
+var GraphDrained = class extends GraphBubbleUp {
+	reason;
+	constructor(reason = "shutdown", fields) {
+		super(`Graph drained: ${reason}`, fields);
+		this.name = "GraphDrained";
+		this.reason = reason;
+	}
+	static get unminifiable_name() {
+		return "GraphDrained";
+	}
+};
+function isGraphDrained(e) {
+	return e !== void 0 && e.name === GraphDrained.unminifiable_name;
+}
 var GraphInterrupt = class extends GraphBubbleUp {
 	interrupts;
 	constructor(interrupts, fields) {
@@ -53,6 +74,47 @@ var NodeInterrupt = class extends GraphInterrupt {
 		return "NodeInterrupt";
 	}
 };
+/**
+* Failure context passed to a node-level error handler.
+*
+* A node-level error handler is registered via
+* `StateGraph.addNode(name, fn, { errorHandler })`. The handler runs ONLY after
+* the failing node's {@link RetryPolicy} is exhausted, so retry and handling
+* stay decoupled. The handler receives the failed node's name and the thrown
+* error via a `NodeError` instance, can return a state update, and can route to
+* a recovery branch via `new Command({ goto })` (saga / compensation flows).
+*
+* @example
+* ```ts
+* import { NodeError } from "@langchain/langgraph";
+*
+* function handler(state: State, error: NodeError) {
+*   return new Command({
+*     update: { status: `recovered from ${error.node}: ${error.error.message}` },
+*     goto: "finalize",
+*   });
+* }
+* ```
+*/
+var NodeError = class {
+	/** Name of the node whose execution failed. */
+	node;
+	/** Error thrown by the failed node. */
+	error;
+	constructor(node, error) {
+		this.node = node;
+		this.error = error;
+	}
+	static get unminifiable_name() {
+		return "NodeError";
+	}
+};
+/**
+* Type guard that checks whether a value is a {@link NodeError}.
+*/
+function isNodeError(e) {
+	return e != null && typeof e === "object" && e.constructor != null && e.constructor.unminifiable_name === NodeError.unminifiable_name;
+}
 var ParentCommand = class extends GraphBubbleUp {
 	command;
 	constructor(command) {
@@ -73,6 +135,63 @@ function isGraphBubbleUp(e) {
 function isGraphInterrupt(e) {
 	return e !== void 0 && [GraphInterrupt.unminifiable_name, NodeInterrupt.unminifiable_name].includes(e.name);
 }
+/**
+* Raised when a node invocation exceeds one of its configured timeouts.
+*
+* Does **not** extend {@link GraphBubbleUp} (so it flows through the normal node
+* error path) and is intentionally treated as retryable by the default retry
+* policy — its message/name do not match the default `retryOn` blocklist, so a
+* configured {@link RetryPolicy} will retry it (see langchain-ai/langgraph#7659).
+*
+* Both {@link NodeTimeoutError.runTimeout} and {@link NodeTimeoutError.idleTimeout}
+* reflect the configured policy at the time of the failure (each `undefined` if
+* not configured). {@link NodeTimeoutError.kind} and {@link NodeTimeoutError.timeout}
+* identify which one fired.
+*
+* @category Errors
+*/
+var NodeTimeoutError = class extends BaseLangGraphError {
+	/** Name of the node/task that timed out. */
+	node;
+	/** Which timeout fired: a hard `"run"` cap or a progress-resetting `"idle"` cap. */
+	kind;
+	/** The value (ms) of the timeout that fired (`runTimeout` or `idleTimeout`). */
+	timeout;
+	/** Elapsed time (ms) since the attempt started, at the moment the timeout fired. */
+	elapsed;
+	/** Configured run timeout (ms), if any. */
+	runTimeout;
+	/** Configured idle timeout (ms), if any. */
+	idleTimeout;
+	constructor(fields, errorFields) {
+		const { node, elapsed, kind, runTimeout, idleTimeout } = fields;
+		let message;
+		let timeout;
+		if (kind === "idle") {
+			if (idleTimeout === void 0) throw new Error("idleTimeout is required when kind='idle'");
+			timeout = idleTimeout;
+			message = `Node "${node}" exceeded its idle timeout of ${idleTimeout}ms without making progress (elapsed: ${elapsed}ms).`;
+		} else {
+			if (runTimeout === void 0) throw new Error("runTimeout is required when kind='run'");
+			timeout = runTimeout;
+			message = `Node "${node}" exceeded its run timeout of ${runTimeout}ms (elapsed: ${elapsed}ms).`;
+		}
+		super(message, errorFields);
+		this.name = "NodeTimeoutError";
+		this.node = node;
+		this.kind = kind;
+		this.timeout = timeout;
+		this.elapsed = elapsed;
+		this.runTimeout = runTimeout;
+		this.idleTimeout = idleTimeout;
+	}
+	static get unminifiable_name() {
+		return "NodeTimeoutError";
+	}
+};
+function isNodeTimeoutError(e) {
+	return e !== void 0 && e.name === NodeTimeoutError.unminifiable_name;
+}
 var EmptyInputError = class extends BaseLangGraphError {
 	constructor(message, fields) {
 		super(message, fields);
@@ -84,7 +203,10 @@ var EmptyInputError = class extends BaseLangGraphError {
 };
 var EmptyChannelError = class extends BaseLangGraphError {
 	constructor(message, fields) {
+		const prevLimit = Error.stackTraceLimit;
+		Error.stackTraceLimit = 0;
 		super(message, fields);
+		Error.stackTraceLimit = prevLimit;
 		this.name = "EmptyChannelError";
 	}
 	static get unminifiable_name() {
@@ -180,19 +302,25 @@ exports.BaseLangGraphError = BaseLangGraphError;
 exports.EmptyChannelError = EmptyChannelError;
 exports.EmptyInputError = EmptyInputError;
 exports.GraphBubbleUp = GraphBubbleUp;
+exports.GraphDrained = GraphDrained;
 exports.GraphInterrupt = GraphInterrupt;
 exports.GraphRecursionError = GraphRecursionError;
 exports.GraphValueError = GraphValueError;
 exports.InvalidUpdateError = InvalidUpdateError;
 exports.MultipleSubgraphsError = MultipleSubgraphsError;
+exports.NodeError = NodeError;
 exports.NodeInterrupt = NodeInterrupt;
+exports.NodeTimeoutError = NodeTimeoutError;
 exports.ParentCommand = ParentCommand;
 exports.RemoteException = RemoteException;
 exports.StateGraphInputError = StateGraphInputError;
 exports.UnreachableNodeError = UnreachableNodeError;
 exports.getSubgraphsSeenSet = getSubgraphsSeenSet;
 exports.isGraphBubbleUp = isGraphBubbleUp;
+exports.isGraphDrained = isGraphDrained;
 exports.isGraphInterrupt = isGraphInterrupt;
+exports.isNodeError = isNodeError;
+exports.isNodeTimeoutError = isNodeTimeoutError;
 exports.isParentCommand = isParentCommand;
 
 //# sourceMappingURL=errors.cjs.map

package/dist/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { Command, Interrupt } from \"./constants.js\";\n\n// When editing, make sure to update the index found here:\n// https://langchain-ai.github.io/langgraphjs/troubleshooting/errors/\nexport type BaseLangGraphErrorFields = {\n  lc_error_code?:\n    | \"GRAPH_RECURSION_LIMIT\"\n    | \"INVALID_CONCURRENT_GRAPH_UPDATE\"\n    | \"INVALID_GRAPH_NODE_RETURN_VALUE\"\n    | \"MISSING_CHECKPOINTER\"\n    | \"MULTIPLE_SUBGRAPHS\"\n    | \"UNREACHABLE_NODE\";\n};\n\n// TODO: Merge with base LangChain error class when we drop support for core@0.2.0\n/** @category Errors */\nexport class BaseLangGraphError extends Error {\n  lc_error_code?: string;\n\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    let finalMessage = message ?? \"\";\n    if (fields?.lc_error_code) {\n      finalMessage = `${finalMessage}\\n\\nTroubleshooting URL: https://docs.langchain.com/oss/javascript/langgraph/${fields.lc_error_code}/\\n`;\n    }\n    super(finalMessage);\n    this.lc_error_code = fields?.lc_error_code;\n  }\n}\n\nexport class GraphBubbleUp extends BaseLangGraphError {\n  get is_bubble_up() {\n    return true;\n  }\n}\n\nexport class GraphRecursionError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"GraphRecursionError\";\n  }\n\n  static get unminifiable_name() {\n    return \"GraphRecursionError\";\n  }\n}\n\nexport class GraphValueError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"GraphValueError\";\n  }\n\n  static get unminifiable_name() {\n    return \"GraphValueError\";\n  }\n}\n\nexport class GraphInterrupt extends GraphBubbleUp {\n  interrupts: Interrupt[];\n\n  constructor(interrupts?: Interrupt[], fields?: BaseLangGraphErrorFields) {\n    super(JSON.stringify(interrupts, null, 2), fields);\n    this.name = \"GraphInterrupt\";\n    this.interrupts = interrupts ?? [];\n  }\n\n  static get unminifiable_name() {\n    return \"GraphInterrupt\";\n  }\n}\n\n/** Raised by a node to interrupt execution. */\nexport class NodeInterrupt extends GraphInterrupt {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  constructor(message: any, fields?: BaseLangGraphErrorFields) {\n    super([{ value: message }], fields);\n    this.name = \"NodeInterrupt\";\n  }\n\n  static get unminifiable_name() {\n    return \"NodeInterrupt\";\n  }\n}\n\nexport class ParentCommand extends GraphBubbleUp {\n  command: Command;\n\n  constructor(command: Command) {\n    super();\n    this.name = \"ParentCommand\";\n    this.command = command;\n  }\n\n  static get unminifiable_name() {\n    return \"ParentCommand\";\n  }\n}\n\nexport function isParentCommand(e?: unknown): e is ParentCommand {\n  return (\n    e !== undefined &&\n    (e as ParentCommand).name === ParentCommand.unminifiable_name\n  );\n}\n\nexport function isGraphBubbleUp(e?: unknown): e is GraphBubbleUp {\n  return e !== undefined && (e as GraphBubbleUp).is_bubble_up === true;\n}\n\nexport function isGraphInterrupt(e?: unknown): e is GraphInterrupt {\n  return (\n    e !== undefined &&\n    [\n      GraphInterrupt.unminifiable_name,\n      NodeInterrupt.unminifiable_name,\n    ].includes((e as Error).name)\n  );\n}\n\nexport class EmptyInputError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"EmptyInputError\";\n  }\n\n  static get unminifiable_name() {\n    return \"EmptyInputError\";\n  }\n}\n\nexport class EmptyChannelError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"EmptyChannelError\";\n  }\n\n  static get unminifiable_name() {\n    return \"EmptyChannelError\";\n  }\n}\n\nexport class InvalidUpdateError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"InvalidUpdateError\";\n  }\n\n  static get unminifiable_name() {\n    return \"InvalidUpdateError\";\n  }\n}\n\n/**\n * @deprecated This exception type is no longer thrown.\n */\nexport class MultipleSubgraphsError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"MultipleSubgraphError\";\n  }\n\n  static get unminifiable_name() {\n    return \"MultipleSubgraphError\";\n  }\n}\n\nexport class UnreachableNodeError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"UnreachableNodeError\";\n  }\n\n  static get unminifiable_name() {\n    return \"UnreachableNodeError\";\n  }\n}\n\n/**\n * Exception raised when an error occurs in the remote graph.\n */\nexport class RemoteException extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"RemoteException\";\n  }\n\n  static get unminifiable_name() {\n    return \"RemoteException\";\n  }\n}\n\n/**\n * Error thrown when invalid input is provided to a StateGraph.\n *\n * This typically means that the input to the StateGraph constructor or builder\n * did not match the required types. A valid input should be a\n * StateDefinition, an Annotation.Root, or a Zod schema.\n *\n * @example\n * // Example of incorrect usage:\n * try {\n *   new StateGraph({ foo: \"bar\" }); // Not a valid input\n * } catch (err) {\n *   if (err instanceof StateGraphInputError) {\n *     console.error(err.message);\n *   }\n * }\n */\nexport class StateGraphInputError extends BaseLangGraphError {\n  /**\n   * Create a new StateGraphInputError.\n   * @param message - Optional custom error message.\n   * @param fields - Optional additional error fields.\n   */\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"StateGraphInputError\";\n    this.message =\n      \"Invalid StateGraph input. Make sure to pass a valid StateDefinition, Annotation.Root, or Zod schema.\";\n  }\n\n  /**\n   * The unminifiable (static, human-readable) error name for this error class.\n   */\n  static get unminifiable_name() {\n    return \"StateGraphInputError\";\n  }\n}\n\n/**\n * Used for subgraph detection.\n */\nexport const getSubgraphsSeenSet = () => {\n  if (\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (globalThis as any)[Symbol.for(\"LG_CHECKPOINT_SEEN_NS_SET\")] === undefined\n  ) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (globalThis as any)[Symbol.for(\"LG_CHECKPOINT_SEEN_NS_SET\")] = new Set();\n  }\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return (globalThis as any)[Symbol.for(\"LG_CHECKPOINT_SEEN_NS_SET\")];\n};\n"],"mappings":"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"}
+{"version":3,"file":"errors.cjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { Command, Interrupt } from \"./constants.js\";\n\n// When editing, make sure to update the index found here:\n// https://langchain-ai.github.io/langgraphjs/troubleshooting/errors/\nexport type BaseLangGraphErrorFields = {\n  lc_error_code?:\n    | \"GRAPH_RECURSION_LIMIT\"\n    | \"INVALID_CONCURRENT_GRAPH_UPDATE\"\n    | \"INVALID_GRAPH_NODE_RETURN_VALUE\"\n    | \"MISSING_CHECKPOINTER\"\n    | \"MULTIPLE_SUBGRAPHS\"\n    | \"UNREACHABLE_NODE\";\n};\n\n// TODO: Merge with base LangChain error class when we drop support for core@0.2.0\n/** @category Errors */\nexport class BaseLangGraphError extends Error {\n  lc_error_code?: string;\n\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    let finalMessage = message ?? \"\";\n    if (fields?.lc_error_code) {\n      finalMessage = `${finalMessage}\\n\\nTroubleshooting URL: https://docs.langchain.com/oss/javascript/langgraph/${fields.lc_error_code}/\\n`;\n    }\n    super(finalMessage);\n    this.lc_error_code = fields?.lc_error_code;\n  }\n}\n\nexport class GraphBubbleUp extends BaseLangGraphError {\n  get is_bubble_up() {\n    return true;\n  }\n}\n\nexport class GraphRecursionError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"GraphRecursionError\";\n  }\n\n  static get unminifiable_name() {\n    return \"GraphRecursionError\";\n  }\n}\n\nexport class GraphValueError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"GraphValueError\";\n  }\n\n  static get unminifiable_name() {\n    return \"GraphValueError\";\n  }\n}\n\n/**\n * Raised when a graph run exits early due to a drain request.\n *\n * This indicates the graph stopped cooperatively at a superstep boundary\n * because {@link RunControl#requestDrain} was called (e.g., in response to\n * SIGTERM). The checkpoint is saved and the run can be resumed later.\n */\nexport class GraphDrained extends GraphBubbleUp {\n  reason: string;\n\n  constructor(reason: string = \"shutdown\", fields?: BaseLangGraphErrorFields) {\n    super(`Graph drained: ${reason}`, fields);\n    this.name = \"GraphDrained\";\n    this.reason = reason;\n  }\n\n  static get unminifiable_name() {\n    return \"GraphDrained\";\n  }\n}\n\nexport function isGraphDrained(e?: unknown): e is GraphDrained {\n  return (\n    e !== undefined && (e as Error).name === GraphDrained.unminifiable_name\n  );\n}\n\nexport class GraphInterrupt extends GraphBubbleUp {\n  interrupts: Interrupt[];\n\n  constructor(interrupts?: Interrupt[], fields?: BaseLangGraphErrorFields) {\n    super(JSON.stringify(interrupts, null, 2), fields);\n    this.name = \"GraphInterrupt\";\n    this.interrupts = interrupts ?? [];\n  }\n\n  static get unminifiable_name() {\n    return \"GraphInterrupt\";\n  }\n}\n\n/** Raised by a node to interrupt execution. */\nexport class NodeInterrupt extends GraphInterrupt {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  constructor(message: any, fields?: BaseLangGraphErrorFields) {\n    super([{ value: message }], fields);\n    this.name = \"NodeInterrupt\";\n  }\n\n  static get unminifiable_name() {\n    return \"NodeInterrupt\";\n  }\n}\n\n/**\n * Failure context passed to a node-level error handler.\n *\n * A node-level error handler is registered via\n * `StateGraph.addNode(name, fn, { errorHandler })`. The handler runs ONLY after\n * the failing node's {@link RetryPolicy} is exhausted, so retry and handling\n * stay decoupled. The handler receives the failed node's name and the thrown\n * error via a `NodeError` instance, can return a state update, and can route to\n * a recovery branch via `new Command({ goto })` (saga / compensation flows).\n *\n * @example\n * ```ts\n * import { NodeError } from \"@langchain/langgraph\";\n *\n * function handler(state: State, error: NodeError) {\n *   return new Command({\n *     update: { status: `recovered from ${error.node}: ${error.error.message}` },\n *     goto: \"finalize\",\n *   });\n * }\n * ```\n */\nexport class NodeError {\n  /** Name of the node whose execution failed. */\n  node: string;\n\n  /** Error thrown by the failed node. */\n  error: Error;\n\n  constructor(node: string, error: Error) {\n    this.node = node;\n    this.error = error;\n  }\n\n  static get unminifiable_name() {\n    return \"NodeError\";\n  }\n}\n\n/**\n * Type guard that checks whether a value is a {@link NodeError}.\n */\nexport function isNodeError(e?: unknown): e is NodeError {\n  return (\n    e != null &&\n    typeof e === \"object\" &&\n    e.constructor != null &&\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (e.constructor as any).unminifiable_name === NodeError.unminifiable_name\n  );\n}\n\nexport class ParentCommand extends GraphBubbleUp {\n  command: Command;\n\n  constructor(command: Command) {\n    super();\n    this.name = \"ParentCommand\";\n    this.command = command;\n  }\n\n  static get unminifiable_name() {\n    return \"ParentCommand\";\n  }\n}\n\nexport function isParentCommand(e?: unknown): e is ParentCommand {\n  return (\n    e !== undefined &&\n    (e as ParentCommand).name === ParentCommand.unminifiable_name\n  );\n}\n\nexport function isGraphBubbleUp(e?: unknown): e is GraphBubbleUp {\n  return e !== undefined && (e as GraphBubbleUp).is_bubble_up === true;\n}\n\nexport function isGraphInterrupt(e?: unknown): e is GraphInterrupt {\n  return (\n    e !== undefined &&\n    [\n      GraphInterrupt.unminifiable_name,\n      NodeInterrupt.unminifiable_name,\n    ].includes((e as Error).name)\n  );\n}\n\n/**\n * Raised when a node invocation exceeds one of its configured timeouts.\n *\n * Does **not** extend {@link GraphBubbleUp} (so it flows through the normal node\n * error path) and is intentionally treated as retryable by the default retry\n * policy — its message/name do not match the default `retryOn` blocklist, so a\n * configured {@link RetryPolicy} will retry it (see langchain-ai/langgraph#7659).\n *\n * Both {@link NodeTimeoutError.runTimeout} and {@link NodeTimeoutError.idleTimeout}\n * reflect the configured policy at the time of the failure (each `undefined` if\n * not configured). {@link NodeTimeoutError.kind} and {@link NodeTimeoutError.timeout}\n * identify which one fired.\n *\n * @category Errors\n */\nexport class NodeTimeoutError extends BaseLangGraphError {\n  /** Name of the node/task that timed out. */\n  node: string;\n\n  /** Which timeout fired: a hard `\"run\"` cap or a progress-resetting `\"idle\"` cap. */\n  kind: \"run\" | \"idle\";\n\n  /** The value (ms) of the timeout that fired (`runTimeout` or `idleTimeout`). */\n  timeout: number;\n\n  /** Elapsed time (ms) since the attempt started, at the moment the timeout fired. */\n  elapsed: number;\n\n  /** Configured run timeout (ms), if any. */\n  runTimeout?: number;\n\n  /** Configured idle timeout (ms), if any. */\n  idleTimeout?: number;\n\n  constructor(\n    fields: {\n      node: string;\n      elapsed: number;\n      kind: \"run\" | \"idle\";\n      runTimeout?: number;\n      idleTimeout?: number;\n    },\n    errorFields?: BaseLangGraphErrorFields\n  ) {\n    const { node, elapsed, kind, runTimeout, idleTimeout } = fields;\n    let message: string;\n    let timeout: number;\n    if (kind === \"idle\") {\n      if (idleTimeout === undefined) {\n        throw new Error(\"idleTimeout is required when kind='idle'\");\n      }\n      timeout = idleTimeout;\n      message =\n        `Node \"${node}\" exceeded its idle timeout of ${idleTimeout}ms ` +\n        `without making progress (elapsed: ${elapsed}ms).`;\n    } else {\n      if (runTimeout === undefined) {\n        throw new Error(\"runTimeout is required when kind='run'\");\n      }\n      timeout = runTimeout;\n      message =\n        `Node \"${node}\" exceeded its run timeout of ${runTimeout}ms ` +\n        `(elapsed: ${elapsed}ms).`;\n    }\n    super(message, errorFields);\n    this.name = \"NodeTimeoutError\";\n    this.node = node;\n    this.kind = kind;\n    this.timeout = timeout;\n    this.elapsed = elapsed;\n    this.runTimeout = runTimeout;\n    this.idleTimeout = idleTimeout;\n  }\n\n  static get unminifiable_name() {\n    return \"NodeTimeoutError\";\n  }\n}\n\nexport function isNodeTimeoutError(e?: unknown): e is NodeTimeoutError {\n  return (\n    e !== undefined &&\n    (e as NodeTimeoutError).name === NodeTimeoutError.unminifiable_name\n  );\n}\n\nexport class EmptyInputError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"EmptyInputError\";\n  }\n\n  static get unminifiable_name() {\n    return \"EmptyInputError\";\n  }\n}\n\nexport class EmptyChannelError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    // Skip expensive stack trace capture — used for control flow on channel reads.\n    const prevLimit = Error.stackTraceLimit;\n    Error.stackTraceLimit = 0;\n    super(message, fields);\n    Error.stackTraceLimit = prevLimit;\n    this.name = \"EmptyChannelError\";\n  }\n\n  static get unminifiable_name() {\n    return \"EmptyChannelError\";\n  }\n}\n\nexport class InvalidUpdateError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"InvalidUpdateError\";\n  }\n\n  static get unminifiable_name() {\n    return \"InvalidUpdateError\";\n  }\n}\n\n/**\n * @deprecated This exception type is no longer thrown.\n */\nexport class MultipleSubgraphsError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"MultipleSubgraphError\";\n  }\n\n  static get unminifiable_name() {\n    return \"MultipleSubgraphError\";\n  }\n}\n\nexport class UnreachableNodeError extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"UnreachableNodeError\";\n  }\n\n  static get unminifiable_name() {\n    return \"UnreachableNodeError\";\n  }\n}\n\n/**\n * Exception raised when an error occurs in the remote graph.\n */\nexport class RemoteException extends BaseLangGraphError {\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"RemoteException\";\n  }\n\n  static get unminifiable_name() {\n    return \"RemoteException\";\n  }\n}\n\n/**\n * Error thrown when invalid input is provided to a StateGraph.\n *\n * This typically means that the input to the StateGraph constructor or builder\n * did not match the required types. A valid input should be a\n * StateDefinition, an Annotation.Root, or a Zod schema.\n *\n * @example\n * // Example of incorrect usage:\n * try {\n *   new StateGraph({ foo: \"bar\" }); // Not a valid input\n * } catch (err) {\n *   if (err instanceof StateGraphInputError) {\n *     console.error(err.message);\n *   }\n * }\n */\nexport class StateGraphInputError extends BaseLangGraphError {\n  /**\n   * Create a new StateGraphInputError.\n   * @param message - Optional custom error message.\n   * @param fields - Optional additional error fields.\n   */\n  constructor(message?: string, fields?: BaseLangGraphErrorFields) {\n    super(message, fields);\n    this.name = \"StateGraphInputError\";\n    this.message =\n      \"Invalid StateGraph input. Make sure to pass a valid StateDefinition, Annotation.Root, or Zod schema.\";\n  }\n\n  /**\n   * The unminifiable (static, human-readable) error name for this error class.\n   */\n  static get unminifiable_name() {\n    return \"StateGraphInputError\";\n  }\n}\n\n/**\n * Used for subgraph detection.\n */\nexport const getSubgraphsSeenSet = () => {\n  if (\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (globalThis as any)[Symbol.for(\"LG_CHECKPOINT_SEEN_NS_SET\")] === undefined\n  ) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (globalThis as any)[Symbol.for(\"LG_CHECKPOINT_SEEN_NS_SET\")] = new Set();\n  }\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return (globalThis as any)[Symbol.for(\"LG_CHECKPOINT_SEEN_NS_SET\")];\n};\n"],"mappings":"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"}

package/dist/errors.d.cts

@@ -20,6 +20,19 @@ declare class GraphValueError extends BaseLangGraphError {
   constructor(message?: string, fields?: BaseLangGraphErrorFields);
   static get unminifiable_name(): string;
 }
+/**
+ * Raised when a graph run exits early due to a drain request.
+ *
+ * This indicates the graph stopped cooperatively at a superstep boundary
+ * because {@link RunControl#requestDrain} was called (e.g., in response to
+ * SIGTERM). The checkpoint is saved and the run can be resumed later.
+ */
+declare class GraphDrained extends GraphBubbleUp {
+  reason: string;
+  constructor(reason?: string, fields?: BaseLangGraphErrorFields);
+  static get unminifiable_name(): string;
+}
+declare function isGraphDrained(e?: unknown): e is GraphDrained;
 declare class GraphInterrupt extends GraphBubbleUp {
   interrupts: Interrupt[];
   constructor(interrupts?: Interrupt[], fields?: BaseLangGraphErrorFields);
@@ -30,6 +43,40 @@ declare class NodeInterrupt extends GraphInterrupt {
   constructor(message: any, fields?: BaseLangGraphErrorFields);
   static get unminifiable_name(): string;
 }
+/**
+ * Failure context passed to a node-level error handler.
+ *
+ * A node-level error handler is registered via
+ * `StateGraph.addNode(name, fn, { errorHandler })`. The handler runs ONLY after
+ * the failing node's {@link RetryPolicy} is exhausted, so retry and handling
+ * stay decoupled. The handler receives the failed node's name and the thrown
+ * error via a `NodeError` instance, can return a state update, and can route to
+ * a recovery branch via `new Command({ goto })` (saga / compensation flows).
+ *
+ * @example
+ * ```ts
+ * import { NodeError } from "@langchain/langgraph";
+ *
+ * function handler(state: State, error: NodeError) {
+ *   return new Command({
+ *     update: { status: `recovered from ${error.node}: ${error.error.message}` },
+ *     goto: "finalize",
+ *   });
+ * }
+ * ```
+ */
+declare class NodeError {
+  /** Name of the node whose execution failed. */
+  node: string;
+  /** Error thrown by the failed node. */
+  error: Error;
+  constructor(node: string, error: Error);
+  static get unminifiable_name(): string;
+}
+/**
+ * Type guard that checks whether a value is a {@link NodeError}.
+ */
+declare function isNodeError(e?: unknown): e is NodeError;
 declare class ParentCommand extends GraphBubbleUp {
   command: Command;
   constructor(command: Command);
@@ -38,6 +85,44 @@ declare class ParentCommand extends GraphBubbleUp {
 declare function isParentCommand(e?: unknown): e is ParentCommand;
 declare function isGraphBubbleUp(e?: unknown): e is GraphBubbleUp;
 declare function isGraphInterrupt(e?: unknown): e is GraphInterrupt;
+/**
+ * Raised when a node invocation exceeds one of its configured timeouts.
+ *
+ * Does **not** extend {@link GraphBubbleUp} (so it flows through the normal node
+ * error path) and is intentionally treated as retryable by the default retry
+ * policy — its message/name do not match the default `retryOn` blocklist, so a
+ * configured {@link RetryPolicy} will retry it (see langchain-ai/langgraph#7659).
+ *
+ * Both {@link NodeTimeoutError.runTimeout} and {@link NodeTimeoutError.idleTimeout}
+ * reflect the configured policy at the time of the failure (each `undefined` if
+ * not configured). {@link NodeTimeoutError.kind} and {@link NodeTimeoutError.timeout}
+ * identify which one fired.
+ *
+ * @category Errors
+ */
+declare class NodeTimeoutError extends BaseLangGraphError {
+  /** Name of the node/task that timed out. */
+  node: string;
+  /** Which timeout fired: a hard `"run"` cap or a progress-resetting `"idle"` cap. */
+  kind: "run" | "idle";
+  /** The value (ms) of the timeout that fired (`runTimeout` or `idleTimeout`). */
+  timeout: number;
+  /** Elapsed time (ms) since the attempt started, at the moment the timeout fired. */
+  elapsed: number;
+  /** Configured run timeout (ms), if any. */
+  runTimeout?: number;
+  /** Configured idle timeout (ms), if any. */
+  idleTimeout?: number;
+  constructor(fields: {
+    node: string;
+    elapsed: number;
+    kind: "run" | "idle";
+    runTimeout?: number;
+    idleTimeout?: number;
+  }, errorFields?: BaseLangGraphErrorFields);
+  static get unminifiable_name(): string;
+}
+declare function isNodeTimeoutError(e?: unknown): e is NodeTimeoutError;
 declare class EmptyInputError extends BaseLangGraphError {
   constructor(message?: string, fields?: BaseLangGraphErrorFields);
   static get unminifiable_name(): string;
@@ -102,5 +187,5 @@ declare class StateGraphInputError extends BaseLangGraphError {
  */
 declare const getSubgraphsSeenSet: () => any;
 //#endregion
-export { BaseLangGraphError, BaseLangGraphErrorFields, EmptyChannelError, EmptyInputError, GraphBubbleUp, GraphInterrupt, GraphRecursionError, GraphValueError, InvalidUpdateError, MultipleSubgraphsError, NodeInterrupt, ParentCommand, RemoteException, StateGraphInputError, UnreachableNodeError, getSubgraphsSeenSet, isGraphBubbleUp, isGraphInterrupt, isParentCommand };
+export { BaseLangGraphError, BaseLangGraphErrorFields, EmptyChannelError, EmptyInputError, GraphBubbleUp, GraphDrained, GraphInterrupt, GraphRecursionError, GraphValueError, InvalidUpdateError, MultipleSubgraphsError, NodeError, NodeInterrupt, NodeTimeoutError, ParentCommand, RemoteException, StateGraphInputError, UnreachableNodeError, getSubgraphsSeenSet, isGraphBubbleUp, isGraphDrained, isGraphInterrupt, isNodeError, isNodeTimeoutError, isParentCommand };
 //# sourceMappingURL=errors.d.cts.map

package/dist/errors.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.cts","names":[],"sources":["../src/errors.ts"],"mappings":";;;KAIY,wBAAA;EACV,aAAA;AAAA;;cAWW,kBAAA,SAA2B,KAAA;EACtC,aAAA;EAEA,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;AAAA;AAAA,cAU5B,aAAA,SAAsB,kBAAA;EAAA,IAC7B,YAAA,CAAA;AAAA;AAAA,cAKO,mBAAA,SAA4B,kBAAA;EACvC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,eAAA,SAAwB,kBAAA;EACnC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,cAAA,SAAuB,aAAA;EAClC,UAAA,EAAY,SAAA;EAEZ,WAAA,CAAY,UAAA,GAAa,SAAA,IAAa,MAAA,GAAS,wBAAA;EAAA,WAMpC,iBAAA,CAAA;AAAA;AA/Bb;AAAA,cAqCa,aAAA,SAAsB,cAAA;EAEjC,WAAA,CAAY,OAAA,OAAc,MAAA,GAAS,wBAAA;EAAA,WAKxB,iBAAA,CAAA;AAAA;AAAA,cAKA,aAAA,SAAsB,aAAA;EACjC,OAAA,EAAS,OAAA;EAET,WAAA,CAAY,OAAA,EAAS,OAAA;EAAA,WAMV,iBAAA,CAAA;AAAA;AAAA,iBAKG,eAAA,CAAgB,CAAA,aAAc,CAAA,IAAK,aAAA;AAAA,iBAOnC,eAAA,CAAgB,CAAA,aAAc,CAAA,IAAK,aAAA;AAAA,iBAInC,gBAAA,CAAiB,CAAA,aAAc,CAAA,IAAK,cAAA;AAAA,cAUvC,eAAA,SAAwB,kBAAA;EACnC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,iBAAA,SAA0B,kBAAA;EACrC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,kBAAA,SAA2B,kBAAA;EACtC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;;;;cAQA,sBAAA,SAA+B,kBAAA;EAC1C,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,oBAAA,SAA6B,kBAAA;EACxC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;;;;cAQA,eAAA,SAAwB,kBAAA;EACnC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;;AAlHb;;;;;;;;;;;;AAYA;;;;cA4Ha,oBAAA,SAA6B,kBAAA;EA5HP;;;;;EAkIjC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EA/HvC;;;EAAA,WAyIW,iBAAA,CAAA;AAAA;;AA9Hb;;cAsIa,mBAAA"}
+{"version":3,"file":"errors.d.cts","names":[],"sources":["../src/errors.ts"],"mappings":"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"}

package/dist/errors.d.ts

@@ -20,6 +20,19 @@ declare class GraphValueError extends BaseLangGraphError {
   constructor(message?: string, fields?: BaseLangGraphErrorFields);
   static get unminifiable_name(): string;
 }
+/**
+ * Raised when a graph run exits early due to a drain request.
+ *
+ * This indicates the graph stopped cooperatively at a superstep boundary
+ * because {@link RunControl#requestDrain} was called (e.g., in response to
+ * SIGTERM). The checkpoint is saved and the run can be resumed later.
+ */
+declare class GraphDrained extends GraphBubbleUp {
+  reason: string;
+  constructor(reason?: string, fields?: BaseLangGraphErrorFields);
+  static get unminifiable_name(): string;
+}
+declare function isGraphDrained(e?: unknown): e is GraphDrained;
 declare class GraphInterrupt extends GraphBubbleUp {
   interrupts: Interrupt[];
   constructor(interrupts?: Interrupt[], fields?: BaseLangGraphErrorFields);
@@ -30,6 +43,40 @@ declare class NodeInterrupt extends GraphInterrupt {
   constructor(message: any, fields?: BaseLangGraphErrorFields);
   static get unminifiable_name(): string;
 }
+/**
+ * Failure context passed to a node-level error handler.
+ *
+ * A node-level error handler is registered via
+ * `StateGraph.addNode(name, fn, { errorHandler })`. The handler runs ONLY after
+ * the failing node's {@link RetryPolicy} is exhausted, so retry and handling
+ * stay decoupled. The handler receives the failed node's name and the thrown
+ * error via a `NodeError` instance, can return a state update, and can route to
+ * a recovery branch via `new Command({ goto })` (saga / compensation flows).
+ *
+ * @example
+ * ```ts
+ * import { NodeError } from "@langchain/langgraph";
+ *
+ * function handler(state: State, error: NodeError) {
+ *   return new Command({
+ *     update: { status: `recovered from ${error.node}: ${error.error.message}` },
+ *     goto: "finalize",
+ *   });
+ * }
+ * ```
+ */
+declare class NodeError {
+  /** Name of the node whose execution failed. */
+  node: string;
+  /** Error thrown by the failed node. */
+  error: Error;
+  constructor(node: string, error: Error);
+  static get unminifiable_name(): string;
+}
+/**
+ * Type guard that checks whether a value is a {@link NodeError}.
+ */
+declare function isNodeError(e?: unknown): e is NodeError;
 declare class ParentCommand extends GraphBubbleUp {
   command: Command;
   constructor(command: Command);
@@ -38,6 +85,44 @@ declare class ParentCommand extends GraphBubbleUp {
 declare function isParentCommand(e?: unknown): e is ParentCommand;
 declare function isGraphBubbleUp(e?: unknown): e is GraphBubbleUp;
 declare function isGraphInterrupt(e?: unknown): e is GraphInterrupt;
+/**
+ * Raised when a node invocation exceeds one of its configured timeouts.
+ *
+ * Does **not** extend {@link GraphBubbleUp} (so it flows through the normal node
+ * error path) and is intentionally treated as retryable by the default retry
+ * policy — its message/name do not match the default `retryOn` blocklist, so a
+ * configured {@link RetryPolicy} will retry it (see langchain-ai/langgraph#7659).
+ *
+ * Both {@link NodeTimeoutError.runTimeout} and {@link NodeTimeoutError.idleTimeout}
+ * reflect the configured policy at the time of the failure (each `undefined` if
+ * not configured). {@link NodeTimeoutError.kind} and {@link NodeTimeoutError.timeout}
+ * identify which one fired.
+ *
+ * @category Errors
+ */
+declare class NodeTimeoutError extends BaseLangGraphError {
+  /** Name of the node/task that timed out. */
+  node: string;
+  /** Which timeout fired: a hard `"run"` cap or a progress-resetting `"idle"` cap. */
+  kind: "run" | "idle";
+  /** The value (ms) of the timeout that fired (`runTimeout` or `idleTimeout`). */
+  timeout: number;
+  /** Elapsed time (ms) since the attempt started, at the moment the timeout fired. */
+  elapsed: number;
+  /** Configured run timeout (ms), if any. */
+  runTimeout?: number;
+  /** Configured idle timeout (ms), if any. */
+  idleTimeout?: number;
+  constructor(fields: {
+    node: string;
+    elapsed: number;
+    kind: "run" | "idle";
+    runTimeout?: number;
+    idleTimeout?: number;
+  }, errorFields?: BaseLangGraphErrorFields);
+  static get unminifiable_name(): string;
+}
+declare function isNodeTimeoutError(e?: unknown): e is NodeTimeoutError;
 declare class EmptyInputError extends BaseLangGraphError {
   constructor(message?: string, fields?: BaseLangGraphErrorFields);
   static get unminifiable_name(): string;
@@ -102,5 +187,5 @@ declare class StateGraphInputError extends BaseLangGraphError {
  */
 declare const getSubgraphsSeenSet: () => any;
 //#endregion
-export { BaseLangGraphError, BaseLangGraphErrorFields, EmptyChannelError, EmptyInputError, GraphBubbleUp, GraphInterrupt, GraphRecursionError, GraphValueError, InvalidUpdateError, MultipleSubgraphsError, NodeInterrupt, ParentCommand, RemoteException, StateGraphInputError, UnreachableNodeError, getSubgraphsSeenSet, isGraphBubbleUp, isGraphInterrupt, isParentCommand };
+export { BaseLangGraphError, BaseLangGraphErrorFields, EmptyChannelError, EmptyInputError, GraphBubbleUp, GraphDrained, GraphInterrupt, GraphRecursionError, GraphValueError, InvalidUpdateError, MultipleSubgraphsError, NodeError, NodeInterrupt, NodeTimeoutError, ParentCommand, RemoteException, StateGraphInputError, UnreachableNodeError, getSubgraphsSeenSet, isGraphBubbleUp, isGraphDrained, isGraphInterrupt, isNodeError, isNodeTimeoutError, isParentCommand };
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;KAIY,wBAAA;EACV,aAAA;AAAA;;cAWW,kBAAA,SAA2B,KAAA;EACtC,aAAA;EAEA,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;AAAA;AAAA,cAU5B,aAAA,SAAsB,kBAAA;EAAA,IAC7B,YAAA,CAAA;AAAA;AAAA,cAKO,mBAAA,SAA4B,kBAAA;EACvC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,eAAA,SAAwB,kBAAA;EACnC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,cAAA,SAAuB,aAAA;EAClC,UAAA,EAAY,SAAA;EAEZ,WAAA,CAAY,UAAA,GAAa,SAAA,IAAa,MAAA,GAAS,wBAAA;EAAA,WAMpC,iBAAA,CAAA;AAAA;AA/Bb;AAAA,cAqCa,aAAA,SAAsB,cAAA;EAEjC,WAAA,CAAY,OAAA,OAAc,MAAA,GAAS,wBAAA;EAAA,WAKxB,iBAAA,CAAA;AAAA;AAAA,cAKA,aAAA,SAAsB,aAAA;EACjC,OAAA,EAAS,OAAA;EAET,WAAA,CAAY,OAAA,EAAS,OAAA;EAAA,WAMV,iBAAA,CAAA;AAAA;AAAA,iBAKG,eAAA,CAAgB,CAAA,aAAc,CAAA,IAAK,aAAA;AAAA,iBAOnC,eAAA,CAAgB,CAAA,aAAc,CAAA,IAAK,aAAA;AAAA,iBAInC,gBAAA,CAAiB,CAAA,aAAc,CAAA,IAAK,cAAA;AAAA,cAUvC,eAAA,SAAwB,kBAAA;EACnC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,iBAAA,SAA0B,kBAAA;EACrC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,kBAAA,SAA2B,kBAAA;EACtC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;;;;cAQA,sBAAA,SAA+B,kBAAA;EAC1C,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;AAAA,cAKA,oBAAA,SAA6B,kBAAA;EACxC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;;;;cAQA,eAAA,SAAwB,kBAAA;EACnC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EAAA,WAK5B,iBAAA,CAAA;AAAA;;AAlHb;;;;;;;;;;;;AAYA;;;;cA4Ha,oBAAA,SAA6B,kBAAA;EA5HP;;;;;EAkIjC,WAAA,CAAY,OAAA,WAAkB,MAAA,GAAS,wBAAA;EA/HvC;;;EAAA,WAyIW,iBAAA,CAAA;AAAA;;AA9Hb;;cAsIa,mBAAA"}
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":"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"}

package/dist/errors.js

@@ -32,6 +32,27 @@ var GraphValueError = class extends BaseLangGraphError {
 		return "GraphValueError";
 	}
 };
+/**
+* Raised when a graph run exits early due to a drain request.
+*
+* This indicates the graph stopped cooperatively at a superstep boundary
+* because {@link RunControl#requestDrain} was called (e.g., in response to
+* SIGTERM). The checkpoint is saved and the run can be resumed later.
+*/
+var GraphDrained = class extends GraphBubbleUp {
+	reason;
+	constructor(reason = "shutdown", fields) {
+		super(`Graph drained: ${reason}`, fields);
+		this.name = "GraphDrained";
+		this.reason = reason;
+	}
+	static get unminifiable_name() {
+		return "GraphDrained";
+	}
+};
+function isGraphDrained(e) {
+	return e !== void 0 && e.name === GraphDrained.unminifiable_name;
+}
 var GraphInterrupt = class extends GraphBubbleUp {
 	interrupts;
 	constructor(interrupts, fields) {
@@ -53,6 +74,47 @@ var NodeInterrupt = class extends GraphInterrupt {
 		return "NodeInterrupt";
 	}
 };
+/**
+* Failure context passed to a node-level error handler.
+*
+* A node-level error handler is registered via
+* `StateGraph.addNode(name, fn, { errorHandler })`. The handler runs ONLY after
+* the failing node's {@link RetryPolicy} is exhausted, so retry and handling
+* stay decoupled. The handler receives the failed node's name and the thrown
+* error via a `NodeError` instance, can return a state update, and can route to
+* a recovery branch via `new Command({ goto })` (saga / compensation flows).
+*
+* @example
+* ```ts
+* import { NodeError } from "@langchain/langgraph";
+*
+* function handler(state: State, error: NodeError) {
+*   return new Command({
+*     update: { status: `recovered from ${error.node}: ${error.error.message}` },
+*     goto: "finalize",
+*   });
+* }
+* ```
+*/
+var NodeError = class {
+	/** Name of the node whose execution failed. */
+	node;
+	/** Error thrown by the failed node. */
+	error;
+	constructor(node, error) {
+		this.node = node;
+		this.error = error;
+	}
+	static get unminifiable_name() {
+		return "NodeError";
+	}
+};
+/**
+* Type guard that checks whether a value is a {@link NodeError}.
+*/
+function isNodeError(e) {
+	return e != null && typeof e === "object" && e.constructor != null && e.constructor.unminifiable_name === NodeError.unminifiable_name;
+}
 var ParentCommand = class extends GraphBubbleUp {
 	command;
 	constructor(command) {
@@ -73,6 +135,63 @@ function isGraphBubbleUp(e) {
 function isGraphInterrupt(e) {
 	return e !== void 0 && [GraphInterrupt.unminifiable_name, NodeInterrupt.unminifiable_name].includes(e.name);
 }
+/**
+* Raised when a node invocation exceeds one of its configured timeouts.
+*
+* Does **not** extend {@link GraphBubbleUp} (so it flows through the normal node
+* error path) and is intentionally treated as retryable by the default retry
+* policy — its message/name do not match the default `retryOn` blocklist, so a
+* configured {@link RetryPolicy} will retry it (see langchain-ai/langgraph#7659).
+*
+* Both {@link NodeTimeoutError.runTimeout} and {@link NodeTimeoutError.idleTimeout}
+* reflect the configured policy at the time of the failure (each `undefined` if
+* not configured). {@link NodeTimeoutError.kind} and {@link NodeTimeoutError.timeout}
+* identify which one fired.
+*
+* @category Errors
+*/
+var NodeTimeoutError = class extends BaseLangGraphError {
+	/** Name of the node/task that timed out. */
+	node;
+	/** Which timeout fired: a hard `"run"` cap or a progress-resetting `"idle"` cap. */
+	kind;
+	/** The value (ms) of the timeout that fired (`runTimeout` or `idleTimeout`). */
+	timeout;
+	/** Elapsed time (ms) since the attempt started, at the moment the timeout fired. */
+	elapsed;
+	/** Configured run timeout (ms), if any. */
+	runTimeout;
+	/** Configured idle timeout (ms), if any. */
+	idleTimeout;
+	constructor(fields, errorFields) {
+		const { node, elapsed, kind, runTimeout, idleTimeout } = fields;
+		let message;
+		let timeout;
+		if (kind === "idle") {
+			if (idleTimeout === void 0) throw new Error("idleTimeout is required when kind='idle'");
+			timeout = idleTimeout;
+			message = `Node "${node}" exceeded its idle timeout of ${idleTimeout}ms without making progress (elapsed: ${elapsed}ms).`;
+		} else {
+			if (runTimeout === void 0) throw new Error("runTimeout is required when kind='run'");
+			timeout = runTimeout;
+			message = `Node "${node}" exceeded its run timeout of ${runTimeout}ms (elapsed: ${elapsed}ms).`;
+		}
+		super(message, errorFields);
+		this.name = "NodeTimeoutError";
+		this.node = node;
+		this.kind = kind;
+		this.timeout = timeout;
+		this.elapsed = elapsed;
+		this.runTimeout = runTimeout;
+		this.idleTimeout = idleTimeout;
+	}
+	static get unminifiable_name() {
+		return "NodeTimeoutError";
+	}
+};
+function isNodeTimeoutError(e) {
+	return e !== void 0 && e.name === NodeTimeoutError.unminifiable_name;
+}
 var EmptyInputError = class extends BaseLangGraphError {
 	constructor(message, fields) {
 		super(message, fields);
@@ -84,7 +203,10 @@ var EmptyInputError = class extends BaseLangGraphError {
 };
 var EmptyChannelError = class extends BaseLangGraphError {
 	constructor(message, fields) {
+		const prevLimit = Error.stackTraceLimit;
+		Error.stackTraceLimit = 0;
 		super(message, fields);
+		Error.stackTraceLimit = prevLimit;
 		this.name = "EmptyChannelError";
 	}
 	static get unminifiable_name() {
@@ -176,6 +298,6 @@ const getSubgraphsSeenSet = () => {
 	return globalThis[Symbol.for("LG_CHECKPOINT_SEEN_NS_SET")];
 };
 //#endregion
-export { BaseLangGraphError, EmptyChannelError, EmptyInputError, GraphBubbleUp, GraphInterrupt, GraphRecursionError, GraphValueError, InvalidUpdateError, MultipleSubgraphsError, NodeInterrupt, ParentCommand, RemoteException, StateGraphInputError, UnreachableNodeError, getSubgraphsSeenSet, isGraphBubbleUp, isGraphInterrupt, isParentCommand };
+export { BaseLangGraphError, EmptyChannelError, EmptyInputError, GraphBubbleUp, GraphDrained, GraphInterrupt, GraphRecursionError, GraphValueError, InvalidUpdateError, MultipleSubgraphsError, NodeError, NodeInterrupt, NodeTimeoutError, ParentCommand, RemoteException, StateGraphInputError, UnreachableNodeError, getSubgraphsSeenSet, isGraphBubbleUp, isGraphDrained, isGraphInterrupt, isNodeError, isNodeTimeoutError, isParentCommand };
 
 //# sourceMappingURL=errors.js.map