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

Interface RunExecutionInterceptor

public interface RunExecutionInterceptor
Control SPI for intercepting a run's execution at two pre-execution points: once before a run enters main execution, and immediately before each LLM call. Both points are synchronous and may veto by throwing ExecutionBlockedException; returning normally allows execution to proceed.

This is a control seam — distinct from the passive LlmCallObserver, which only watches completed calls. It carries no tenant, billing, or cost concepts; an embedding application (for example a budget enforcer) registers an implementation and derives those itself. Both methods default to no-ops, so when nothing is registered the runtime behaves exactly as before.

A single instance is shared across all runs and driving threads, so implementations must be thread-safe.

When a hook throws ExecutionBlockedException the runtime records a neutral WorkflowEventType.RUN_BLOCKED audit event and transitions the run to WorkflowStatus.PAUSED; the embedding application resolves the block (resume or cancel). OSS performs no terminal transition. See ExecutionBlockedException for the additional STEP_FAILED event a beforeLlmCall(com.agentforge4j.runtime.interceptor.LlmCallContext) veto records ahead of RUN_BLOCKED.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final RunExecutionInterceptor
    NO_OP
    Canonical no-op interceptor — both hooks allow; the default when nothing is registered.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    beforeLlmCall(LlmCallContext context)
    Invoked immediately before each LLM provider call, after model resolution and before dispatch.
    default void
    beforeMainExecution(RunExecutionContext context)
    Invoked once, when a run first enters main execution (not on resume).

  • Field Details

    • NO_OP

      static final RunExecutionInterceptor NO_OP
      Canonical no-op interceptor — both hooks allow; the default when nothing is registered.

  • Method Details

    • beforeMainExecution

      default void beforeMainExecution(RunExecutionContext context)
      Invoked once, when a run first enters main execution (not on resume). May throw ExecutionBlockedException to block the run before any step runs.
      Parameters:
      context - the run entering main execution

    • beforeLlmCall

      default void beforeLlmCall(LlmCallContext context)
      Invoked immediately before each LLM provider call, after model resolution and before dispatch. May throw ExecutionBlockedException to block the call.
      Parameters:
      context - the imminent call