Skip to content

Commit c20654c

Browse files
feat(agent): make structured output repair inherit execution control stops (#206)
StructuredOutputFinalizer gains a finalizeOutput overload that receives the run's ExecutionControl. A control that is already stopped (cancelled, past its deadline, ownership lost) skips the repair re-ask and propagates the stop instead of degrading to VALIDATION_FAILED; a stop raised while the re-ask is in flight cancels the pending repair call and propagates the stop reason; a deadline that expires during the re-ask stops the delivery after it. A repair re-ask that cannot be performed is marked with the new ERROR_CODE_REPAIR_CALL_FAILED beside the original issues, keeping cancellation, repair call errors and validation failures distinguishable. ReActAgent passes its AgentExecutionContext control into the finalizer. Budget accounting stays with the executor contract (#127): the repair call now runs inside the controlled path built from the trusted context that carries the budget declaration.
1 parent b348353 commit c20654c

6 files changed

Lines changed: 509 additions & 16 deletions

File tree

‎argi-agent/argi-agent-api/src/main/java/io/github/agentic/ai/agent/AgentResult.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,9 @@ public record AgentResult(ChatMessage message, Status status, Usage usage, Objec
5959
/** Error code marking that the single bounded repair attempt still failed validation. */
6060
public static final String ERROR_CODE_REPAIRED_STILL_INVALID = "REPAIRED_STILL_INVALID";
6161

62+
/** Error code marking that the bounded repair re-ask could not be performed at all. */
63+
public static final String ERROR_CODE_REPAIR_CALL_FAILED = "REPAIR_CALL_FAILED";
64+
6265
/**
6366
* Delivery status of the run.
6467
*/

‎argi-agent/argi-agent-core/src/main/java/io/github/agentic/ai/agent/react/ReActAgent.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -549,7 +549,7 @@ private void finish(List<ChatMessage> messages, Map<String, Object> state, Usage
549549
ChatMessage terminal) {
550550
Map<String, Object> outputs = new LinkedHashMap<>(state);
551551
if (outputSchema != null && outputFinalizer != null) {
552-
AgentResult result = outputFinalizer.finalizeOutput(terminal, outputSchema, usage);
552+
AgentResult result = outputFinalizer.finalizeOutput(terminal, outputSchema, usage, context.control());
553553
if (result.status() != AgentResult.Status.COMPLETED) {
554554
throw new AgentExecutionException(result);
555555
}

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

Lines changed: 121 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@
1818
import java.util.ArrayList;
1919
import java.util.List;
2020
import java.util.Map;
21+
import java.util.concurrent.CancellationException;
22+
import java.util.concurrent.CompletableFuture;
23+
import java.util.concurrent.ExecutionException;
24+
import java.util.concurrent.atomic.AtomicReference;
2125
import java.util.stream.Collectors;
2226

2327
import com.networknt.schema.Error;
@@ -34,6 +38,7 @@
3438
import io.github.agentic.ai.api.chat.ToolChoice;
3539
import io.github.agentic.ai.api.chat.Usage;
3640
import io.github.agentic.ai.agent.AgentResult;
41+
import io.github.agentic.ai.runtime.execution.ExecutionControl;
3742
import tools.jackson.core.StreamReadFeature;
3843
import tools.jackson.databind.DeserializationFeature;
3944
import tools.jackson.databind.JsonNode;
@@ -55,17 +60,29 @@
5560
* </p>
5661
*
5762
* <p>
58-
* The component never throws: every failure mode (malformed JSON, malformed schema,
59-
* schema violations) becomes {@link AgentResult.Status#VALIDATION_FAILED} with issue
60-
* entries that do not echo the full output content.
63+
* Validation never throws: every output failure mode (malformed JSON, malformed
64+
* schema, schema violations) becomes {@link AgentResult.Status#VALIDATION_FAILED} with
65+
* issue entries that do not echo the full output content.
6166
* </p>
6267
*
6368
* <p>
6469
* When constructed with a {@link ChatClient}, a failed validation gets exactly one
6570
* bounded repair attempt: a single-turn model re-ask that carries no tools (and never
6671
* touches the graph), after which the repaired output is re-validated without a second
67-
* repair. A failed repair is marked with {@link #ERROR_CODE_REPAIRED_STILL_INVALID};
68-
* a failing repair client leaves the original failure untouched.
72+
* repair. A repair that still fails validation is marked with
73+
* {@link AgentResult#ERROR_CODE_REPAIRED_STILL_INVALID}; a repair re-ask that cannot
74+
* be performed is marked with {@link AgentResult#ERROR_CODE_REPAIR_CALL_FAILED} beside
75+
* the original failure.
76+
* </p>
77+
*
78+
* <p>
79+
* Passing the run's {@link ExecutionControl} makes the repair re-ask execution-aware:
80+
* a control that is already stopped (cancelled, past its deadline, ownership lost)
81+
* skips the re-ask and propagates the stop instead of returning a validation failure,
82+
* a stop raised while the re-ask is in flight cancels that call and propagates the
83+
* stop reason, and a deadline that expires during the re-ask stops the delivery after
84+
* it. Without a control, a cancelled or failing repair client degrades to the marked
85+
* repair failure instead.
6986
* </p>
7087
*/
7188
public final class StructuredOutputFinalizer {
@@ -105,6 +122,28 @@ public StructuredOutputFinalizer(ChatClient repairClient) {
105122
* @return the delivery result; never {@code null} and never thrown over
106123
*/
107124
public AgentResult finalizeOutput(ChatMessage terminal, String outputSchema, Usage usage) {
125+
return finalizeOutput(terminal, outputSchema, usage, null);
126+
}
127+
128+
/**
129+
* Finalizes the terminal message of a run against the configured output schema under
130+
* the run's execution control. The control governs the optional repair re-ask: a
131+
* control that is already stopped (cancelled, past its deadline, ownership lost)
132+
* skips the re-ask and propagates the stop instead of returning a validation
133+
* failure, a stop raised while the re-ask is in flight cancels that call and
134+
* propagates the stop reason, and a deadline that expires during the re-ask stops
135+
* the delivery after it. Validation failures themselves are never thrown. Without a
136+
* control, a cancelled or failing repair client degrades to a marked repair failure
137+
* instead.
138+
* @param terminal the terminal assistant message; must not be {@code null}
139+
* @param outputSchema the configured JSON Schema for the output, or {@code null} or
140+
* blank when the run has none
141+
* @param usage the token usage recorded for the run, or {@code null} when unknown
142+
* @param control the run's execution control, or {@code null} to keep the
143+
* uncontrolled legacy behavior
144+
* @return the delivery result; never {@code null} and never thrown over
145+
*/
146+
public AgentResult finalizeOutput(ChatMessage terminal, String outputSchema, Usage usage, ExecutionControl control) {
108147
if (outputSchema == null || outputSchema.isEmpty()) {
109148
return AgentResult.completed(terminal, usage, null);
110149
}
@@ -123,11 +162,25 @@ public AgentResult finalizeOutput(ChatMessage terminal, String outputSchema, Usa
123162
if (first.status() != AgentResult.Status.VALIDATION_FAILED || this.repairClient == null) {
124163
return first;
125164
}
126-
127-
ChatMessage repaired = attemptRepair(terminal, outputSchema, first.issues());
165+
if (control != null) {
166+
// A stopped run must not spend another model call: cancelled, deadline
167+
// exceeded and ownership lost all propagate as execution stops.
168+
control.assertActive();
169+
}
170+
ChatMessage repaired = attemptRepair(terminal, outputSchema, first.issues(), control);
128171
if (repaired == null) {
129-
// The repair client failed: keep the original failure untouched.
130-
return first;
172+
// The repair re-ask could not be performed: keep the original failure and
173+
// mark the distinction from a repair that ran but stayed invalid.
174+
List<AgentResult.OutputValidationIssue> marked = new ArrayList<>();
175+
marked.add(new AgentResult.OutputValidationIssue(AgentResult.ERROR_CODE_REPAIR_CALL_FAILED, ROOT_PATH,
176+
"The bounded repair re-ask could not be performed or returned no assistant message"));
177+
marked.addAll(first.issues());
178+
return AgentResult.validationFailed(first.message(), first.usage(), List.copyOf(marked));
179+
}
180+
if (control != null) {
181+
// Deadline checks are synchronous: a deadline that expired during the
182+
// re-ask stops the delivery here instead of publishing a late output.
183+
control.assertActive();
131184
}
132185
AgentResult second = validateAgainst(repaired, schema, usage);
133186
if (second.status() != AgentResult.Status.VALIDATION_FAILED) {
@@ -169,7 +222,7 @@ private AgentResult validateAgainst(ChatMessage terminal, Schema schema, Usage u
169222
* assistant message, or {@code null} when the repair client itself failed.
170223
*/
171224
private ChatMessage attemptRepair(ChatMessage terminal, String outputSchema,
172-
List<AgentResult.OutputValidationIssue> issues) {
225+
List<AgentResult.OutputValidationIssue> issues, ExecutionControl control) {
173226
try {
174227
String issueSummary = issues.stream()
175228
.map(issue -> issue.errorCode()
@@ -181,16 +234,72 @@ private ChatMessage attemptRepair(ChatMessage terminal, String outputSchema,
181234
+ outputSchema);
182235
ChatMessage user = ChatMessage.user("The previous response failed schema validation (" + issueSummary
183236
+ "). Return the corrected JSON only.\nPrevious response:\n" + terminal.text());
184-
ChatResponse response = this.repairClient.callBlocking(new ChatRequest(List.of(system, user), List.of(),
185-
GenerationOptions.builder().toolChoice(ToolChoice.none()).build(), Map.of()));
237+
ChatRequest request = new ChatRequest(List.of(system, user), List.of(),
238+
GenerationOptions.builder().toolChoice(ToolChoice.none()).build(), Map.of());
239+
ChatResponse response = control == null ? this.repairClient.callBlocking(request)
240+
: callUnderControl(request, control);
186241
return response.messages().stream()
187242
.filter(message -> message.role() == ChatRole.ASSISTANT)
188243
.findFirst()
189244
.orElse(null);
190245
}
246+
catch (CancellationException cancelled) {
247+
if (control == null) {
248+
// The uncontrolled path has no stop semantics to preserve.
249+
return null;
250+
}
251+
// Propagate the control's stop reason when the cancellation came from it;
252+
// a cancellation raised by the client itself stays a cancellation.
253+
control.assertActive();
254+
throw cancelled;
255+
}
191256
catch (RuntimeException ex) {
192257
return null;
193258
}
194259
}
195260

261+
/**
262+
* Performs the repair re-ask bound to the run's control: a stop raised while the
263+
* call is in flight cancels the pending call, and the cancellation observed while
264+
* waiting is translated back into the control's stop reason by the caller.
265+
*/
266+
private ChatResponse callUnderControl(ChatRequest request, ExecutionControl control) {
267+
CompletableFuture<ChatResponse> pending = this.repairClient.call(request).toCompletableFuture();
268+
AtomicReference<Throwable> failure = new AtomicReference<>();
269+
pending.whenComplete((response, error) -> {
270+
if (error != null) {
271+
failure.set(error);
272+
}
273+
});
274+
try (AutoCloseable ignored = control.onLoss(() -> pending.cancel(true))) {
275+
return pending.get();
276+
}
277+
catch (InterruptedException interrupted) {
278+
pending.cancel(true);
279+
Thread.currentThread().interrupt();
280+
throw new CancellationException("Model repair call interrupted");
281+
}
282+
catch (CancellationException cancelled) {
283+
if (failure.get() instanceof CancellationException original) {
284+
throw original;
285+
}
286+
throw cancelled;
287+
}
288+
catch (Exception error) {
289+
// onLoss detachment cannot fail; everything else reaching here is the
290+
// awaited call failure, unwrapped from its ExecutionException carrier.
291+
throw repairFailure(error instanceof ExecutionException execution ? execution.getCause() : error);
292+
}
293+
}
294+
295+
private static RuntimeException repairFailure(Throwable error) {
296+
if (error instanceof RuntimeException runtime) {
297+
return runtime;
298+
}
299+
if (error instanceof java.lang.Error fatal) {
300+
throw fatal;
301+
}
302+
return new IllegalStateException("Model repair call failed", error);
303+
}
304+
196305
}

‎argi-agent/argi-agent-core/src/test/java/io/github/agentic/ai/agent/react/ReActAgentTest.java‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,11 @@
3838
import io.github.agentic.ai.agent.interceptor.ModelInterceptor;
3939
import io.github.agentic.ai.agent.interceptor.ModelRequest;
4040
import io.github.agentic.ai.agent.interceptor.ModelResponse;
41+
import io.github.agentic.ai.agent.result.StructuredOutputFinalizer;
4142
import io.github.agentic.ai.agent.tool.patch.ToolContextPatchPolicy;
4243
import io.github.agentic.ai.runtime.execution.DelegationScope;
4344
import io.github.agentic.ai.runtime.execution.ExecutionBudget;
45+
import io.github.agentic.ai.runtime.execution.ExecutionStoppedException;
4446
import io.github.agentic.ai.runtime.execution.PrincipalReference;
4547
import io.github.agentic.ai.runtime.execution.TenantReference;
4648
import io.github.agentic.ai.runtime.execution.TrustedExecutionContext;
@@ -236,6 +238,44 @@ public Map<String, Object> contextPatch(ToolCall call, ToolResult result) {
236238
assertEquals(1, outcome.outputs().get("count"));
237239
}
238240

241+
@Test
242+
void stoppedControlSkipsOutputRepairAndPropagatesTheStop() throws Exception {
243+
try (AgentExecutionContext context = context()) {
244+
ScriptedClient client = new ScriptedClient(List.of(response(ChatMessage.assistant("not json"), List.of(), 1))) {
245+
public synchronized CompletionStage<ChatResponse> call(ChatRequest request) {
246+
context.control().cancel(); // the run is stopped while its terminal turn is produced
247+
return super.call(request);
248+
}
249+
};
250+
AtomicInteger repairs = new AtomicInteger();
251+
ChatClient repairClient = new ChatClient() {
252+
public CompletionStage<ChatResponse> call(ChatRequest request) {
253+
repairs.incrementAndGet();
254+
throw new AssertionError("the repair client must not be called");
255+
}
256+
257+
public Flow.Publisher<ChatEvent> stream(ChatRequest request) {
258+
throw new UnsupportedOperationException();
259+
}
260+
261+
public ChatClientCapabilities capabilities() {
262+
return ChatClientCapabilities.basic();
263+
}
264+
};
265+
ReActAgent agent = ReActAgent.builder(client)
266+
.outputSchema("{\"type\":\"object\",\"required\":[\"status\"],"
267+
+ "\"additionalProperties\":false,\"properties\":{\"status\":{\"type\":\"string\"}}}")
268+
.outputFinalizer(new StructuredOutputFinalizer(repairClient))
269+
.build();
270+
271+
ExecutionStoppedException stopped = assertThrows(ExecutionStoppedException.class,
272+
() -> agent.invoke(request(), context).get(3, TimeUnit.SECONDS));
273+
274+
assertEquals(ExecutionStoppedException.Reason.CANCELLED, stopped.reason());
275+
assertEquals(0, repairs.get());
276+
}
277+
}
278+
239279
private static AgentRequest request() {
240280
return AgentRequest.messages(List.of(ChatMessage.user("hello")));
241281
}

0 commit comments

Comments
 (0)