Skip to content

Commit 4b0f434

Browse files
fix(agent): classify lease-style guard stops and check delivery liveness (#206)
A bare execution guard whose assertActive throws a plain RuntimeException (the framework's own checkpoint lease throws LeaseLostException) no longer degrades to a marked repair failure or escapes the delivery as an execution error: attemptRepair re-asserts the guard before treating a call failure as the client's own, and the graph delivery boundary re-checks the guard to classify stop-shaped failures as INTERRUPTED. The boundary also asserts liveness before publishing, so an already cancelled, expired or ownership-lost run cannot deliver a COMPLETED output even when the terminal message is schema-valid and needs no repair. ExecutionGuard gains a default deadline() accessor (overridden by ExecutionControl) so the repair wait is sliced only when a deadline actually bounds it — a deadline-less guard goes back to a plain wait instead of polling idle — and the graph bridge reuses the canonical AgentExecutionContext scope instead of re-implementing the wrap. Deterministic regression tests cover a lease-style guard lost during the repair and an expired trusted deadline with a valid terminal.
1 parent e3cf9e8 commit 4b0f434

6 files changed

Lines changed: 179 additions & 32 deletions

File tree

‎argi-agent/argi-agent-core/src/main/java/io/github/agentic/ai/agent/result/StructuredOutputFinalizer.java‎

Lines changed: 29 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -81,12 +81,12 @@
8181
* Passing the run's {@link ExecutionGuard} makes the repair re-ask execution-aware:
8282
* a guard that is already stopped (cancelled, past its deadline, ownership lost)
8383
* skips the re-ask and propagates the stop instead of returning a validation failure,
84-
* and a stop raised while the re-ask is in flight — including a deadline that expires
85-
* while the response is still pending — actively cancels that call and propagates the
86-
* stop reason instead of waiting on a request that may never return. A deadline that
87-
* expires after the response returned still stops the delivery before publishing it.
88-
* Without a guard, a cancelled or failing repair client degrades to the marked
89-
* repair failure instead.
84+
* and a stop raised while the re-ask is in flight cancels that call and propagates
85+
* the stop. A deadline carried by the guard is enforced while the response is still
86+
* pending — a request that never returns is cancelled once the deadline expires —
87+
* and a deadline that expires after the response returned still stops the delivery
88+
* before publishing it. Without a guard, a cancelled or failing repair client
89+
* degrades to the marked repair failure instead.
9090
* </p>
9191
*/
9292
public final class StructuredOutputFinalizer {
@@ -141,12 +141,13 @@ public AgentResult finalizeOutput(ChatMessage terminal, String outputSchema, Usa
141141
* the run's execution guard. The guard governs the optional repair re-ask: a guard
142142
* that is already stopped (cancelled, past its deadline, ownership lost) skips the
143143
* re-ask and propagates the stop instead of returning a validation failure, and a
144-
* stop raised while the re-ask is in flight — including a deadline that expires
145-
* while the response is still pending — actively cancels that call and propagates
146-
* the stop reason instead of waiting on a request that may never return. A deadline
147-
* that expires after the response returned still stops the delivery before
148-
* publishing it. Validation failures themselves are never thrown. Without a guard,
149-
* a cancelled or failing repair client degrades to a marked repair failure instead.
144+
* stop raised while the re-ask is in flight cancels that call and propagates the
145+
* stop. A deadline carried by the guard is enforced while the response is still
146+
* pending — a request that never returns is cancelled once the deadline expires —
147+
* and a deadline that expires after the response returned still stops the delivery
148+
* before publishing it. Validation failures themselves are never thrown. Without a
149+
* guard, a cancelled or failing repair client degrades to a marked repair failure
150+
* instead.
150151
* @param terminal the terminal assistant message; must not be {@code null}
151152
* @param outputSchema the configured JSON Schema for the output, or {@code null} or
152153
* blank when the run has none
@@ -266,17 +267,26 @@ private ChatMessage attemptRepair(ChatMessage terminal, String outputSchema,
266267
throw cancelled;
267268
}
268269
catch (RuntimeException ex) {
270+
if (control != null) {
271+
// A stop-shaped failure (a guard whose assertActive throws a plain
272+
// RuntimeException, such as a lost checkpoint lease) must propagate as
273+
// that stop instead of degrading to a marked repair failure; an active
274+
// guard confirms the failure was the client's own.
275+
control.assertActive();
276+
}
269277
return null;
270278
}
271279
}
272280

273281
/**
274282
* Performs the repair re-ask bound to the run's guard: a stop raised while the call
275283
* is in flight cancels the pending call, and the cancellation observed while waiting
276-
* is translated back into the guard's stop reason by the caller. The wait itself is
277-
* sliced so the synchronous deadline boundary is enforced while the response is
278-
* still pending: a request that never returns is cancelled once the deadline
279-
* expires, instead of blocking the delivery until an external timeout.
284+
* is translated back into the guard's stop by the caller. When the guard carries a
285+
* deadline the wait is sliced so the synchronous deadline boundary is enforced while
286+
* the response is still pending — a request that never returns is cancelled once the
287+
* deadline expires instead of blocking the delivery. A guard without a deadline is
288+
* waited on plainly: every stop path fires the onLoss registration synchronously,
289+
* and slicing would only add idle wakeups.
280290
*/
281291
private ChatResponse callUnderControl(ChatRequest request, ExecutionGuard control) {
282292
CompletableFuture<ChatResponse> pending = this.repairClient.call(request).toCompletableFuture();
@@ -287,6 +297,9 @@ private ChatResponse callUnderControl(ChatRequest request, ExecutionGuard contro
287297
}
288298
});
289299
try (AutoCloseable ignored = control.onLoss(() -> pending.cancel(true))) {
300+
if (control.deadline().isEmpty()) {
301+
return pending.get();
302+
}
290303
while (true) {
291304
try {
292305
return pending.get(DEADLINE_POLL_MILLIS, TimeUnit.MILLISECONDS);

‎argi-agent/argi-agent-core/src/test/java/io/github/agentic/ai/agent/result/StructuredOutputFinalizerExecutionControlTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ void deadlineExpiryDuringRepairStopsTheDelivery() {
180180
void neverReturningRepairRequestIsCancelledAtTheDeadline() {
181181
final CompletableFuture<ChatResponse> pending = new CompletableFuture<>();
182182
final ControlledClient client = new ControlledClient(request -> pending);
183-
final ExecutionControl control = new ExecutionControl(trustedContext(Instant.now().plusMillis(250)),
183+
final ExecutionControl control = new ExecutionControl(trustedContext(Instant.now().plusMillis(500)),
184184
Clock.systemUTC());
185185
final StructuredOutputFinalizer repairing = new StructuredOutputFinalizer(client);
186186

‎argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/ReactAgent.java‎

Lines changed: 44 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
import io.github.agentic.ai.api.chat.ChatClient;
2424
import io.github.agentic.ai.api.chat.ChatResponse;
2525

26+
import io.github.agentic.ai.agent.AgentExecutionContext;
2627
import io.github.agentic.ai.agent.AgentResult;
2728
import io.github.agentic.ai.runtime.execution.ExecutionControl;
2829
import io.github.agentic.ai.runtime.execution.ExecutionGuard;
@@ -536,9 +537,10 @@ private AgentResult finalizeResult(Optional<NodeOutput> output, RunnableConfig c
536537
/**
537538
* Maps a terminal message onto the delivery boundary shared by call and stream paths.
538539
* The run's execution boundaries travel with the delivery: the config's own control
539-
* passes through unchanged, a trusted deadline without one is bridged onto a control
540-
* owned by this delivery, and a stop observed during the final repair stays a stop —
541-
* it must neither publish a completed output nor degrade to a validation failure.
540+
* passes through unchanged, a trusted deadline without one is bridged onto the
541+
* canonical invocation scope owned by this delivery, and a stop observed before or
542+
* during the final repair stays a stop — it must neither publish a completed output
543+
* nor degrade to a validation failure or an execution error.
542544
*/
543545
private AgentResult deliver(ChatMessage terminal, Usage usage, RunnableConfig config) {
544546
if (Boolean.TRUE.equals(terminal.metadata().get(AgentLlmNode.MODEL_FAILURE_METADATA_KEY))) {
@@ -551,29 +553,57 @@ private AgentResult deliver(ChatMessage terminal, Usage usage, RunnableConfig co
551553
TrustedExecutionContext trusted = config == null ? null : config.trustedExecutionContext().orElse(null);
552554
ExecutionGuard guard = config == null ? null : config.executionGuard().orElse(null);
553555
if (trusted != null && !(guard instanceof ExecutionControl)) {
554-
// The remaining deadline and the ownership boundary combine into a control
555-
// owned by this delivery; the neutral finalizer stays free of graph types.
556-
try (ExecutionControl owned = new ExecutionControl(trusted, Clock.systemUTC(), guard)) {
557-
return finalizeUnderGuard(terminal, usage, owned);
556+
// The remaining deadline and the ownership boundary combine into the
557+
// canonical invocation scope owned by this delivery; the neutral finalizer
558+
// stays free of graph types.
559+
try (AgentExecutionContext owned = new AgentExecutionContext(trusted, Clock.systemUTC(), guard)) {
560+
return finalizeUnderGuard(terminal, usage, owned.control());
558561
}
559562
}
560-
if (guard == null && trusted == null) {
561-
// No execution boundary is attached to the run: keep the uncontrolled
562-
// legacy delivery.
563-
return finalizer().finalizeOutput(terminal, outputSchema, usage);
564-
}
565563
return finalizeUnderGuard(terminal, usage, guard);
566564
}
567565

566+
/**
567+
* Runs the final delivery under the run's guard, or uncontrolled when the run
568+
* carries none. A stop observed at the boundary — including a guard whose
569+
* assertActive throws a plain RuntimeException, such as a lost checkpoint lease —
570+
* delivers an interrupted run; any other failure keeps its pre-existing
571+
* classification.
572+
*/
568573
private AgentResult finalizeUnderGuard(ChatMessage terminal, Usage usage, ExecutionGuard guard) {
574+
if (runStopped(guard)) {
575+
// A cancelled, expired or lost-ownership run must not publish a late
576+
// output, not even a schema-valid one.
577+
return AgentResult.interrupted(usage);
578+
}
569579
try {
570580
return finalizer().finalizeOutput(terminal, outputSchema, usage, guard);
571581
}
572582
catch (CancellationException stopped) {
573-
// A cancelled, expired or lost-ownership run must not publish a late output:
574-
// the stop stays a stop instead of degrading to a validation failure.
575583
return AgentResult.interrupted(usage);
576584
}
585+
catch (RuntimeException failure) {
586+
if (runStopped(guard)) {
587+
// The failure was the guard's own stop signal: keep the stop semantics
588+
// instead of degrading them to a marked repair or execution failure.
589+
return AgentResult.interrupted(usage);
590+
}
591+
throw failure;
592+
}
593+
}
594+
595+
/** A guard that fails its liveness assertion marks the run as stopped. */
596+
private static boolean runStopped(ExecutionGuard guard) {
597+
if (guard == null) {
598+
return false;
599+
}
600+
try {
601+
guard.assertActive();
602+
return false;
603+
}
604+
catch (RuntimeException stopped) {
605+
return true;
606+
}
577607
}
578608

579609
/**

‎argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/ReactAgentExecutionControlDeliveryTest.java‎

Lines changed: 84 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
import java.util.concurrent.CountDownLatch;
2525
import java.util.concurrent.Flow;
2626
import java.util.concurrent.TimeUnit;
27+
import java.util.concurrent.atomic.AtomicBoolean;
2728
import java.util.concurrent.atomic.AtomicInteger;
2829
import java.util.function.Function;
2930

@@ -37,6 +38,7 @@
3738
import io.github.agentic.ai.api.chat.Usage;
3839
import io.github.agentic.ai.agent.AgentResult;
3940
import io.github.agentic.ai.runtime.execution.ExecutionControl;
41+
import io.github.agentic.ai.runtime.execution.ExecutionGuard;
4042
import io.github.agentic.ai.runtime.execution.PrincipalReference;
4143
import io.github.agentic.ai.runtime.execution.TenantReference;
4244
import io.github.agentic.ai.runtime.execution.TrustedExecutionContext;
@@ -110,7 +112,7 @@ void cancelledControlDuringGraphRepairInterruptsDelivery() throws Exception {
110112
@DisplayName("a trusted deadline without a guard stops a never-returning graph repair")
111113
void trustedDeadlineStopsANeverReturningGraphRepair() {
112114
final ControllableClient client = ControllableClient.blockingMainModel("plain prose answer");
113-
final TrustedExecutionContext trusted = trustedContext(Instant.now().plusMillis(1500));
115+
final TrustedExecutionContext trusted = trustedContext(Instant.now().plusMillis(3000));
114116
final RunnableConfig config = RunnableConfig.builder().trustedExecutionContext(trusted).build();
115117
final ReactAgent agent = agent(client, SCHEMA);
116118

@@ -157,6 +159,59 @@ void cancelledControlDuringStreamedRepairInterruptsDelivery() throws Exception {
157159
}
158160
}
159161

162+
@Test
163+
@Timeout(15)
164+
@DisplayName("a lease-style guard lost during the graph repair delivers INTERRUPTED, not a marked repair failure")
165+
void leaseStyleGuardLostDuringGraphRepairInterruptsDelivery() throws Exception {
166+
final LeaseStyleGuard guard = new LeaseStyleGuard();
167+
final ControllableClient client = ControllableClient.blockingMainModel("plain prose answer");
168+
final RunnableConfig config = RunnableConfig.builder().executionGuard(guard).build();
169+
final ReactAgent agent = agent(client, SCHEMA);
170+
171+
final Thread loser = new Thread(() -> {
172+
try {
173+
client.awaitRepairStarted(5, TimeUnit.SECONDS);
174+
guard.lose();
175+
// A lease-fenced adapter call fails with the lease's own exception type.
176+
client.repairPending.completeExceptionally(new IllegalStateException("lease fenced the call"));
177+
}
178+
catch (InterruptedException ignored) {
179+
Thread.currentThread().interrupt();
180+
}
181+
});
182+
loser.start();
183+
try {
184+
final AgentResult result = agent.callResult("give me the status", config);
185+
186+
assertThat(result.status()).isEqualTo(AgentResult.Status.INTERRUPTED);
187+
// The stop must not be folded into a marked repair or validation failure.
188+
assertThat(result.issues()).isEmpty();
189+
assertThat(result.message()).isNull();
190+
assertThat(client.modelCalls.get()).isEqualTo(1);
191+
assertThat(client.repairCalls.get()).isEqualTo(1);
192+
}
193+
finally {
194+
loser.join(TimeUnit.SECONDS.toMillis(5));
195+
}
196+
}
197+
198+
@Test
199+
@Timeout(15)
200+
@DisplayName("an expired trusted deadline delivers INTERRUPTED even when the terminal output is schema-valid")
201+
void expiredDeadlineStopsDeliveryOfAValidOutput() {
202+
final ControllableClient client = ControllableClient.blockingMainModel("{\"status\":\"ok\"}");
203+
final TrustedExecutionContext trusted = trustedContext(Instant.now().minusSeconds(1));
204+
final RunnableConfig config = RunnableConfig.builder().trustedExecutionContext(trusted).build();
205+
final ReactAgent agent = agent(client, SCHEMA);
206+
207+
final AgentResult result = agent.callResult("give me the status", config);
208+
209+
assertThat(result.status()).isEqualTo(AgentResult.Status.INTERRUPTED);
210+
assertThat(result.issues()).isEmpty();
211+
assertThat(client.modelCalls.get()).isEqualTo(1);
212+
assertThat(client.repairCalls.get()).isZero();
213+
}
214+
160215
@Test
161216
@DisplayName("without a config the bounded repair keeps completing the delivery")
162217
void legacyDeliveryWithoutConfigStillRepairs() {
@@ -179,6 +234,34 @@ private static ReactAgent agent(ChatClient client, String outputSchema) {
179234
.build();
180235
}
181236

237+
/**
238+
* Mirrors a checkpoint-lease guard whose stop signal is a plain RuntimeException,
239+
* not a cancellation: the framework's own lease scope throws LeaseLostException.
240+
*/
241+
private static final class LeaseStyleGuard implements ExecutionGuard {
242+
243+
private final AtomicBoolean lost = new AtomicBoolean();
244+
245+
void lose() {
246+
this.lost.set(true);
247+
}
248+
249+
@Override
250+
public void assertActive() {
251+
if (this.lost.get()) {
252+
throw new IllegalStateException("lease lost");
253+
}
254+
}
255+
256+
@Override
257+
public AutoCloseable onLoss(Runnable cancellation) {
258+
// The lease scope in this test reports loss only through assertActive.
259+
return () -> {
260+
};
261+
}
262+
263+
}
264+
182265
private static ExecutionControl activeControl() {
183266
return new ExecutionControl(trustedContext(null), Clock.systemUTC());
184267
}

‎argi-runtime/argi-runtime-api/src/main/java/io/github/agentic/ai/runtime/execution/ExecutionControl.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import java.time.Instant;
2121
import java.util.ArrayList;
2222
import java.util.LinkedHashSet;
23+
import java.util.Optional;
2324
import java.util.Set;
2425
import java.util.concurrent.atomic.AtomicBoolean;
2526

@@ -62,6 +63,11 @@ public ExecutionControl(TrustedExecutionContext context, Clock clock, ExecutionG
6263
} : requireNonNull(ownership.onLoss(this::loseOwnership), "ownership registration cannot be null");
6364
}
6465

66+
@Override
67+
public Optional<Instant> deadline() {
68+
return Optional.ofNullable(this.deadline);
69+
}
70+
6571
@Override
6672
public void assertActive() {
6773
checkDeadline();

‎argi-runtime/argi-runtime-api/src/main/java/io/github/agentic/ai/runtime/execution/ExecutionGuard.java‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@
1515
*/
1616
package io.github.agentic.ai.runtime.execution;
1717

18+
import java.time.Instant;
19+
import java.util.Optional;
20+
1821
/**
1922
* Execution-local liveness guard exposed without lease credentials or engine state.
2023
*/
@@ -24,4 +27,16 @@ public interface ExecutionGuard {
2427

2528
AutoCloseable onLoss(Runnable cancellation);
2629

30+
/**
31+
* The deadline this guard enforces synchronously through {@link #assertActive()},
32+
* or empty when the guard has no deadline of its own. Executors that block on an
33+
* in-flight operation use it to decide whether the wait must be sliced so the
34+
* deadline is enforced while the operation is still pending; a guard without a
35+
* deadline can be waited on plainly, because every stop path fires
36+
* {@link #onLoss(Runnable)} synchronously.
37+
*/
38+
default Optional<Instant> deadline() {
39+
return Optional.empty();
40+
}
41+
2742
}

0 commit comments

Comments
 (0)