Module agentforge4j.runtime

Package com.agentforge4j.runtime.tool

Class DefaultToolExecutionService

java.lang.Object

com.agentforge4j.runtime.tool.DefaultToolExecutionService

All Implemented Interfaces:

ToolExecutionService

public final class DefaultToolExecutionService
extends Object
implements ToolExecutionService

Default ToolExecutionService: the single chokepoint for tool invocation. It emits audit events, resolves the capability, validates arguments, evaluates policy, and invokes the provider under an authoritative hard timeout that the service owns regardless of provider behaviour. On approval it persists a PendingToolInvocation and resumes later via resume(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.ApprovalDecision), never re-invoking the LLM.

Constructor Summary

Constructors

Constructor	Description
DefaultToolExecutionService(ToolProviderResolver resolver, ToolPolicy policy, PendingToolInvocationStore pendingStore, ToolExecutionOptions options, EventRecorder eventRecorder, com.fasterxml.jackson.databind.ObjectMapper objectMapper, Clock clock)	Creates the chokepoint service with its collaborators.

Method Summary

Modifier and Type	Method	Description
ToolExecutionOutcome	execute(ToolInvocationCommand cmd, ToolInvocationContext ctx)	Executes a requested tool invocation.
ToolExecutionOutcome	resume(String runId, String toolInvocationId, ApprovalDecision decision)	Resumes a previously suspended tool invocation — awaiting approval (ToolExecutionOutcome.Status.APPROVAL_PENDING), or awaiting an operator decision after a policy denial or an execution failure — after a human decision.

Methods inherited from class java.lang.Object

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

Constructor Details

DefaultToolExecutionService

public DefaultToolExecutionService(ToolProviderResolver resolver,
 ToolPolicy policy,
 PendingToolInvocationStore pendingStore,
 ToolExecutionOptions options,
 EventRecorder eventRecorder,
 com.fasterxml.jackson.databind.ObjectMapper objectMapper,
 Clock clock)

Creates the chokepoint service with its collaborators.

Parameters:

resolver - capability resolver (sole resolver; fail-fast)

policy - policy gate

pendingStore - store for approval-pending invocations

options - invocation tunables, including the authoritative timeout

eventRecorder - audit sink

objectMapper - JSON mapper for argument validation and event payloads

clock - clock for pending-invocation timestamps

Method Details

execute

public ToolExecutionOutcome execute(ToolInvocationCommand cmd,
 ToolInvocationContext ctx)

Description copied from interface: ToolExecutionService

Executes a requested tool invocation.

Specified by:

execute in interface ToolExecutionService

Parameters:

cmd - the requested invocation

ctx - invocation context

Returns:

the terminal outcome

resume

public ToolExecutionOutcome resume(String runId,
 String toolInvocationId,
 ApprovalDecision decision)

Resumes a previously suspended tool invocation — awaiting approval (ToolExecutionOutcome.Status.APPROVAL_PENDING), or awaiting an operator decision after a policy denial or an execution failure — after a human decision.

For an PendingToolInvocation.Origin.APPROVAL_REQUIRED or PendingToolInvocation.Origin.EXECUTION_FAILED row, the human decision supersedes the original PolicyDecision.RequireApproval rule: policy is not re-evaluated. The capability is re-resolved and arguments re-validated against current configuration, and the pending record is atomically claimed — tied to the exact row this call observed (see PendingToolInvocationStore.claim(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation)) — before invocation, so that two concurrent resumes on the same invocation never both execute. If there is no claimable pending row for this invocation — whether because it was never pending, already resolved, or claimed/replaced by a concurrent resume before this call's own claim attempt — this call throws ToolInvocationClaimLostException without mutating any state; this is a benign concurrency-loss signal, never reported as a provider/tool failure. If the claimed attempt itself fails, a fresh pending row is persisted so the operator gets a further decision point.

For a PendingToolInvocation.Origin.POLICY_DENIED row the denial is terminal: ApprovalDecision.Approve is rejected with a PolicyDenialTerminalException without invoking the provider and without consuming the pending row; only ApprovalDecision.Reject resolves it through this method (the runtime's non-executing ToolDecision.Continue resolves it without ever calling resume — it claims the pending row directly, using the same atomic, exact-row-tied contract).

If there is no claimable pending row for runId/toolInvocationId — never pending, already resolved, or already claimed/replaced by a concurrent resume — this call throws ToolInvocationClaimLostException without mutating any state; this is a benign concurrency-loss signal, never reported as a provider/tool failure. When a row is found, a PendingToolInvocation.Origin.POLICY_DENIED row is terminal: an ApprovalDecision.Approve — whether issued by the runtime's ToolDecision.Retry or a direct SPI call — never reaches the provider for such a row. Before treating it as terminal, this re-verifies (via PendingToolInvocationStore.verifyStillCurrent(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation)) that the exact row this call originally observed is still the current one — a concurrent ApprovalDecision.Reject or the runtime's non-executing ToolDecision.Continue may have already resolved it in the meantime, in which case this call throws ToolInvocationClaimLostException instead, never an override-rejected event for a row that is no longer even pending. Only once still confirmed current is it rejected with a PolicyDenialTerminalException and an audited override-rejected event, with the row left in place (never claimed/removed here) so that later legitimate resolver can still resolve it. Every other pending row is claimed atomically, tied to the exact row this call observed via PendingToolInvocationStore.find(java.lang.String, java.lang.String) (see PendingToolInvocationStore.claim(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation)), before its provider is invoked, so at most one of two concurrent resumes on the same invocation executes; the other — or a resume whose observed row was replaced by a different one before its own claim attempt — never reaches the provider and throws the same ToolInvocationClaimLostException. If the claimed call itself ends in ToolExecutionOutcome.Status.FAILED, a fresh pending row is persisted (origin PendingToolInvocation.Origin.EXECUTION_FAILED) so the operator gets a further decision point rather than the run silently losing the pending invocation.

Specified by:

resume in interface ToolExecutionService

Parameters:

runId - non-blank run that owns the pending invocation

toolInvocationId - non-blank pending invocation id

decision - the human decision

Returns:

the terminal outcome

Throws:

ToolInvocationClaimLostException - if there is no claimable pending row for this invocation, whether because it was never pending, already resolved, or claimed/replaced by a concurrent resume before this call's own claim attempt