Skip to content

Commit b5ad401

Browse files
committed
fix(agent): position-aware tool result pairing and documented budget ordering (issue #137 review)
1 parent 210f465 commit b5ad401

4 files changed

Lines changed: 172 additions & 16 deletions

File tree

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,18 @@ public static Builder builder() {
6969
return new Builder();
7070
}
7171

72+
/**
73+
* Ordering contract: this interceptor must be registered **after** (i.e. more
74+
* innermost than) every interceptor that rewrites the request. The budget is
75+
* checked against the request as seen at this interceptor's position in the
76+
* chain — an outer rewrite that grows the request after the budget check has
77+
* passed would bypass the gate (a chain-level regression test documents this).
78+
* Terminal, non-bypassable enforcement belongs to the runtime dispatch (see
79+
* issue #137 discussion).
80+
*/
81+
public static final String ORDERING_CONTRACT = "register the context budget interceptor"
82+
+ " after every request-rewriting interceptor";
83+
7284
@Override
7385
public ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler) {
7486
Objects.requireNonNull(request, "request must not be null");

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

Lines changed: 39 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,12 @@
1919
import io.github.agentic.ai.api.chat.ChatRole;
2020
import io.github.agentic.ai.api.chat.ToolCall;
2121

22+
import java.util.ArrayList;
2223
import java.util.HashMap;
23-
import java.util.LinkedHashSet;
2424
import java.util.List;
2525
import java.util.Map;
2626
import java.util.Objects;
2727
import java.util.Optional;
28-
import java.util.Set;
2928

3029
/**
3130
* Validates that the tool calls of a conversation and their results stay paired.
@@ -34,7 +33,9 @@
3433
* Compression may remove a message. When it removes a tool result, the assistant
3534
* message which requested the tool call is left with an unanswered call; when it
3635
* removes the assistant message, the tool result is left without a call. Both break
37-
* the conversation, so the budget gate refuses to dispatch such a request.
36+
* the conversation, so the budget gate refuses to dispatch such a request. The
37+
* validation is position-aware: a result must follow the assistant message which
38+
* requested the call, and neither calls nor results may repeat.
3839
*/
3940
public final class ToolCallPairingValidator {
4041

@@ -59,7 +60,17 @@ public enum Kind {
5960
/**
6061
* The same tool call appears more than once.
6162
*/
62-
DUPLICATE_TOOL_CALL
63+
DUPLICATE_TOOL_CALL,
64+
65+
/**
66+
* The same tool result appears more than once.
67+
*/
68+
DUPLICATE_TOOL_RESULT,
69+
70+
/**
71+
* A tool result appears before the assistant message which requested the call.
72+
*/
73+
RESULT_BEFORE_CALL
6374
}
6475

6576
/**
@@ -90,34 +101,46 @@ public record Violation(Kind kind, String toolCallId) {
90101
public static Optional<Violation> validate(List<ChatMessage> messages) {
91102
Objects.requireNonNull(messages, "messages must not be null");
92103
Map<String, Integer> callCounts = new HashMap<>();
93-
Set<String> calls = new LinkedHashSet<>();
94-
for (ChatMessage message : messages) {
104+
Map<String, Integer> callFirstIndex = new HashMap<>();
105+
Map<String, List<Integer>> resultIndexes = new HashMap<>();
106+
for (int index = 0; index < messages.size(); index++) {
107+
ChatMessage message = messages.get(index);
95108
for (ToolCall call : message.toolCalls()) {
96109
if (call.id() == null) {
97110
continue;
98111
}
99112
callCounts.merge(call.id(), 1, Integer::sum);
100-
calls.add(call.id());
113+
callFirstIndex.putIfAbsent(call.id(), index);
114+
}
115+
if (message.role() == ChatRole.TOOL && message.toolCallId() != null) {
116+
resultIndexes.computeIfAbsent(message.toolCallId(), key -> new ArrayList<>())
117+
.add(index);
101118
}
102119
}
103120
for (Map.Entry<String, Integer> call : callCounts.entrySet()) {
104121
if (call.getValue() > 1) {
105122
return Optional.of(new Violation(Kind.DUPLICATE_TOOL_CALL, call.getKey()));
106123
}
107124
}
108-
Set<String> results = new LinkedHashSet<>();
109-
for (ChatMessage message : messages) {
110-
if (message.role() == ChatRole.TOOL && message.toolCallId() != null) {
111-
results.add(message.toolCallId());
125+
for (Map.Entry<String, List<Integer>> result : resultIndexes.entrySet()) {
126+
if (result.getValue().size() > 1) {
127+
return Optional.of(new Violation(Kind.DUPLICATE_TOOL_RESULT, result.getKey()));
112128
}
113129
}
114-
for (String result : results) {
115-
if (!calls.contains(result)) {
116-
return Optional.of(new Violation(Kind.UNKNOWN_TOOL_RESULT, result));
130+
for (Map.Entry<String, List<Integer>> result : resultIndexes.entrySet()) {
131+
Integer callIndex = callFirstIndex.get(result.getKey());
132+
if (callIndex == null) {
133+
return Optional.of(new Violation(Kind.UNKNOWN_TOOL_RESULT, result.getKey()));
134+
}
135+
// A result must follow the assistant message which requested the call:
136+
// a compacted history that moves a result in front of its call would
137+
// otherwise reach the provider.
138+
if (result.getValue().get(0) < callIndex) {
139+
return Optional.of(new Violation(Kind.RESULT_BEFORE_CALL, result.getKey()));
117140
}
118141
}
119-
for (String call : calls) {
120-
if (!results.contains(call)) {
142+
for (String call : callCounts.keySet()) {
143+
if (!resultIndexes.containsKey(call)) {
121144
return Optional.of(new Violation(Kind.MISSING_TOOL_RESULT, call));
122145
}
123146
}

‎argi-agent/argi-agent-api/src/test/java/io/github/agentic/ai/agent/budget/ContextBudgetInterceptorTest.java‎

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

18+
import io.github.agentic.ai.agent.interceptor.ModelInterceptor;
19+
import io.github.agentic.ai.agent.interceptor.ModelCallHandler;
1820
import io.github.agentic.ai.agent.interceptor.ModelRequest;
1921
import io.github.agentic.ai.agent.interceptor.ModelResponse;
2022
import io.github.agentic.ai.api.chat.ChatMessage;
@@ -56,6 +58,40 @@ void theEstimateCoversSystemMessagesToolSchemasAndTheOutputReserve() {
5658
assertThat(estimate.accuracy()).isEqualTo(EstimationAccuracy.APPROXIMATE);
5759
}
5860

61+
// issue #137 review: the budget must hold after interceptor rewrites, so the
62+
// budget interceptor has to sit **after** every request-rewriting interceptor
63+
// in the chain (innermost). This chain-level case registers [rewriter, budget]:
64+
// a small request passes the rewriter, grows beyond the window, and must be
65+
// refused before reaching the provider.
66+
@Test
67+
void budgetStillGuardsAfterARequestRewritingInterceptor() throws Exception {
68+
AtomicInteger dispatches = new AtomicInteger();
69+
ModelInterceptor rewriter = new ModelInterceptor() {
70+
public String getName() {
71+
return "rewriter";
72+
}
73+
74+
public ModelResponse interceptModel(ModelRequest request, ModelCallHandler next) {
75+
// Rewrites the small incoming request into an oversized one.
76+
return next.call(longRequest());
77+
}
78+
};
79+
ContextBudgetInterceptor budget = ContextBudgetInterceptor.builder()
80+
.budget(new ContextWindowBudget(20, 5))
81+
.build();
82+
// Registration order: the rewriter outermost, the budget innermost (the
83+
// terminal position, right before the dispatch).
84+
ModelCallHandler chain = request -> {
85+
dispatches.incrementAndGet();
86+
return response();
87+
};
88+
ModelCallHandler budgetHandler = request -> budget.interceptModel(request, chain);
89+
ModelCallHandler fullChain = request -> rewriter.interceptModel(request, budgetHandler);
90+
91+
assertThatThrownBy(() -> fullChain.call(request()))
92+
.isInstanceOf(ContextWindowBudgetExceededException.class);
93+
assertThat(dispatches).hasValue(0);
94+
}
5995
@Test
6096
void anOversizedRequestIsNeverDispatched() {
6197
AtomicInteger dispatches = new AtomicInteger();
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
/*
2+
* Copyright 2026 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.github.agentic.ai.agent.budget;
17+
18+
import io.github.agentic.ai.api.chat.ChatMessage;
19+
import io.github.agentic.ai.api.chat.ToolCall;
20+
import org.junit.jupiter.api.Test;
21+
22+
import java.util.List;
23+
24+
import static org.assertj.core.api.Assertions.assertThat;
25+
26+
/**
27+
* Position-aware pairing validation: a result must follow the assistant message
28+
* which requested the call, and neither calls nor results may repeat (issue #137
29+
* review).
30+
*/
31+
class ToolCallPairingValidatorTest {
32+
33+
@Test
34+
void aWellPairedConversationPasses() {
35+
List<ChatMessage> messages = List.of(
36+
ChatMessage.assistant("use", List.of(new ToolCall("call-1", "lookup", "{}"))),
37+
ChatMessage.tool("call-1", "lookup", "lookup result"));
38+
39+
assertThat(ToolCallPairingValidator.validate(messages)).isEmpty();
40+
}
41+
42+
@Test
43+
void aResultBeforeItsCallIsRejected() {
44+
List<ChatMessage> messages = List.of(
45+
ChatMessage.tool("call-1", "lookup", "lookup result"),
46+
ChatMessage.assistant("use", List.of(new ToolCall("call-1", "lookup", "{}"))));
47+
48+
assertThat(ToolCallPairingValidator.validate(messages))
49+
.contains(new ToolCallPairingValidator.Violation(
50+
ToolCallPairingValidator.Kind.RESULT_BEFORE_CALL, "call-1"));
51+
}
52+
53+
@Test
54+
void aDuplicatedResultIsRejected() {
55+
List<ChatMessage> messages = List.of(
56+
ChatMessage.assistant("use", List.of(new ToolCall("call-1", "lookup", "{}"))),
57+
ChatMessage.tool("call-1", "lookup", "lookup result"),
58+
ChatMessage.tool("call-1", "lookup", "lookup result"));
59+
60+
assertThat(ToolCallPairingValidator.validate(messages))
61+
.contains(new ToolCallPairingValidator.Violation(
62+
ToolCallPairingValidator.Kind.DUPLICATE_TOOL_RESULT, "call-1"));
63+
}
64+
65+
@Test
66+
void aMissingResultIsStillRejected() {
67+
List<ChatMessage> messages = List.of(
68+
ChatMessage.assistant("use", List.of(new ToolCall("call-1", "lookup", "{}"))));
69+
70+
assertThat(ToolCallPairingValidator.validate(messages))
71+
.contains(new ToolCallPairingValidator.Violation(
72+
ToolCallPairingValidator.Kind.MISSING_TOOL_RESULT, "call-1"));
73+
}
74+
75+
@Test
76+
void anOrphanedResultIsStillRejected() {
77+
List<ChatMessage> messages = List.of(
78+
ChatMessage.tool("call-1", "lookup", "lookup result"));
79+
80+
assertThat(ToolCallPairingValidator.validate(messages))
81+
.contains(new ToolCallPairingValidator.Violation(
82+
ToolCallPairingValidator.Kind.UNKNOWN_TOOL_RESULT, "call-1"));
83+
}
84+
85+
}

0 commit comments

Comments
 (0)