@crewhaus/tool-loop-detection 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/tool-loop-detection",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Detect repeated tool calls via sliding-window canonical-JSON signatures",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/turn-state-machine": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-loop-detection"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-loop-detection#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from "bun:test";
+import type { ToolUseBlock } from "@crewhaus/turn-state-machine";
+import { detectLoop, toolCallSignature } from "./index";
+
+function call(name: string, input: unknown = {}, id = `tu_${Math.random()}`): ToolUseBlock {
+  return { id, name, input };
+}
+
+describe("toolCallSignature", () => {
+  test("primitives, arrays, and nested objects are canonical", () => {
+    expect(toolCallSignature("X", 1)).toBe("X:1");
+    expect(toolCallSignature("X", "y")).toBe('X:"y"');
+    expect(toolCallSignature("X", true)).toBe("X:true");
+    expect(toolCallSignature("X", null)).toBe("X:null");
+    expect(toolCallSignature("X", [1, 2, 3])).toBe("X:[1,2,3]");
+  });
+
+  test("object key order does not affect signature", () => {
+    expect(toolCallSignature("X", { a: 1, b: 2 })).toBe(toolCallSignature("X", { b: 2, a: 1 }));
+  });
+
+  test("nested object key order does not affect signature", () => {
+    const a = { outer: { a: 1, b: 2 }, list: [{ x: 1, y: 2 }] };
+    const b = { list: [{ y: 2, x: 1 }], outer: { b: 2, a: 1 } };
+    expect(toolCallSignature("X", a)).toBe(toolCallSignature("X", b));
+  });
+
+  test("escaping handles quotes and newlines", () => {
+    const sig = toolCallSignature("X", { msg: 'he said "hi"\nthen left' });
+    expect(sig).toContain("X:");
+    // Round-trip the JSON portion to ensure it parses cleanly.
+    const json = sig.slice(2);
+    expect(JSON.parse(json)).toEqual({ msg: 'he said "hi"\nthen left' });
+  });
+
+  test("name vs input separation", () => {
+    expect(toolCallSignature("Foo", { a: 1 })).not.toBe(toolCallSignature("Bar", { a: 1 }));
+  });
+
+  test("undefined values collapse to null in canonical form", () => {
+    expect(toolCallSignature("X", undefined)).toBe("X:null");
+  });
+});
+
+describe("detectLoop — basic shapes", () => {
+  test("empty history returns null", () => {
+    expect(detectLoop([])).toBeNull();
+  });
+
+  test("single occurrence with threshold 3 returns null", () => {
+    expect(detectLoop([call("A")])).toBeNull();
+  });
+
+  test("threshold 3, three identical calls in window → detected", () => {
+    const out = detectLoop([
+      call("Bash", { command: "date" }),
+      call("Bash", { command: "date" }),
+      call("Bash", { command: "date" }),
+    ]);
+    expect(out).not.toBeNull();
+    expect(out?.toolName).toBe("Bash");
+    expect(out?.count).toBe(3);
+    expect(out?.signature).toBe('Bash:{"command":"date"}');
+  });
+
+  test("threshold 3, two identical and one different → null", () => {
+    const out = detectLoop([call("A"), call("B"), call("A")]);
+    expect(out).toBeNull();
+  });
+
+  test("interleaved A/B/A/B/A with threshold 3 → detects A", () => {
+    const out = detectLoop([call("A"), call("B"), call("A"), call("B"), call("A")]);
+    expect(out?.toolName).toBe("A");
+    expect(out?.count).toBe(3);
+  });
+
+  test("different inputs do not collapse", () => {
+    const out = detectLoop([
+      call("Read", { path: "a" }),
+      call("Read", { path: "b" }),
+      call("Read", { path: "c" }),
+    ]);
+    expect(out).toBeNull();
+  });
+
+  test("same call but different object key order → still collapses", () => {
+    const out = detectLoop([
+      call("Read", { path: "a", limit: 10 }),
+      call("Read", { limit: 10, path: "a" }),
+      call("Read", { path: "a", limit: 10 }),
+    ]);
+    expect(out?.count).toBe(3);
+    expect(out?.toolName).toBe("Read");
+  });
+});
+
+describe("detectLoop — window slicing", () => {
+  test("only the last windowSize entries count", () => {
+    // Three As at the head, then 10 Bs. windowSize 10 should NOT see the As.
+    const head = [call("A"), call("A"), call("A")];
+    const tail = Array.from({ length: 10 }, () => call("B"));
+    const out = detectLoop([...head, ...tail], 10, 3);
+    expect(out?.toolName).toBe("B");
+  });
+
+  test("threshold can be tuned", () => {
+    expect(detectLoop([call("A"), call("A")], 10, 2)?.count).toBe(2);
+  });
+
+  test("threshold larger than window length → null", () => {
+    expect(detectLoop([call("A"), call("A")], 10, 5)).toBeNull();
+  });
+
+  test("threshold 0 or negative is a no-op", () => {
+    expect(detectLoop([call("A")], 10, 0)).toBeNull();
+    expect(detectLoop([call("A")], 10, -1)).toBeNull();
+  });
+});
+
+describe("detectLoop — early-exit on first hit", () => {
+  test("returns the FIRST signature to hit threshold while scanning the window", () => {
+    // Two competing loops in window: A and B. A's third occurrence should
+    // arrive first and be reported.
+    const out = detectLoop(
+      [call("A"), call("B"), call("A"), call("B"), call("A"), call("B"), call("B")],
+      10,
+      3,
+    );
+    expect(out?.toolName).toBe("A");
+  });
+});

