neograph::graph::NodeInterrupt Class Reference

Exception thrown from inside a node to trigger a dynamic breakpoint. More...

#include <types.h>

Inherits std::runtime_error.

Public Member Functions
const std::string &	node () const
	The node that threw this interrupt.
	NodeInterrupt (const std::string &reason)
	Construct a NodeInterrupt with a reason message.
	NodeInterrupt (const std::string &reason, json value)
	Construct a NodeInterrupt carrying a structured payload.
const std::string &	reason () const
	Get the interrupt reason.
void	set_node (std::string node)
	Record the throwing node's name. Called by the executor.
const json &	value () const
	Get the structured payload.

Detailed Description

Exception thrown from inside a node to trigger a dynamic breakpoint.

When a node throws NodeInterrupt, the graph engine saves a checkpoint and pauses execution, allowing Human-in-the-Loop (HITL) intervention. Execution continues with GraphEngine::resume(), whose resume_value comes back to the node as RunContext::resume_value. Only the invocation that paused receives it; a node of a later step of the resumed run sees none (#393).

Unlike interrupt_before / interrupt_after in the graph definition, which pause at a node chosen when the graph was written, this pauses on a decision the node makes about what it is holding — which is what an approval prompt actually needs:

// Out: why we stopped, and what needs approving.
throw NodeInterrupt("shell command needs approval",
                    json{{"tool", "shell"}, {"cmd", "rm -rf build/"}});
 
// In (on the resumed call): what the human said.
if (in.ctx.resume_value->value("approved", false)) { ... }

The caller sees the reason at RunResult::interrupt_value["reason"], the payload at ["value"], and the node that paused at RunResult::interrupt_node.

Definition at line 200 of file types.h.

Constructor & Destructor Documentation

NodeInterrupt() [1/2]

neograph::graph::NodeInterrupt::NodeInterrupt ( const std::string &  reason )

inlineexplicit

Construct a NodeInterrupt with a reason message.

Parameters

reason

Human-readable explanation of why the interrupt was triggered.

Definition at line 204 of file types.h.

NodeInterrupt() [2/2]

neograph::graph::NodeInterrupt::NodeInterrupt ( const std::string &  reason, json  value  )

inline

Construct a NodeInterrupt carrying a structured payload.

Parameters

reason	Human-readable explanation, for logs and for humans.
value	Machine-readable payload the caller can branch on without parsing prose (which tool, which arguments, ...).

Definition at line 211 of file types.h.

Member Function Documentation

node()

const std::string & neograph::graph::NodeInterrupt::node ( ) const

inline

The node that threw this interrupt.

Stamped by the executor, which is the only layer that knows the name — a node body does not know what the graph definition called it. Empty on an interrupt that has not yet passed through the executor.

Definition at line 228 of file types.h.

reason()

const std::string & neograph::graph::NodeInterrupt::reason ( ) const

inline

Get the interrupt reason.

Returns

The reason string provided at construction.

Definition at line 217 of file types.h.

value()

const json & neograph::graph::NodeInterrupt::value ( ) const

inline

Get the structured payload.

Returns

The payload, or a null json when the node attached none.

Definition at line 221 of file types.h.

---

The documentation for this class was generated from the following file:

• include/neograph/graph/types.h