@crewhaus/tool-loop-detection 0.3.2 → 0.4.2

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 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.2",
3
+ "version": "0.4.2",
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.3.2"
18
+ "@crewhaus/turn-state-machine": "0.4.2"
19
19
  },
20
20
  "license": "Apache-2.0",
21
21
  "author": {