package/src/index.ts

@@ -0,0 +1,114 @@
+/**
+ * Catalog R3 `tool-loop-detection` — flag when the model gets stuck
+ * making the same `(toolName, input)` call over and over. The runtime
+ * runs `detectLoop()` after every batch of tool executions; on a hit
+ * it injects a synthetic warning message so the model can self-correct.
+ *
+ * Detection is a simple sliding-window count. Take the last
+ * `windowSize` tool calls, compute a canonical signature for each
+ * (`toolName + ":" + canonicalJson(input)`), and return the first
+ * signature whose count meets `threshold`. Canonical JSON sorts object
+ * keys recursively so `{a:1,b:2}` and `{b:2,a:1}` collapse to the same
+ * signature.
+ *
+ * No hashing — plain string signatures keep memory tiny (a single
+ * detection map per check) and make debug output readable. Cross-turn:
+ * the runtime feeds its full per-run tool-use history, so loops that
+ * span turns get caught.
+ *
+ * Reference: `openclaw/agents/tool-loop-detection.ts` — uses SHA-256
+ * over a stable-stringified params object plus a 30-call window with
+ * tiered thresholds (10 warning / 20 critical). We collapse to one
+ * threshold and skip the hash.
+ */
+import type { ToolUseBlock } from "@crewhaus/turn-state-machine";
+
+export type LoopDetection = {
+  readonly signature: string;
+  readonly toolName: string;
+  /** How many times the signature appeared inside the window. */
+  readonly count: number;
+  readonly windowSize: number;
+  readonly threshold: number;
+};
+
+export const DEFAULT_WINDOW_SIZE = 10;
+export const DEFAULT_THRESHOLD = 3;
+
+/**
+ * Look for a `(toolName, input)` pair that occurs at least `threshold`
+ * times in the last `windowSize` entries of `history`. Returns the
+ * first hit found while scanning the window left-to-right, or `null`
+ * if no signature reaches the threshold.
+ */
+export function detectLoop(
+  history: ReadonlyArray<ToolUseBlock>,
+  windowSize: number = DEFAULT_WINDOW_SIZE,
+  threshold: number = DEFAULT_THRESHOLD,
+): LoopDetection | null {
+  if (history.length === 0 || threshold <= 0) return null;
+
+  const window = history.length > windowSize ? history.slice(history.length - windowSize) : history;
+
+  const counts = new Map<string, { count: number; toolName: string }>();
+  for (const call of window) {
+    const sig = toolCallSignature(call.name, call.input);
+    const entry = counts.get(sig);
+    if (entry) {
+      entry.count += 1;
+      if (entry.count >= threshold) {
+        return {
+          signature: sig,
+          toolName: entry.toolName,
+          count: entry.count,
+          windowSize,
+          threshold,
+        };
+      }
+    } else {
+      counts.set(sig, { count: 1, toolName: call.name });
+      if (threshold === 1) {
+        return {
+          signature: sig,
+          toolName: call.name,
+          count: 1,
+          windowSize,
+          threshold,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Canonical signature for a tool call. The JSON encoding sorts object
+ * keys recursively so the same logical input always produces the same
+ * string regardless of property order. Arrays preserve order; primitive
+ * leaves use `JSON.stringify` (which already escapes quotes/newlines/
+ * unicode safely).
+ */
+export function toolCallSignature(name: string, input: unknown): string {
+  return `${name}:${canonicalJson(input)}`;
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "null";
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  if (t === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  // bigint, symbol, function — fall through to a stable but obviously-tagged
+  // representation so detection still works.
+  return JSON.stringify(String(value));
+}