Package dev.agenor.runtime.behavior.advanced

Class HumanCheckpointBehavior<T>

java.lang.Object

dev.agenor.runtime.behavior.BaseBehavior

dev.agenor.runtime.behavior.advanced.HumanCheckpointBehavior<T>

Type Parameters:

T - type of the action payload

All Implemented Interfaces:

Behavior

public class HumanCheckpointBehavior<T>
extends BaseBehavior

A ONE_SHOT behavior that suspends execution until a human approves, rejects, or modifies the wrapped critical action.

Execution flow:

1. Notifier fires (fire-and-forget) to alert an external observer.
2. ApprovalGate.requestApproval(dev.agenor.core.hitl.ApprovalRequest) is called; the virtual thread parks.
3. When ApprovalService.submit(java.lang.String, dev.agenor.core.hitl.ApprovalDecision) completes the future, the behavior resumes and dispatches to decisionHandler.

Example:

 new HumanCheckpointBehavior<>(
     "payment-checkpoint",
     approvalGate,
     notifier,
     paymentPayload,
     "process-payment",
     Duration.ofMinutes(30),
     decision -> switch (decision) {
         case ApprovalDecision.Approved  a -> processPayment(paymentPayload);
         case ApprovalDecision.Rejected  r -> log.warn("Rejected: {}", r.reason());
         case ApprovalDecision.Modified  m -> processPayment((PaymentRequest) m.newPayload());
     }
 )
 

Timeout: if no decision arrives within timeout, ApprovalTimeoutException is thrown inside action() and routed to BaseBehavior.onError(java.lang.Exception) by BaseBehavior (which swallows all throwables and completes the future normally). Override BaseBehavior.onError(java.lang.Exception) to add custom fallback or escalation logic.

Since:

0.13.0

See Also:

• ApprovalGate
• ApprovalNotifier
• ApprovalDecision

Constructor Summary

Constructors

Constructor	Description
HumanCheckpointBehavior(String behaviorId, ApprovalGate gate, ApprovalNotifier notifier, T payload, String actionName, Duration timeout, Consumer<ApprovalDecision> decisionHandler)	Creates a new HumanCheckpointBehavior.
HumanCheckpointBehavior(String behaviorId, ApprovalGate gate, ApprovalNotifier notifier, T payload, String actionName, Duration timeout, Consumer<ApprovalDecision> decisionHandler, AgenorTelemetry telemetry)	Creates a new HumanCheckpointBehavior with telemetry support.

Method Summary

Modifier and Type	Method	Description
protected void	action()	The main action to be performed by this behavior.

Methods inherited from class dev.agenor.runtime.behavior.BaseBehavior

activate, execute, getAgent, getBehaviorId, getInterval, getType, isActive, onError, onStop, setAgent, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface dev.agenor.core.Behavior

getInitialDelay

Constructor Details

HumanCheckpointBehavior

public HumanCheckpointBehavior(String behaviorId,
 ApprovalGate gate,
 ApprovalNotifier notifier,
 T payload,
 String actionName,
 Duration timeout,
 Consumer<ApprovalDecision> decisionHandler)

Creates a new HumanCheckpointBehavior.

Parameters:

behaviorId - unique identifier for this behavior

gate - gate used to park the virtual thread until a decision arrives

notifier - notifier invoked before the gate parks (fire-and-forget)

payload - data describing the action to be approved

actionName - human-readable action name included in the ApprovalRequest

timeout - maximum wait time for a human decision

decisionHandler - called with the ApprovalDecision when one is received; responsible for executing or skipping the critical action

HumanCheckpointBehavior

public HumanCheckpointBehavior(String behaviorId,
 ApprovalGate gate,
 ApprovalNotifier notifier,
 T payload,
 String actionName,
 Duration timeout,
 Consumer<ApprovalDecision> decisionHandler,
 AgenorTelemetry telemetry)

Creates a new HumanCheckpointBehavior with telemetry support.

Parameters:

behaviorId - unique identifier for this behavior

gate - gate used to park the virtual thread until a decision arrives

notifier - notifier invoked before the gate parks (fire-and-forget)

payload - data describing the action to be approved

actionName - human-readable action name included in the ApprovalRequest

timeout - maximum wait time for a human decision

decisionHandler - called with the ApprovalDecision when one is received

telemetry - telemetry instance for emitting hitl.approval spans; null uses noop

Since:

0.19.0

Method Details

action

protected void action()

Description copied from class: BaseBehavior

The main action to be performed by this behavior. Must be implemented by subclasses.

Specified by:

action in class BaseBehavior