@crewhaus/tool-loop-detection 0.3.2 → 0.4.0
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/dist/index.d.ts +55 -1
- package/dist/index.js +74 -0
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -11,6 +11,16 @@
|
|
|
11
11
|
* keys recursively so `{a:1,b:2}` and `{b:2,a:1}` collapse to the same
|
|
12
12
|
* signature.
|
|
13
13
|
*
|
|
14
|
+
* Loop contract 0.4 (G27) adds a NEAR-DUPLICATE tier: calls to the same
|
|
15
|
+
* tool whose inputs differ only in volatile substrings (numbers, UUIDs,
|
|
16
|
+
* hashes, whitespace — the classic "retry with page 2 / a fresh id"
|
|
17
|
+
* churn that defeats exact matching) are grouped under a normalized
|
|
18
|
+
* signature and counted at {@link NEAR_DUPLICATE_WEIGHT} weight. The
|
|
19
|
+
* exact tier is checked first and its behaviour is byte-identical to the
|
|
20
|
+
* pre-0.4 detector; only when no exact signature trips does the weighted
|
|
21
|
+
* near pass run. Deliberately cheap: pure string normalization — no
|
|
22
|
+
* embeddings, no edit distance.
|
|
23
|
+
*
|
|
14
24
|
* No hashing — plain string signatures keep memory tiny (a single
|
|
15
25
|
* detection map per check) and make debug output readable. Cross-turn:
|
|
16
26
|
* the runtime feeds its full per-run tool-use history, so loops that
|
|
@@ -25,20 +35,64 @@ import type { ToolUseBlock } from "@crewhaus/turn-state-machine";
|
|
|
25
35
|
export type LoopDetection = {
|
|
26
36
|
readonly signature: string;
|
|
27
37
|
readonly toolName: string;
|
|
28
|
-
/** How many times the signature appeared inside the window.
|
|
38
|
+
/** How many times the signature appeared inside the window. For the
|
|
39
|
+
* `"near"` tier this is the RAW occurrence count of the normalized
|
|
40
|
+
* group (the weighted score is what crossed `threshold`). */
|
|
29
41
|
readonly count: number;
|
|
30
42
|
readonly windowSize: number;
|
|
31
43
|
readonly threshold: number;
|
|
44
|
+
/**
|
|
45
|
+
* G27 — which detector tripped: `"exact"` for byte-identical
|
|
46
|
+
* `(toolName, input)` repeats (the pre-0.4 behaviour), `"near"` for
|
|
47
|
+
* same-tool calls whose inputs collapse to one normalized signature
|
|
48
|
+
* after volatile-substring stripping, counted at
|
|
49
|
+
* {@link NEAR_DUPLICATE_WEIGHT} weight.
|
|
50
|
+
*/
|
|
51
|
+
readonly tier: "exact" | "near";
|
|
32
52
|
};
|
|
33
53
|
export declare const DEFAULT_WINDOW_SIZE = 10;
|
|
34
54
|
export declare const DEFAULT_THRESHOLD = 3;
|
|
55
|
+
/**
|
|
56
|
+
* G27 — weight of one near-duplicate occurrence relative to an exact
|
|
57
|
+
* repeat. Within a normalized group the score is
|
|
58
|
+
* `maxExact + (groupSize - maxExact) * NEAR_DUPLICATE_WEIGHT`, so at the
|
|
59
|
+
* default threshold (3) five near-duplicates (`1 + 4×0.5`) trip the
|
|
60
|
+
* detector where three exact repeats already would — near matches are
|
|
61
|
+
* suggestive, not conclusive, so they must accumulate more evidence.
|
|
62
|
+
*/
|
|
63
|
+
export declare const NEAR_DUPLICATE_WEIGHT = 0.5;
|
|
35
64
|
/**
|
|
36
65
|
* Look for a `(toolName, input)` pair that occurs at least `threshold`
|
|
37
66
|
* times in the last `windowSize` entries of `history`. Returns the
|
|
38
67
|
* first hit found while scanning the window left-to-right, or `null`
|
|
39
68
|
* if no signature reaches the threshold.
|
|
69
|
+
*
|
|
70
|
+
* Two passes (G27):
|
|
71
|
+
* 1. **exact** — identical to the pre-0.4 detector: first canonical
|
|
72
|
+
* signature whose count reaches `threshold` wins (`tier: "exact"`).
|
|
73
|
+
* 2. **near** — only when pass 1 found nothing: group the window by
|
|
74
|
+
* {@link nearToolCallSignature} (volatile substrings stripped) and
|
|
75
|
+
* return the first group whose weighted score
|
|
76
|
+
* (`maxExact + others × `{@link NEAR_DUPLICATE_WEIGHT}) reaches
|
|
77
|
+
* `threshold` (`tier: "near"`). A group that is all-identical calls
|
|
78
|
+
* never lands here — pass 1 would have caught it.
|
|
40
79
|
*/
|
|
41
80
|
export declare function detectLoop(history: ReadonlyArray<ToolUseBlock>, windowSize?: number, threshold?: number): LoopDetection | null;
|
|
81
|
+
/**
|
|
82
|
+
* G27 — strip the volatile substrings that make near-identical tool
|
|
83
|
+
* inputs hash apart: UUIDs, long hex ids (16–64 chars), digit runs, and
|
|
84
|
+
* whitespace runs each collapse to a fixed placeholder. Pure string →
|
|
85
|
+
* string; exported for tests and for the runtime's warning copy.
|
|
86
|
+
*/
|
|
87
|
+
export declare function stripVolatile(text: string): string;
|
|
88
|
+
/**
|
|
89
|
+
* G27 — the near-tier signature: the same canonical JSON encoding as
|
|
90
|
+
* {@link toolCallSignature} but with every string leaf (and every
|
|
91
|
+
* number, which stringifies to a digit run) passed through
|
|
92
|
+
* {@link stripVolatile}. Joined with `~` instead of `:` so a near
|
|
93
|
+
* signature can never collide with an exact one in a caller's dedup set.
|
|
94
|
+
*/
|
|
95
|
+
export declare function nearToolCallSignature(name: string, input: unknown): string;
|
|
42
96
|
/**
|
|
43
97
|
* Canonical signature for a tool call. The JSON encoding sorts object
|
|
44
98
|
* keys recursively so the same logical input always produces the same
|
package/dist/index.js
CHANGED
|
@@ -1,10 +1,29 @@
|
|
|
1
1
|
export const DEFAULT_WINDOW_SIZE = 10;
|
|
2
2
|
export const DEFAULT_THRESHOLD = 3;
|
|
3
|
+
/**
|
|
4
|
+
* G27 — weight of one near-duplicate occurrence relative to an exact
|
|
5
|
+
* repeat. Within a normalized group the score is
|
|
6
|
+
* `maxExact + (groupSize - maxExact) * NEAR_DUPLICATE_WEIGHT`, so at the
|
|
7
|
+
* default threshold (3) five near-duplicates (`1 + 4×0.5`) trip the
|
|
8
|
+
* detector where three exact repeats already would — near matches are
|
|
9
|
+
* suggestive, not conclusive, so they must accumulate more evidence.
|
|
10
|
+
*/
|
|
11
|
+
export const NEAR_DUPLICATE_WEIGHT = 0.5;
|
|
3
12
|
/**
|
|
4
13
|
* Look for a `(toolName, input)` pair that occurs at least `threshold`
|
|
5
14
|
* times in the last `windowSize` entries of `history`. Returns the
|
|
6
15
|
* first hit found while scanning the window left-to-right, or `null`
|
|
7
16
|
* if no signature reaches the threshold.
|
|
17
|
+
*
|
|
18
|
+
* Two passes (G27):
|
|
19
|
+
* 1. **exact** — identical to the pre-0.4 detector: first canonical
|
|
20
|
+
* signature whose count reaches `threshold` wins (`tier: "exact"`).
|
|
21
|
+
* 2. **near** — only when pass 1 found nothing: group the window by
|
|
22
|
+
* {@link nearToolCallSignature} (volatile substrings stripped) and
|
|
23
|
+
* return the first group whose weighted score
|
|
24
|
+
* (`maxExact + others × `{@link NEAR_DUPLICATE_WEIGHT}) reaches
|
|
25
|
+
* `threshold` (`tier: "near"`). A group that is all-identical calls
|
|
26
|
+
* never lands here — pass 1 would have caught it.
|
|
8
27
|
*/
|
|
9
28
|
export function detectLoop(history, windowSize = DEFAULT_WINDOW_SIZE, threshold = DEFAULT_THRESHOLD) {
|
|
10
29
|
if (history.length === 0 || threshold <= 0)
|
|
@@ -23,6 +42,7 @@ export function detectLoop(history, windowSize = DEFAULT_WINDOW_SIZE, threshold
|
|
|
23
42
|
count: entry.count,
|
|
24
43
|
windowSize,
|
|
25
44
|
threshold,
|
|
45
|
+
tier: "exact",
|
|
26
46
|
};
|
|
27
47
|
}
|
|
28
48
|
}
|
|
@@ -35,12 +55,66 @@ export function detectLoop(history, windowSize = DEFAULT_WINDOW_SIZE, threshold
|
|
|
35
55
|
count: 1,
|
|
36
56
|
windowSize,
|
|
37
57
|
threshold,
|
|
58
|
+
tier: "exact",
|
|
38
59
|
};
|
|
39
60
|
}
|
|
40
61
|
}
|
|
41
62
|
}
|
|
63
|
+
// Near pass — group by normalized signature, score exact-vs-near split.
|
|
64
|
+
// `counts` already holds the per-exact-signature tallies from pass 1.
|
|
65
|
+
const nearGroups = new Map();
|
|
66
|
+
for (const call of window) {
|
|
67
|
+
const nearSig = nearToolCallSignature(call.name, call.input);
|
|
68
|
+
const exactSig = toolCallSignature(call.name, call.input);
|
|
69
|
+
let group = nearGroups.get(nearSig);
|
|
70
|
+
if (!group) {
|
|
71
|
+
group = { count: 0, toolName: call.name, exactCounts: new Map() };
|
|
72
|
+
nearGroups.set(nearSig, group);
|
|
73
|
+
}
|
|
74
|
+
group.count += 1;
|
|
75
|
+
group.exactCounts.set(exactSig, (group.exactCounts.get(exactSig) ?? 0) + 1);
|
|
76
|
+
// A group of ONE distinct exact signature is pass-1 territory (it did
|
|
77
|
+
// not trip there, so it cannot trip here either at <= weight 1).
|
|
78
|
+
if (group.exactCounts.size < 2)
|
|
79
|
+
continue;
|
|
80
|
+
const maxExact = Math.max(...group.exactCounts.values());
|
|
81
|
+
const score = maxExact + (group.count - maxExact) * NEAR_DUPLICATE_WEIGHT;
|
|
82
|
+
if (score >= threshold) {
|
|
83
|
+
return {
|
|
84
|
+
signature: nearSig,
|
|
85
|
+
toolName: group.toolName,
|
|
86
|
+
count: group.count,
|
|
87
|
+
windowSize,
|
|
88
|
+
threshold,
|
|
89
|
+
tier: "near",
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
}
|
|
42
93
|
return null;
|
|
43
94
|
}
|
|
95
|
+
/**
|
|
96
|
+
* G27 — strip the volatile substrings that make near-identical tool
|
|
97
|
+
* inputs hash apart: UUIDs, long hex ids (16–64 chars), digit runs, and
|
|
98
|
+
* whitespace runs each collapse to a fixed placeholder. Pure string →
|
|
99
|
+
* string; exported for tests and for the runtime's warning copy.
|
|
100
|
+
*/
|
|
101
|
+
export function stripVolatile(text) {
|
|
102
|
+
return text
|
|
103
|
+
.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "«uuid»")
|
|
104
|
+
.replace(/\b[0-9a-f]{16,64}\b/gi, "«hex»")
|
|
105
|
+
.replace(/\d+/g, "«n»")
|
|
106
|
+
.replace(/\s+/g, " ");
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* G27 — the near-tier signature: the same canonical JSON encoding as
|
|
110
|
+
* {@link toolCallSignature} but with every string leaf (and every
|
|
111
|
+
* number, which stringifies to a digit run) passed through
|
|
112
|
+
* {@link stripVolatile}. Joined with `~` instead of `:` so a near
|
|
113
|
+
* signature can never collide with an exact one in a caller's dedup set.
|
|
114
|
+
*/
|
|
115
|
+
export function nearToolCallSignature(name, input) {
|
|
116
|
+
return `${name}~${stripVolatile(canonicalJson(input))}`;
|
|
117
|
+
}
|
|
44
118
|
/**
|
|
45
119
|
* Canonical signature for a tool call. The JSON encoding sorts object
|
|
46
120
|
* keys recursively so the same logical input always produces the same
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@crewhaus/tool-loop-detection",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Detect repeated tool calls via sliding-window canonical-JSON signatures",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
"test": "bun test src"
|
|
16
16
|
},
|
|
17
17
|
"dependencies": {
|
|
18
|
-
"@crewhaus/turn-state-machine": "0.
|
|
18
|
+
"@crewhaus/turn-state-machine": "0.4.0"
|
|
19
19
|
},
|
|
20
20
|
"license": "Apache-2.0",
|
|
21
21
|
"author": {
|