Module agentforge4j.runtime

Package com.agentforge4j.runtime.tool

Class InMemoryPendingToolInvocationStore

java.lang.Object

com.agentforge4j.runtime.tool.InMemoryPendingToolInvocationStore

All Implemented Interfaces:

PendingToolInvocationStore

public final class InMemoryPendingToolInvocationStore
extends Object
implements PendingToolInvocationStore

In-memory PendingToolInvocationStore (OSS default). Entries are keyed by run id and invocation id so a lookup for one run can never return another run's pending invocation.

Constructor Summary

Constructors

Constructor	Description
InMemoryPendingToolInvocationStore()

Method Summary

Modifier and Type	Method	Description
PendingToolInvocation	claim(String runId, String toolInvocationId, PendingToolInvocation expectedPending)	Atomically removes and returns a pending invocation, but only if the row currently stored for runId/toolInvocationId is still exactly expectedPending — the same instance (or an equal value) an earlier PendingToolInvocationStore.find(java.lang.String, java.lang.String) on this call's behalf observed.
PendingToolInvocation	find(String runId, String toolInvocationId)	Finds a pending invocation within its owning run.
List<PendingToolInvocation>	findByRun(String runId)	Returns every pending invocation currently awaiting resolution for runId.
void	remove(String runId, String toolInvocationId)	Removes a pending invocation; a no-op if it is absent.
void	save(PendingToolInvocation pending)	Persists a pending invocation.
PendingToolInvocation	verifyStillCurrent(String runId, String toolInvocationId, PendingToolInvocation expectedPending)	Atomically checks whether the row currently stored for runId/toolInvocationId is still exactly expectedPending — the same exact-row-identity guarantee PendingToolInvocationStore.claim(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation) provides, but without removing the row.

Methods inherited from class java.lang.Object

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

Constructor Details

InMemoryPendingToolInvocationStore

public InMemoryPendingToolInvocationStore()

Method Details

save

public void save(PendingToolInvocation pending)

Description copied from interface: PendingToolInvocationStore

Persists a pending invocation.

Specified by:

save in interface PendingToolInvocationStore

Parameters:

pending - the pending invocation

find

public PendingToolInvocation find(String runId,
 String toolInvocationId)

Description copied from interface: PendingToolInvocationStore

Finds a pending invocation within its owning run.

Specified by:

find in interface PendingToolInvocationStore

Parameters:

runId - owning run id

toolInvocationId - pending invocation id

Returns:

the pending invocation, or null if it does not belong to runId or is gone

findByRun

public List<PendingToolInvocation> findByRun(String runId)

Description copied from interface: PendingToolInvocationStore

Returns every pending invocation currently awaiting resolution for runId. The result is scoped to the run — invocations belonging to other runs are never included — and is empty when the run has none pending. Used to resolve the single current pending invocation when a scripted approve/deny/retry/continue does not name an id; callers fail closed when the count is not one.

Specified by:

findByRun in interface PendingToolInvocationStore

Parameters:

runId - owning run id

Returns:

the run's pending invocations, in no guaranteed order; never null

remove

public void remove(String runId,
 String toolInvocationId)

Description copied from interface: PendingToolInvocationStore

Removes a pending invocation; a no-op if it is absent.

Specified by:

remove in interface PendingToolInvocationStore

Parameters:

runId - owning run id

toolInvocationId - pending invocation id

claim

public PendingToolInvocation claim(String runId,
 String toolInvocationId,
 PendingToolInvocation expectedPending)

Description copied from interface: PendingToolInvocationStore

Atomically removes and returns a pending invocation, but only if the row currently stored for runId/toolInvocationId is still exactly expectedPending — the same instance (or an equal value) an earlier PendingToolInvocationStore.find(java.lang.String, java.lang.String) on this call's behalf observed. This closes two race windows at once: when two callers race to resume the same invocation, at most one observes a non-null result and every other concurrent caller observes null as though the row were already gone; and when the row is replaced (for example by a fresh pending row persisted after a claimed resume itself failed) between one caller's PendingToolInvocationStore.find(java.lang.String, java.lang.String) and its own claim attempt, that caller's claim fails rather than consuming the replacement under the stale row's authorization.

This is the sole safe way to consume a pending invocation before invoking its provider: a separate PendingToolInvocationStore.find(java.lang.String, java.lang.String) followed by a separate PendingToolInvocationStore.remove(java.lang.String, java.lang.String) leaves a window in which two concurrent resumes both observe the row and both invoke the provider, or in which a caller claims a row that is no longer the one it decided to act on. Implementations backed by a durable or distributed store must provide this atomically — for example a conditional delete tied to the expected row's identity/version (compare-and-delete), an equivalent compare-and-swap, or a SELECT ... FOR UPDATE followed by a delete guarded by the same condition within the same transaction — never a naive find-then-remove pair, which would silently reopen the race this method exists to close.

Specified by:

claim in interface PendingToolInvocationStore

Parameters:

runId - owning run id

toolInvocationId - pending invocation id

expectedPending - the pending invocation the caller observed and is claiming; the claim only succeeds if the currently stored row still equals this value

Returns:

the claimed pending invocation, or null if it does not belong to runId, is already gone, was already claimed by a concurrent caller, or no longer equals expectedPending (it was replaced)

verifyStillCurrent

public PendingToolInvocation verifyStillCurrent(String runId,
 String toolInvocationId,
 PendingToolInvocation expectedPending)

Description copied from interface: PendingToolInvocationStore

Atomically checks whether the row currently stored for runId/toolInvocationId is still exactly expectedPending — the same exact-row-identity guarantee PendingToolInvocationStore.claim(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation) provides, but without removing the row. Used when a caller must act on a previously observed row's content without itself consuming it, so a legitimate later resolver (for example a Reject, or the runtime's non-executing Continue) can still resolve the row afterward.

This exists because a caller re-issuing a plain PendingToolInvocationStore.find(java.lang.String, java.lang.String) and comparing the result against its own earlier observation in application code is not equivalent to this method: that second find is itself just another independent read, with no contract binding it to observe a result consistent with any other caller's concurrent PendingToolInvocationStore.claim(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation)/PendingToolInvocationStore.save(com.agentforge4j.core.spi.tool.PendingToolInvocation)/PendingToolInvocationStore.remove(java.lang.String, java.lang.String) on the same row — an implementation would be free to satisfy both methods' individual contracts while still letting the two calls interleave with an intervening mutation in a way that leaves the caller's decision based on data that was never simultaneously true. This method's contract fixes that: it is required to observe the exact same total order over claim/save/ remove/find for a given key that PendingToolInvocationStore.claim(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation)'s compare-and-delete already relies on, so a true-equivalent result here is a genuine, race-free confirmation that expectedPending was still the current row at a single well-defined point after every concurrent mutation that had already completed. Implementations backed by a durable or distributed store must provide this with the same atomicity guarantee as PendingToolInvocationStore.claim(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation) (for example a conditional read tied to the expected row's identity/version, consistent with whatever mechanism backs claim's compare-and-delete) — never a plain, independently-timed find call assembled in caller code.

Specified by:

verifyStillCurrent in interface PendingToolInvocationStore

Parameters:

runId - owning run id

toolInvocationId - pending invocation id

expectedPending - the pending invocation the caller previously observed

Returns:

expectedPending if the currently stored row for this key still equals it; null if it does not belong to runId, is already gone, or no longer equals expectedPending (it was claimed or replaced by a concurrent caller)