Module agentforge4j.runtime
Package com.agentforge4j.runtime.interceptor

Class ExecutionBlockedException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
com.agentforge4j.runtime.interceptor.ExecutionBlockedException
All Implemented Interfaces:
Serializable
public final class ExecutionBlockedException extends RuntimeException
Thrown by a RunExecutionInterceptor to deliberately block a run from proceeding — for example when a budget control declines to admit the next LLM call. This is a control outcome (a chosen veto), distinct from an incidental runtime failure; the runtime treats it as a blocking signal and halts the affected drive.

OSS itself never throws this — it carries no notion of why a run might be blocked; only a registered interceptor (supplied by an embedding application) raises it.

Lifecycle on a block: the workflow run is paused rather than failed — the runtime records a neutral WorkflowEventType.RUN_BLOCKED audit event and transitions the run to WorkflowStatus.PAUSED, performing no terminal transition, although a mid-step block also emits a STEP_FAILED audit event before RUN_BLOCKED. When thrown from RunExecutionInterceptor.beforeLlmCall(com.agentforge4j.runtime.interceptor.LlmCallContext) (mid-step, as opposed to RunExecutionInterceptor.beforeMainExecution(com.agentforge4j.runtime.interceptor.RunExecutionContext)), the exception propagates through the step's own failure handling first, which is why that STEP_FAILED event for the in-flight step precedes RUN_BLOCKED. The embedding application resolves the block — for example once the vetoing condition no longer applies — or cancels the run; any mapping to an application-specific status is the embedder's concern.

See Also:

  • Constructor Details

    • ExecutionBlockedException

      public ExecutionBlockedException(String message)
      Creates a blocked-execution signal.
      Parameters:
      message - human-readable reason the interceptor blocked execution

    • ExecutionBlockedException

      public ExecutionBlockedException(String message, Throwable cause)
      Creates a blocked-execution signal with an underlying cause.
      Parameters:
      message - human-readable reason the interceptor blocked execution
      cause - the underlying cause