pi-braid 0.43.7 → 0.43.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +39 -0
- package/TOOLS.md +1 -1
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
- package/dist/extensions/core/skills-tool/index.js +20 -2
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
- package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
- package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
- package/dist/extensions/core/skills-tool/session-records.js +141 -5
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
- package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
- package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
- package/dist/extensions/enforcement/verification-judge.js +28 -21
- package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
- package/dist/extensions/memory/session-recall/ask.js +376 -0
- package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
- package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
- package/dist/extensions/memory/session-recall/index.js +173 -21
- package/dist/extensions/memory/session-recall/search.d.ts +29 -0
- package/dist/extensions/memory/session-recall/search.js +42 -9
- package/dist/lib/ai/payload-hygiene.d.ts +3 -0
- package/dist/lib/ai/payload-hygiene.js +34 -2
- package/dist/lib/config/braid-paths.d.ts +4 -0
- package/dist/lib/config/braid-paths.js +6 -0
- package/dist/lib/config/braid-settings.d.ts +22 -0
- package/dist/lib/config/braid-settings.js +15 -0
- package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
- package/dist/lib/detection/tool-loop-detector.js +288 -180
- package/dist/lib/reasoning/dreamer.d.ts +2 -1
- package/dist/lib/reasoning/dreamer.js +12 -7
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -0
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -2
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
- package/src/extensions/core/skills-tool/index.ts +21 -1
- package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
- package/src/extensions/core/skills-tool/session-records.ts +201 -9
- package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
- package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
- package/src/extensions/enforcement/verification-judge.ts +32 -25
- package/src/extensions/memory/AGENTS.md +2 -2
- package/src/extensions/memory/session-recall/AGENTS.md +92 -18
- package/src/extensions/memory/session-recall/ask.ts +435 -0
- package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
- package/src/extensions/memory/session-recall/index.ts +202 -21
- package/src/extensions/memory/session-recall/search.ts +61 -10
- package/src/lib/ai/payload-hygiene.ts +47 -3
- package/src/lib/config/braid-paths.ts +7 -0
- package/src/lib/config/braid-settings.ts +42 -3
- package/src/lib/detection/AGENTS.md +8 -7
- package/src/lib/detection/tool-loop-detector.ts +339 -195
- package/src/lib/reasoning/dreamer.ts +13 -6
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Tool Loop Detector - single source of truth for "agent stuck
|
|
3
|
-
* the same
|
|
2
|
+
* Tool Loop Detector - single source of truth for "agent stuck repeating
|
|
3
|
+
* the same call".
|
|
4
4
|
*
|
|
5
5
|
* One detector, one threshold, one window, one cooldown, one remedy.
|
|
6
6
|
* Consumers (turn-outcome, dreamer, policy-rules) call detectToolLoop()
|
|
@@ -15,26 +15,44 @@
|
|
|
15
15
|
* The two paths share a tryClaim-based dedup so only ONE whisper
|
|
16
16
|
* per loop event reaches the agent.
|
|
17
17
|
*
|
|
18
|
+
* IDENTITY, NOT NAME. A recorded call carries the tool name and an
|
|
19
|
+
* identity built from the arguments (toolCallIdentity). Sixteen `bash`
|
|
20
|
+
* calls running sixteen different commands are a chain of work: the agent
|
|
21
|
+
* is exploring, testing, committing, and nothing repeats. Sixteen runs of
|
|
22
|
+
* the same command are a repeat, and sixteen turns of that same command
|
|
23
|
+
* are a loop across turns. Name-only counting could not tell those apart,
|
|
24
|
+
* which is why the detector used to accuse a chain of work at the same
|
|
25
|
+
* threshold as a repeat. Measured over 672 stored accusations before the
|
|
26
|
+
* change: 667 had a tail of twenty distinct calls under one name, none was
|
|
27
|
+
* an identical repeat.
|
|
28
|
+
*
|
|
18
29
|
* STATE LIFECYCLE:
|
|
19
30
|
* - getToolLoopState(ctx) returns the per-session state via
|
|
20
31
|
* getExtensionState. Resets on session_start, no manual reset
|
|
21
32
|
* needed.
|
|
22
|
-
* - recordToolCall() is called from the tool_call
|
|
23
|
-
* with the
|
|
33
|
+
* - recordToolCall(state, toolName, input) is called from the tool_call
|
|
34
|
+
* event handler with the call's arguments.
|
|
24
35
|
* - recordTurnEnd() is called from turn_end to bump the counter
|
|
25
36
|
* used for cooldown comparison.
|
|
26
37
|
* - detectToolLoop() reads the state and returns the verdict.
|
|
27
38
|
*
|
|
28
39
|
* THRESHOLDS (one of each - change here, change everywhere):
|
|
29
|
-
* - TOOL_LOOP_THRESHOLD: 16 consecutive
|
|
30
|
-
*
|
|
40
|
+
* - TOOL_LOOP_THRESHOLD: 16 consecutive calls with one identity, or 16
|
|
41
|
+
* strictly alternating calls of two identities, or one identity across
|
|
42
|
+
* 16 consecutive turns
|
|
43
|
+
* - TOOL_LOOP_WINDOW: 20 calls of history kept
|
|
31
44
|
* - TOOL_LOOP_COOLDOWN_TURNS: 8 turns between emissions
|
|
45
|
+
* - TOOL_TURN_WINDOW: 20 turns of per-turn history kept (the cross-turn
|
|
46
|
+
* shape needs 16 consecutive turns, so this bound is in turns)
|
|
32
47
|
*
|
|
33
|
-
* 16 catches
|
|
34
|
-
*
|
|
35
|
-
*
|
|
48
|
+
* 16 catches the same call returning sixteen times. It does not catch a chain
|
|
49
|
+
* of work that happens to use one tool, which is the whole point of the
|
|
50
|
+
* identity rule: reading several files, running a build, a commit, and a grep
|
|
51
|
+
* are different calls.
|
|
36
52
|
*
|
|
37
|
-
* Only
|
|
53
|
+
* Only this file decides a loop. The whisper that reaches the agent is the
|
|
54
|
+
* enforcement handler's, driven by this verdict; the analytics and dreamer
|
|
55
|
+
* paths keep their observations and deliver nothing. If any intentional
|
|
38
56
|
* (metacognitive) tool - think, verify, verify_claim, finalize,
|
|
39
57
|
* hypothesize, scratchpad, memory, memory_store, repl - appears anywhere
|
|
40
58
|
* in the recorded window, the agent is engaged, not stuck, and
|
|
@@ -42,20 +60,38 @@
|
|
|
42
60
|
* Per-episode single delivery is enforced here by markLoopFired() + the
|
|
43
61
|
* 8-turn TOOL_LOOP_COOLDOWN_TURNS gate, and the whisper never wakes the
|
|
44
62
|
* agent (triggerTurn:false, see enforcement/handlers/turn-end-handler.ts).
|
|
63
|
+
*
|
|
64
|
+
* The whisper states what was observed - the same call, with identical
|
|
65
|
+
* arguments, repeated - and never claims the absence of progress, which
|
|
66
|
+
* this module cannot see.
|
|
45
67
|
*/
|
|
46
68
|
|
|
47
69
|
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
48
70
|
import { getExtensionState } from "../state/extension-state.js";
|
|
71
|
+
import { hashForDedup } from "../utils/dedup.js";
|
|
49
72
|
|
|
50
|
-
/** Minimum consecutive same-
|
|
73
|
+
/** Minimum consecutive same-identity calls (or turns) in the recent history to flag. */
|
|
51
74
|
export const TOOL_LOOP_THRESHOLD = 16;
|
|
52
75
|
|
|
53
|
-
/** How many recent
|
|
76
|
+
/** How many recent calls to retain in the rolling window. Must be >= TOOL_LOOP_THRESHOLD + 1. */
|
|
54
77
|
export const TOOL_LOOP_WINDOW = 20;
|
|
55
78
|
|
|
56
79
|
/** Minimum turns between successive loop whispers. */
|
|
57
80
|
export const TOOL_LOOP_COOLDOWN_TURNS = 8;
|
|
58
81
|
|
|
82
|
+
/** How many turns of per-turn history to retain. A cross-turn loop needs
|
|
83
|
+
* TOOL_LOOP_THRESHOLD consecutive turns, so the bound is turn-shaped rather
|
|
84
|
+
* than call-shaped: bounding the total call count would evict the older turns
|
|
85
|
+
* of a busy agent and hide the very run the cross-turn shape looks for. Each
|
|
86
|
+
* turn's own call list is bounded by TOOL_LOOP_WINDOW. */
|
|
87
|
+
export const TOOL_TURN_WINDOW = TOOL_LOOP_THRESHOLD + 4;
|
|
88
|
+
|
|
89
|
+
/** Longest argument string kept verbatim in an identity. Longer values are
|
|
90
|
+
* replaced by a digest plus their length: a heredoc command runs to thousands
|
|
91
|
+
* of characters and would otherwise be retained twenty times over, while
|
|
92
|
+
* equality - the only thing the detector reads - survives the digest. */
|
|
93
|
+
const MAX_IDENTITY_VALUE_CHARS = 80;
|
|
94
|
+
|
|
59
95
|
// Intentional-use filter: metacognitive tools that prove the agent is
|
|
60
96
|
// engaged, not stuck. If any of these appears in the recorded window, the
|
|
61
97
|
// agent is deliberately reflecting/verifying/closing-out, not mechanically
|
|
@@ -73,44 +109,50 @@ const INTENTIONAL_TOOLS = new Set([
|
|
|
73
109
|
"repl",
|
|
74
110
|
]);
|
|
75
111
|
|
|
76
|
-
/**
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
112
|
+
/** One recorded call: the tool, and the equality key for its arguments. */
|
|
113
|
+
export interface ToolCallRecord {
|
|
114
|
+
tool: string;
|
|
115
|
+
identity: string;
|
|
80
116
|
}
|
|
81
117
|
|
|
82
|
-
/**
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
118
|
+
/** A call to score, or a bare tool name. A bare name is what a caller has when
|
|
119
|
+
* it kept only names (the dreamer's historical log): it carries no argument
|
|
120
|
+
* evidence, so it cannot show that two calls are the same call. See
|
|
121
|
+
* detectToolLoopFromSequence for what that rules out. */
|
|
122
|
+
export type ToolCallLike = string | ToolCallRecord;
|
|
123
|
+
|
|
124
|
+
/** One turn's recorded calls, most recent turn first in ToolLoopState.perTurn. */
|
|
125
|
+
export interface ToolTurn {
|
|
126
|
+
/** Tool names seen in this turn - what the intentional-use filter reads. */
|
|
127
|
+
tools: Set<string>;
|
|
128
|
+
/** This turn's calls, oldest first, capped at TOOL_LOOP_WINDOW. */
|
|
129
|
+
calls: ToolCallRecord[];
|
|
90
130
|
}
|
|
91
131
|
|
|
92
132
|
export interface ToolLoopState {
|
|
93
|
-
/**
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
*
|
|
100
|
-
|
|
101
|
-
* shifted when exceeding WINDOW. */
|
|
102
|
-
history: string[];
|
|
133
|
+
/** Calls per turn, most recent turn first. Turn boundaries are kept so a
|
|
134
|
+
* cross-turn loop (the same call every turn) can be scored separately from
|
|
135
|
+
* an intra-turn repeat, whose window spans the flat history below. */
|
|
136
|
+
perTurn: ToolTurn[];
|
|
137
|
+
/** Ordered flat history of the last TOOL_LOOP_WINDOW calls. Used for
|
|
138
|
+
* identity-run detection: consecutive calls that are the same call,
|
|
139
|
+
* whether within one turn or across turns. */
|
|
140
|
+
history: ToolCallRecord[];
|
|
103
141
|
/** Turn index when we last emitted a loop whisper. -1 if never. */
|
|
104
142
|
lastFiredAtTurn: number;
|
|
105
143
|
/** Monotonically increasing turn counter for cooldown math. */
|
|
106
144
|
turnCount: number;
|
|
107
145
|
}
|
|
108
146
|
|
|
147
|
+
/** Which shape of repetition produced the verdict. */
|
|
148
|
+
export type ToolLoopPattern = "repeat" | "alternation" | "cross-turn" | "";
|
|
149
|
+
|
|
109
150
|
export interface ToolLoopResult {
|
|
110
151
|
isLoop: boolean;
|
|
111
152
|
tool: string;
|
|
112
153
|
count: number;
|
|
113
154
|
message: string;
|
|
155
|
+
pattern: ToolLoopPattern;
|
|
114
156
|
}
|
|
115
157
|
|
|
116
158
|
export function createToolLoopState(): ToolLoopState {
|
|
@@ -127,27 +169,74 @@ export function getToolLoopState(ctx: ExtensionContext): ToolLoopState {
|
|
|
127
169
|
}
|
|
128
170
|
|
|
129
171
|
/**
|
|
130
|
-
*
|
|
131
|
-
*
|
|
132
|
-
* tool set. If no turn has started yet, creates one.
|
|
172
|
+
* Normalize an argument value for equality: whitespace collapsed, object keys
|
|
173
|
+
* sorted (argument order is not identity), long strings digested.
|
|
133
174
|
*/
|
|
134
|
-
|
|
135
|
-
if (
|
|
136
|
-
|
|
137
|
-
|
|
175
|
+
function normalizeArgValue(value: unknown): unknown {
|
|
176
|
+
if (typeof value === "string") {
|
|
177
|
+
const collapsed = value.replace(/\s+/g, " ").trim();
|
|
178
|
+
return collapsed.length > MAX_IDENTITY_VALUE_CHARS
|
|
179
|
+
? `#${hashForDedup(collapsed)}:${collapsed.length}`
|
|
180
|
+
: collapsed;
|
|
138
181
|
}
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
182
|
+
if (Array.isArray(value)) return value.map(normalizeArgValue);
|
|
183
|
+
if (value && typeof value === "object") {
|
|
184
|
+
const out: Record<string, unknown> = {};
|
|
185
|
+
const source = value as Record<string, unknown>;
|
|
186
|
+
for (const key of Object.keys(source).sort()) {
|
|
187
|
+
const normalized = normalizeArgValue(source[key]);
|
|
188
|
+
if (normalized !== undefined) out[key] = normalized;
|
|
189
|
+
}
|
|
190
|
+
return out;
|
|
148
191
|
}
|
|
149
|
-
|
|
150
|
-
|
|
192
|
+
return value;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Build the equality key for one tool call: the tool name plus its normalized
|
|
197
|
+
* arguments. Two calls share an identity exactly when they are the same call -
|
|
198
|
+
* same tool, same arguments - which is what "the agent repeated itself" means.
|
|
199
|
+
*
|
|
200
|
+
* A call whose arguments are absent or empty is identified by its name alone;
|
|
201
|
+
* there is no argument evidence to distinguish it from another call of the
|
|
202
|
+
* same tool, so they count as the same call.
|
|
203
|
+
*/
|
|
204
|
+
export function toolCallIdentity(toolName: string, input?: unknown): string {
|
|
205
|
+
if (!toolName) return "";
|
|
206
|
+
if (input === undefined || input === null) return toolName;
|
|
207
|
+
const normalized = normalizeArgValue(input);
|
|
208
|
+
const serialized = JSON.stringify(normalized);
|
|
209
|
+
if (!serialized || serialized === "{}" || serialized === "null") return toolName;
|
|
210
|
+
return `${toolName} ${serialized}`;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
function openTurn(): ToolTurn {
|
|
214
|
+
return { tools: new Set<string>(), calls: [] };
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** Drop whole turns from the oldest end past the per-turn window. */
|
|
218
|
+
function trimPerTurn(state: ToolLoopState): void {
|
|
219
|
+
while (state.perTurn.length > TOOL_TURN_WINDOW) state.perTurn.pop();
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Record a tool invocation. Call this from the tool_call event handler with
|
|
224
|
+
* the tool name and its arguments. Adds the call to the current (most recent)
|
|
225
|
+
* turn. If no turn has started yet, creates one.
|
|
226
|
+
*/
|
|
227
|
+
export function recordToolCall(state: ToolLoopState, toolName: string, input?: unknown): void {
|
|
228
|
+
if (!toolName) return;
|
|
229
|
+
if (state.perTurn.length === 0) state.perTurn.push(openTurn());
|
|
230
|
+
const turn = state.perTurn[0];
|
|
231
|
+
turn.tools.add(toolName);
|
|
232
|
+
|
|
233
|
+
const record: ToolCallRecord = { tool: toolName, identity: toolCallIdentity(toolName, input) };
|
|
234
|
+
turn.calls.push(record);
|
|
235
|
+
if (turn.calls.length > TOOL_LOOP_WINDOW) turn.calls.shift();
|
|
236
|
+
|
|
237
|
+
trimPerTurn(state);
|
|
238
|
+
|
|
239
|
+
state.history.push(record);
|
|
151
240
|
if (state.history.length > TOOL_LOOP_WINDOW) {
|
|
152
241
|
state.history.shift();
|
|
153
242
|
}
|
|
@@ -156,21 +245,11 @@ export function recordToolCall(state: ToolLoopState, toolName: string): void {
|
|
|
156
245
|
/**
|
|
157
246
|
* Record the end of a turn. Call this from the turn_end handler to
|
|
158
247
|
* bump the counter and open a new turn for the next round of tool calls.
|
|
159
|
-
* Pushes a fresh perTurn entry so the next recordToolCall adds to the new
|
|
160
|
-
* turn's set. History rotation happens in recordToolCall; perTurn entries
|
|
161
|
-
* are trimmed to TOOL_LOOP_WINDOW here.
|
|
162
248
|
*/
|
|
163
249
|
export function recordTurnEnd(state: ToolLoopState): void {
|
|
164
250
|
state.turnCount++;
|
|
165
|
-
state.perTurn.unshift(
|
|
166
|
-
|
|
167
|
-
for (const turn of state.perTurn) {
|
|
168
|
-
totalTools += turn.size;
|
|
169
|
-
}
|
|
170
|
-
while (totalTools > TOOL_LOOP_WINDOW && state.perTurn.length > 1) {
|
|
171
|
-
const removed = state.perTurn.pop()!;
|
|
172
|
-
totalTools -= removed.size;
|
|
173
|
-
}
|
|
251
|
+
state.perTurn.unshift(openTurn());
|
|
252
|
+
trimPerTurn(state);
|
|
174
253
|
}
|
|
175
254
|
|
|
176
255
|
/**
|
|
@@ -182,183 +261,248 @@ export function markLoopFired(state: ToolLoopState): void {
|
|
|
182
261
|
state.lastFiredAtTurn = state.turnCount;
|
|
183
262
|
}
|
|
184
263
|
|
|
264
|
+
/** True when the agent showed any intentional (metacognitive) tool in the
|
|
265
|
+
* recorded history window. History is already capped at TOOL_LOOP_WINDOW. */
|
|
266
|
+
function hasIntentionalToolInHistory(history: ToolCallRecord[]): boolean {
|
|
267
|
+
return history.some((call) => INTENTIONAL_TOOLS.has(call.tool));
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
/** True when any per-turn tool set in the window contains an intentional tool. */
|
|
271
|
+
function hasIntentionalToolInTurns(perTurn: ToolTurn[]): boolean {
|
|
272
|
+
for (const turn of perTurn) {
|
|
273
|
+
for (const tool of turn.tools) {
|
|
274
|
+
if (INTENTIONAL_TOOLS.has(tool)) return true;
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
return false;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/** Length of the run of one identity at the end of the history. */
|
|
281
|
+
function identityTailRun(
|
|
282
|
+
history: ToolCallRecord[],
|
|
283
|
+
): { count: number; call: ToolCallRecord } | null {
|
|
284
|
+
if (history.length === 0) return null;
|
|
285
|
+
const last = history[history.length - 1];
|
|
286
|
+
let count = 1;
|
|
287
|
+
for (let i = history.length - 2; i >= 0; i--) {
|
|
288
|
+
if (history[i].identity === last.identity) count++;
|
|
289
|
+
else break;
|
|
290
|
+
}
|
|
291
|
+
return { count, call: last };
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** Length of a strict two-identity oscillation at the end of the history
|
|
295
|
+
* (A,B,A,B,... - never A,A). Returns null when the last two calls are the
|
|
296
|
+
* same call, which is the repeat path's case, not this one. */
|
|
297
|
+
function alternationTailRun(
|
|
298
|
+
history: ToolCallRecord[],
|
|
299
|
+
): { count: number; a: ToolCallRecord; b: ToolCallRecord } | null {
|
|
300
|
+
if (history.length < 2) return null;
|
|
301
|
+
const a = history[history.length - 1];
|
|
302
|
+
const b = history[history.length - 2];
|
|
303
|
+
if (a.identity === b.identity) return null;
|
|
304
|
+
let count = 2;
|
|
305
|
+
for (let i = history.length - 3; i >= 0; i--) {
|
|
306
|
+
const expected = count % 2 === 0 ? a : b;
|
|
307
|
+
if (history[i].identity === expected.identity) count++;
|
|
308
|
+
else break;
|
|
309
|
+
}
|
|
310
|
+
return { count, a, b };
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
const SUGGESTED_ACTIONS =
|
|
314
|
+
`\n\n**Suggested actions:**\n` +
|
|
315
|
+
`1. Use \`think()\` tool to re-evaluate your approach\n` +
|
|
316
|
+
`2. Check if the problem has changed - you may be solving the wrong issue\n` +
|
|
317
|
+
`3. Consider breaking the task into smaller steps\n` +
|
|
318
|
+
`4. Use the \`memory()\` tool to find past solutions to similar problems`;
|
|
319
|
+
|
|
320
|
+
function repeatMessage(call: ToolCallRecord, count: number, acrossTurns: boolean): string {
|
|
321
|
+
const observed = acrossTurns
|
|
322
|
+
? `the same \`${call.tool}\` call, with identical arguments, ran in ${count} consecutive turns.`
|
|
323
|
+
: `the same \`${call.tool}\` call, with identical arguments, repeated ${count} times in a row.`;
|
|
324
|
+
return `Tool loop detected: ${observed}${SUGGESTED_ACTIONS}`;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
function alternationMessage(a: ToolCallRecord, b: ToolCallRecord, count: number): string {
|
|
328
|
+
const pair =
|
|
329
|
+
a.tool === b.tool
|
|
330
|
+
? `\`${a.tool}\` with two different arguments`
|
|
331
|
+
: `\`${a.tool}\`, \`${b.tool}\``;
|
|
332
|
+
return (
|
|
333
|
+
`Tool loop detected: two calls alternated ${count} times in a row ` +
|
|
334
|
+
`(${pair}), each call identical to its counterpart.` +
|
|
335
|
+
SUGGESTED_ACTIONS
|
|
336
|
+
);
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
const NOT_A_LOOP: ToolLoopResult = { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
340
|
+
|
|
185
341
|
/**
|
|
186
|
-
* Detect a
|
|
187
|
-
*
|
|
188
|
-
* 1. Tail-run (intra-turn): checks the ordered `history` array for N
|
|
189
|
-
* consecutive same-tool calls. Catches the common `read*8` loop even
|
|
190
|
-
* when all calls happen in a single turn. This is the primary path;
|
|
191
|
-
* the test suite and the stateless detectToolLoopFromSequence share
|
|
192
|
-
* the same tail-run semantics.
|
|
193
|
-
*
|
|
194
|
-
* 2. Cross-turn (inter-turn): checks perTurn sets for the same tool
|
|
195
|
-
* appearing in N consecutive turns. Catches loops where the agent
|
|
196
|
-
* calls different tools but always returns to the same one.
|
|
342
|
+
* Detect a loop at the tail of a call sequence. Three shapes:
|
|
197
343
|
*
|
|
198
|
-
*
|
|
199
|
-
*
|
|
200
|
-
*
|
|
344
|
+
* 1. Repeat: one identity at the end of the history, TOOL_LOOP_THRESHOLD or
|
|
345
|
+
* more calls long. The common `read the same file 16 times` loop.
|
|
346
|
+
* 2. Alternation: two identities oscillating strictly (A,B,A,B,...) for
|
|
347
|
+
* TOOL_LOOP_THRESHOLD or more calls. Each call is distinct from the one
|
|
348
|
+
* before it, so only the whole-window shape names this as a loop.
|
|
349
|
+
* 3. Cross-turn: one identity present in TOOL_LOOP_THRESHOLD consecutive
|
|
350
|
+
* turns. Catches an agent that does other work in between but returns to
|
|
351
|
+
* the same call every turn.
|
|
201
352
|
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
353
|
+
* A tail of one tool name whose calls are all distinct is a chain of work and
|
|
354
|
+
* matches none of the three.
|
|
204
355
|
*/
|
|
205
356
|
export function detectToolLoop(state: ToolLoopState): ToolLoopResult {
|
|
206
|
-
// Cooldown gate. Only applies once we've fired at least once
|
|
357
|
+
// Cooldown gate. Only applies once we've fired at least once.
|
|
207
358
|
if (
|
|
208
359
|
state.lastFiredAtTurn >= 0 &&
|
|
209
360
|
state.turnCount - state.lastFiredAtTurn < TOOL_LOOP_COOLDOWN_TURNS
|
|
210
361
|
) {
|
|
211
|
-
return
|
|
362
|
+
return NOT_A_LOOP;
|
|
212
363
|
}
|
|
213
364
|
|
|
214
365
|
// If the agent used any intentional (metacognitive) tool anywhere in the
|
|
215
|
-
// recorded window, it is deliberately engaged, not stuck in a loop.
|
|
216
|
-
//
|
|
217
|
-
//
|
|
218
|
-
// verdict even when the tail still runs 16+ same-tool calls (the
|
|
219
|
-
// false-positive class the 16 threshold guards against).
|
|
366
|
+
// recorded window, it is deliberately engaged, not stuck in a loop. Applies
|
|
367
|
+
// to all three shapes; a think/verify/finalize inside the window kills the
|
|
368
|
+
// loop verdict even when the tail still repeats.
|
|
220
369
|
if (hasIntentionalToolInHistory(state.history) || hasIntentionalToolInTurns(state.perTurn)) {
|
|
221
|
-
return
|
|
370
|
+
return NOT_A_LOOP;
|
|
222
371
|
}
|
|
223
372
|
|
|
224
|
-
// Path 1: tail-run detection (ordered history) - count consecutive
|
|
225
|
-
// same-tool calls at the end of the history array. This matches the
|
|
226
|
-
// stateless detectToolLoopFromSequence semantics.
|
|
227
373
|
if (state.history.length >= TOOL_LOOP_THRESHOLD) {
|
|
228
|
-
const
|
|
229
|
-
|
|
230
|
-
for (let i = state.history.length - 2; i >= 0; i--) {
|
|
231
|
-
if (state.history[i] === last) count++;
|
|
232
|
-
else break;
|
|
233
|
-
}
|
|
234
|
-
if (count >= TOOL_LOOP_THRESHOLD) {
|
|
374
|
+
const repeat = identityTailRun(state.history);
|
|
375
|
+
if (repeat && repeat.count >= TOOL_LOOP_THRESHOLD) {
|
|
235
376
|
return {
|
|
236
377
|
isLoop: true,
|
|
237
|
-
tool:
|
|
238
|
-
count,
|
|
239
|
-
message:
|
|
240
|
-
|
|
241
|
-
`\n\n**Suggested actions:**\n` +
|
|
242
|
-
`1. Use \`think()\` tool to re-evaluate your approach\n` +
|
|
243
|
-
`2. Check if the problem has changed - you may be solving the wrong issue\n` +
|
|
244
|
-
`3. Consider breaking the task into smaller steps\n` +
|
|
245
|
-
`4. Use the \`memory()\` tool to find past solutions to similar problems`,
|
|
378
|
+
tool: repeat.call.tool,
|
|
379
|
+
count: repeat.count,
|
|
380
|
+
message: repeatMessage(repeat.call, repeat.count, false),
|
|
381
|
+
pattern: "repeat",
|
|
246
382
|
};
|
|
247
383
|
}
|
|
248
|
-
}
|
|
249
|
-
|
|
250
|
-
// Only relevant when the agent spans multiple turns with the same tool.
|
|
251
|
-
if (state.perTurn.length < 2) {
|
|
252
|
-
return { isLoop: false, tool: "", count: 0, message: "" };
|
|
253
|
-
}
|
|
254
384
|
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
entry.exclusiveTurns++;
|
|
265
|
-
}
|
|
385
|
+
const alternation = alternationTailRun(state.history);
|
|
386
|
+
if (alternation && alternation.count >= TOOL_LOOP_THRESHOLD) {
|
|
387
|
+
return {
|
|
388
|
+
isLoop: true,
|
|
389
|
+
tool: alternation.a.tool,
|
|
390
|
+
count: alternation.count,
|
|
391
|
+
message: alternationMessage(alternation.a, alternation.b, alternation.count),
|
|
392
|
+
pattern: "alternation",
|
|
393
|
+
};
|
|
266
394
|
}
|
|
267
395
|
}
|
|
268
396
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
397
|
+
// Cross-turn: only relevant when the agent spans multiple turns. Empty
|
|
398
|
+
// turns are transparent: recordTurnEnd() opens the next turn, so the newest
|
|
399
|
+
// entry is empty at detection time by construction, and a turn that made no
|
|
400
|
+
// tool calls carries no evidence either way. A populated turn without the
|
|
401
|
+
// call ends the run.
|
|
402
|
+
const populated = state.perTurn.filter((turn) => turn.calls.length > 0);
|
|
403
|
+
if (populated.length >= 2) {
|
|
404
|
+
let best: { call: ToolCallRecord; turns: number } | null = null;
|
|
405
|
+
const seen = new Set<string>();
|
|
406
|
+
for (const call of populated[0].calls) {
|
|
407
|
+
if (seen.has(call.identity)) continue;
|
|
408
|
+
seen.add(call.identity);
|
|
409
|
+
let turns = 0;
|
|
410
|
+
for (const turn of populated) {
|
|
411
|
+
if (turn.calls.some((c) => c.identity === call.identity)) turns++;
|
|
412
|
+
else break;
|
|
413
|
+
}
|
|
414
|
+
if (!best || turns > best.turns) best = { call, turns };
|
|
277
415
|
}
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
if (turn.has(bestTool)) {
|
|
287
|
-
consecutiveTurns++;
|
|
288
|
-
} else {
|
|
289
|
-
break;
|
|
416
|
+
if (best && best.turns >= TOOL_LOOP_THRESHOLD) {
|
|
417
|
+
return {
|
|
418
|
+
isLoop: true,
|
|
419
|
+
tool: best.call.tool,
|
|
420
|
+
count: best.turns,
|
|
421
|
+
message: repeatMessage(best.call, best.turns, true),
|
|
422
|
+
pattern: "cross-turn",
|
|
423
|
+
};
|
|
290
424
|
}
|
|
291
425
|
}
|
|
292
426
|
|
|
293
|
-
|
|
294
|
-
return { isLoop: false, tool: "", count: 0, message: "" };
|
|
295
|
-
}
|
|
296
|
-
|
|
297
|
-
return {
|
|
298
|
-
isLoop: true,
|
|
299
|
-
tool: bestTool,
|
|
300
|
-
count: consecutiveTurns,
|
|
301
|
-
message:
|
|
302
|
-
`Tool loop detected: \`${bestTool}\` called in ${consecutiveTurns} consecutive turns.` +
|
|
303
|
-
(bestExclusive >= 2
|
|
304
|
-
? ` In ${bestExclusive} of those turns, it was the only tool called.`
|
|
305
|
-
: ``) +
|
|
306
|
-
`\n\n**Suggested actions:**\n` +
|
|
307
|
-
`1. Use \`think()\` tool to re-evaluate your approach\n` +
|
|
308
|
-
`2. Check if the problem has changed - you may be solving the wrong issue\n` +
|
|
309
|
-
`3. Consider breaking the task into smaller steps\n` +
|
|
310
|
-
`4. Use the \`memory()\` tool to find past solutions to similar problems`,
|
|
311
|
-
};
|
|
427
|
+
return NOT_A_LOOP;
|
|
312
428
|
}
|
|
313
429
|
|
|
314
430
|
//
|
|
315
|
-
// The stateful detectToolLoop() above is for callers
|
|
316
|
-
// event handler
|
|
317
|
-
//
|
|
318
|
-
//
|
|
319
|
-
//
|
|
431
|
+
// The stateful detectToolLoop() above is for callers that record calls
|
|
432
|
+
// incrementally (the tool_call event handler and the failure-trace collector).
|
|
433
|
+
// This helper is for callers that hold a complete sequence at hand (the
|
|
434
|
+
// dreamer) and need no cooldown or cross-turn state. Same threshold, same
|
|
435
|
+
// window, same messages.
|
|
436
|
+
//
|
|
437
|
+
// It accepts recorded calls, and it accepts bare tool names for callers that
|
|
438
|
+
// kept only names - and a name is not a call. Sixteen identical names are
|
|
439
|
+
// indistinguishable from sixteen different commands under that name, which is
|
|
440
|
+
// exactly the false accusation this module was rewritten to stop making. A
|
|
441
|
+
// sequence that carries no identities therefore returns NOT a loop: the
|
|
442
|
+
// stateless path can only accuse when it can show the same call repeating, and
|
|
443
|
+
// a caller that wants that verdict must pass what recordToolCall recorded
|
|
444
|
+
// (ToolLoopState.history) rather than a name log.
|
|
320
445
|
|
|
321
446
|
export interface StatelessLoopResult {
|
|
322
447
|
isLoop: boolean;
|
|
323
448
|
tool: string;
|
|
324
449
|
count: number;
|
|
325
450
|
message: string;
|
|
451
|
+
pattern: ToolLoopPattern;
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
/** Narrow a ToolCallLike to a record, or null when it is a bare name. */
|
|
455
|
+
function asRecord(entry: ToolCallLike): ToolCallRecord | null {
|
|
456
|
+
if (typeof entry === "string") return null;
|
|
457
|
+
if (!entry || typeof entry.tool !== "string" || typeof entry.identity !== "string") return null;
|
|
458
|
+
return entry;
|
|
326
459
|
}
|
|
327
460
|
|
|
328
|
-
export function detectToolLoopFromSequence(sequence:
|
|
461
|
+
export function detectToolLoopFromSequence(sequence: ToolCallLike[]): StatelessLoopResult {
|
|
329
462
|
if (sequence.length < TOOL_LOOP_THRESHOLD) {
|
|
330
|
-
return { isLoop: false, tool: "", count: 0, message: "" };
|
|
463
|
+
return { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
331
464
|
}
|
|
332
|
-
// Cap to WINDOW so the check is consistent with the stateful path
|
|
465
|
+
// Cap to WINDOW so the check is consistent with the stateful path.
|
|
333
466
|
const windowed =
|
|
334
467
|
sequence.length > TOOL_LOOP_WINDOW ? sequence.slice(-TOOL_LOOP_WINDOW) : sequence;
|
|
335
468
|
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
469
|
+
const records: ToolCallRecord[] = [];
|
|
470
|
+
for (const entry of windowed) {
|
|
471
|
+
const record = asRecord(entry);
|
|
472
|
+
if (!record) {
|
|
473
|
+
// A bare name is not a call: no argument evidence, no identity.
|
|
474
|
+
return { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
475
|
+
}
|
|
476
|
+
records.push(record);
|
|
341
477
|
}
|
|
342
478
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
else break;
|
|
479
|
+
// Intentional-use filter: any metacognitive tool in the windowed slice means
|
|
480
|
+
// the agent is engaged, not stuck. Mirrors the stateful path.
|
|
481
|
+
if (hasIntentionalToolInHistory(records)) {
|
|
482
|
+
return { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
348
483
|
}
|
|
349
|
-
|
|
350
|
-
|
|
484
|
+
|
|
485
|
+
const repeat = identityTailRun(records);
|
|
486
|
+
if (repeat && repeat.count >= TOOL_LOOP_THRESHOLD) {
|
|
487
|
+
return {
|
|
488
|
+
isLoop: true,
|
|
489
|
+
tool: repeat.call.tool,
|
|
490
|
+
count: repeat.count,
|
|
491
|
+
message: repeatMessage(repeat.call, repeat.count, false),
|
|
492
|
+
pattern: "repeat",
|
|
493
|
+
};
|
|
351
494
|
}
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
495
|
+
|
|
496
|
+
const alternation = alternationTailRun(records);
|
|
497
|
+
if (alternation && alternation.count >= TOOL_LOOP_THRESHOLD) {
|
|
498
|
+
return {
|
|
499
|
+
isLoop: true,
|
|
500
|
+
tool: alternation.a.tool,
|
|
501
|
+
count: alternation.count,
|
|
502
|
+
message: alternationMessage(alternation.a, alternation.b, alternation.count),
|
|
503
|
+
pattern: "alternation",
|
|
504
|
+
};
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
return { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
364
508
|
}
|