1818import java .util .ArrayList ;
1919import java .util .List ;
2020import 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 ;
2125import java .util .stream .Collectors ;
2226
2327import com .networknt .schema .Error ;
3438import io .github .agentic .ai .api .chat .ToolChoice ;
3539import io .github .agentic .ai .api .chat .Usage ;
3640import io .github .agentic .ai .agent .AgentResult ;
41+ import io .github .agentic .ai .runtime .execution .ExecutionControl ;
3742import tools .jackson .core .StreamReadFeature ;
3843import tools .jackson .databind .DeserializationFeature ;
3944import tools .jackson .databind .JsonNode ;
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 */
7188public 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.\n Previous 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}
0 commit comments