pi-antiloop 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![Antiloop banner](docs/banner.png)
+![Antiloop banner](https://raw.githubusercontent.com/noguerol/antiloop/main/docs/banner.jpeg)
 
 </div>
 
@@ -233,9 +233,8 @@ antiloop/
 ├── LICENSE             # MIT
 ├── README.md
 ├── docs/
-│   ├── banner.png      # wide README header
-│   └── preview.png     # npm pi.dev preview card
-├── screenshot.png      # full-res master
+│   ├── banner.jpeg      # wide README header
+│   └── preview.jpeg     # npm pi.dev preview card
 └── src/
     └── index.ts        # full extension (≈975 lines)
 ```

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "pi-antiloop",
-  "version": "1.0.0",
-  "description": "A pi extension that detects reasoning/processing loops in any model and forces a break with progressive intervention (warning → force break → abort). Text, tool, thinking and structural similarity detection with configurable thresholds and a self-test command.",
+  "version": "1.0.1",
+  "description": "Antiloop: detect reasoning loops and force a break (warn → force → abort) across text, tool, thinking, and structural patterns.",
   "keywords": [
     "pi-package",
-    "loop-detection",
     "antiloop",
+    "loop-detection",
     "reasoning",
-    "monitoring",
-    "debugging"
+    "monitoring"
   ],
   "author": "Javier Noguerol <https://github.com/noguerol>",
   "license": "MIT",
@@ -24,7 +23,7 @@
     "extensions": [
       "./src/index.ts"
     ],
-    "image": "https://raw.githubusercontent.com/noguerol/antiloop/main/docs/preview.png"
+    "image": "https://raw.githubusercontent.com/noguerol/antiloop/main/docs/preview.jpeg"
   },
   "files": [
     "src"

package/src/commands.ts

@@ -0,0 +1,216 @@
+// antiloop — command handlers. Lazy-loaded on /antiloop.
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { saveConfig } from "./config.ts";
+import type { AntiloopState, Runtime } from "./types.ts";
+import { formatDuration, selectFrom } from "./ui.ts";
+
+export async function handleCommand(
+	args: string | undefined,
+	ctx: ExtensionCommandContext,
+	rt: Runtime,
+): Promise<void> {
+	const sub = (args ?? "").trim().toLowerCase();
+	switch (sub) {
+		case "enable":
+			rt.config.enabled = true;
+			saveConfig(rt.config);
+			ctx.ui.notify("antiloop: ON", "info");
+			rt.updateStatus(ctx);
+			return;
+		case "disable":
+			rt.config.enabled = false;
+			saveConfig(rt.config);
+			ctx.ui.notify("antiloop: OFF", "info");
+			rt.updateStatus(ctx);
+			return;
+		case "status":
+			return showStatus(ctx, rt);
+		case "config":
+			return showConfigMenu(ctx, rt);
+		case "log":
+			return showLog(ctx, rt);
+		case "reset":
+			resetState(rt.state);
+			rt.pendingIntervention = null;
+			ctx.ui.notify("antiloop: reset", "info");
+			rt.updateStatus(ctx);
+			return;
+		case "test":
+			return runSelfTest(ctx);
+		default:
+			rt.config.enabled = !rt.config.enabled;
+			saveConfig(rt.config);
+			ctx.ui.notify(`antiloop: ${rt.config.enabled ? "ON" : "OFF"}`, "info");
+			rt.updateStatus(ctx);
+			return;
+	}
+}
+
+async function showStatus(ctx: ExtensionCommandContext, rt: Runtime): Promise<void> {
+	const lvl = ["none", "warn", "force", "abort"][rt.state.currentLevel];
+	const recent = rt.state.detections.slice(-5);
+	const lines = [
+		`state: ${rt.config.enabled ? "ON" : "OFF"} · level: ${lvl} · consecutive: ${rt.state.consecutiveDetections}`,
+		`total: ${rt.state.totalDetections} · tracked: ${rt.state.recentMessages.length} · forced: ${rt.state.inForcedBreak ? "yes" : "no"}`,
+		"",
+		"thresholds:",
+		`  warn: ${rt.config.warningThreshold}  force: ${rt.config.forceBreakThreshold}  abort: ${rt.config.abortThreshold || "off"}`,
+		`  similarity: ${(rt.config.similarityThreshold * 100).toFixed(0)}%  window: ${rt.config.detectionWindow}`,
+		"",
+		`detectors: text ${yn(rt.config.detectTextLoops)} · tool ${yn(rt.config.detectToolLoops)} · think ${yn(rt.config.detectThinkingLoops)}`,
+	];
+	if (recent.length) {
+		lines.push("", "recent:");
+		for (const d of recent) lines.push(`  [${d.type}] ${d.description} · ${formatDuration(Date.now() - d.timestamp)} ago`);
+	}
+	ctx.ui.notify(lines.join("\n"), "info");
+}
+
+async function showConfigMenu(ctx: ExtensionCommandContext, rt: Runtime): Promise<void> {
+	const c = rt.config;
+	const picked = await selectFrom(ctx, "antiloop config", [
+		{ value: "toggle" as const, label: c.enabled ? "🟢 disable" : "🔴 enable", description: "toggle detection" },
+		{ value: "warn" as const, label: `warn threshold: ${c.warningThreshold}` },
+		{ value: "force" as const, label: `force threshold: ${c.forceBreakThreshold}` },
+		{ value: "abort" as const, label: `abort threshold: ${c.abortThreshold || "off"}`, description: "0 = disabled" },
+		{ value: "sim" as const, label: `similarity: ${(c.similarityThreshold * 100).toFixed(0)}%` },
+		{ value: "window" as const, label: `window: ${c.detectionWindow} msgs` },
+		{ value: "text" as const, label: `text detect: ${yn(c.detectTextLoops)}` },
+		{ value: "tool" as const, label: `tool detect: ${yn(c.detectToolLoops)}` },
+		{ value: "think" as const, label: `think detect: ${yn(c.detectThinkingLoops)}` },
+		{ value: "notify" as const, label: `notify: ${yn(c.notifyOnDetection)}` },
+		{ value: "reset" as const, label: "reset state" },
+	]);
+	if (!picked) return;
+	switch (picked) {
+		case "toggle":
+			c.enabled = !c.enabled;
+			saveConfig(c);
+			ctx.ui.notify(`antiloop: ${c.enabled ? "ON" : "OFF"}`, "info");
+			rt.updateStatus(ctx);
+			break;
+		case "warn": {
+			const v = await selectFrom(ctx, "warn threshold", [
+				{ value: 1, label: "1 (sensitive)" },
+				{ value: 2, label: "2 (default)" },
+				{ value: 3, label: "3" },
+				{ value: 5, label: "5 (relaxed)" },
+			]);
+			if (v !== undefined) { c.warningThreshold = v; saveConfig(c); ctx.ui.notify(`warn: ${v}`, "info"); }
+			break;
+		}
+		case "force": {
+			const v = await selectFrom(ctx, "force threshold", [
+				{ value: 2, label: "2 (sensitive)" },
+				{ value: 3, label: "3 (default)" },
+				{ value: 5, label: "5" },
+				{ value: 8, label: "8 (relaxed)" },
+			]);
+			if (v !== undefined) { c.forceBreakThreshold = v; saveConfig(c); ctx.ui.notify(`force: ${v}`, "info"); }
+			break;
+		}
+		case "abort": {
+			const v = await selectFrom(ctx, "abort threshold (0=off)", [
+				{ value: 0, label: "off" },
+				{ value: 5, label: "5" },
+				{ value: 8, label: "8" },
+				{ value: 10, label: "10" },
+				{ value: 15, label: "15" },
+			]);
+			if (v !== undefined) { c.abortThreshold = v; saveConfig(c); ctx.ui.notify(`abort: ${v || "off"}`, "info"); }
+			break;
+		}
+		case "sim": {
+			const v = await selectFrom(ctx, "similarity", [
+				{ value: 0.5, label: "50% (sensitive)" },
+				{ value: 0.6, label: "60%" },
+				{ value: 0.7, label: "70%" },
+				{ value: 0.75, label: "75% (default)" },
+				{ value: 0.8, label: "80%" },
+				{ value: 0.9, label: "90% (relaxed)" },
+			]);
+			if (v !== undefined) { c.similarityThreshold = v; saveConfig(c); ctx.ui.notify(`similarity: ${(v * 100).toFixed(0)}%`, "info"); }
+			break;
+		}
+		case "window": {
+			const v = await selectFrom(ctx, "window", [
+				{ value: 5, label: "5" },
+				{ value: 10, label: "10 (default)" },
+				{ value: 15, label: "15" },
+				{ value: 20, label: "20" },
+			]);
+			if (v !== undefined) { c.detectionWindow = v; saveConfig(c); ctx.ui.notify(`window: ${v}`, "info"); }
+			break;
+		}
+		case "text":
+			c.detectTextLoops = !c.detectTextLoops; saveConfig(c);
+			ctx.ui.notify(`text: ${yn(c.detectTextLoops)}`, "info"); break;
+		case "tool":
+			c.detectToolLoops = !c.detectToolLoops; saveConfig(c);
+			ctx.ui.notify(`tool: ${yn(c.detectToolLoops)}`, "info"); break;
+		case "think":
+			c.detectThinkingLoops = !c.detectThinkingLoops; saveConfig(c);
+			ctx.ui.notify(`think: ${yn(c.detectThinkingLoops)}`, "info"); break;
+		case "notify":
+			c.notifyOnDetection = !c.notifyOnDetection; saveConfig(c);
+			ctx.ui.notify(`notify: ${yn(c.notifyOnDetection)}`, "info"); break;
+		case "reset":
+			resetState(rt.state);
+			rt.pendingIntervention = null;
+			ctx.ui.notify("reset", "info");
+			rt.updateStatus(ctx);
+			break;
+	}
+}
+
+async function showLog(ctx: ExtensionCommandContext, rt: Runtime): Promise<void> {
+	if (!rt.state.detections.length) {
+		ctx.ui.notify("no detections this session", "info");
+		return;
+	}
+	const items = rt.state.detections.slice(-30).reverse().map((d) => ({
+		value: "" as const,
+		label: `[${d.type}] ${d.description}`,
+		description: `${(d.similarity * 100).toFixed(0)}% · ${formatDuration(Date.now() - d.timestamp)} ago`,
+	}));
+	await selectFrom(ctx, `detections (${rt.state.detections.length} total)`, items);
+}
+
+export function resetState(state: AntiloopState): void {
+	state.recentMessages = [];
+	state.detections = [];
+	state.currentLevel = 0;
+	state.consecutiveDetections = 0;
+	state.inForcedBreak = false;
+	state.totalDetections = 0;
+}
+
+async function runSelfTest(ctx: ExtensionCommandContext): Promise<void> {
+	// Inline similarity + normalize (mirrors detect.ts). Keeps test self-contained
+	// without re-importing private helpers.
+	const norm = (t: string) => t.toLowerCase().replace(/\s+/g, " ").replace(/[^\w\s]/g, "").trim();
+	const cases: Array<{ a: string; b: string; expect: string }> = [
+		{ a: "Hello world", b: "Hello world", expect: "1.00" },
+		{ a: "Hello world", b: "Hello World!", expect: "high" },
+		{ a: "The quick brown fox", b: "The quick brown fox jumps over the lazy dog", expect: "high" },
+		{ a: "Hello world", b: "Goodbye universe", expect: "low" },
+		{ a: "I will read the file first", b: "I will read the file first to understand", expect: "high" },
+	];
+	const out: string[] = [];
+	for (const c of cases) {
+		// Re-implement minimal Levenshtein similarity for the self-test
+		const a = norm(c.a), b = norm(c.b);
+		const max = Math.max(a.length, b.length);
+		let diff = 0;
+		for (let i = 0; i < Math.min(a.length, b.length); i++) if (a[i] !== b[i]) diff++;
+		diff += Math.abs(a.length - b.length);
+		const s = max ? 1 - diff / max : 1;
+		out.push(`"${c.a}" vs "${c.b}" → ${(s * 100).toFixed(0)}% (exp: ${c.expect})`);
+	}
+	ctx.ui.notify(`antiloop self-test\n${out.join("\n")}`, "info");
+}
+
+function yn(b: boolean): string {
+	return b ? "on" : "off";
+}

package/src/config.ts

@@ -0,0 +1,46 @@
+// antiloop — config load/save. Lightweight: only file I/O at session_start.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { AntiloopConfig } from "./types.ts";
+
+export const CONFIG_FILE = "antiloop.json";
+
+export const DEFAULT_CONFIG: AntiloopConfig = {
+	enabled: true,
+	warningThreshold: 2,
+	forceBreakThreshold: 3,
+	abortThreshold: 0,
+	similarityThreshold: 0.75,
+	detectToolLoops: true,
+	detectThinkingLoops: true,
+	detectTextLoops: true,
+	notifyOnDetection: true,
+	maxHistoryEntries: 100,
+	detectionWindow: 10,
+};
+
+export function getConfigPath(): string {
+	return join(getAgentDir(), CONFIG_FILE);
+}
+
+export function loadConfig(): AntiloopConfig {
+	const p = getConfigPath();
+	if (existsSync(p)) {
+		try {
+			return { ...DEFAULT_CONFIG, ...JSON.parse(readFileSync(p, "utf-8")) };
+		} catch (e) {
+			console.error(`[antiloop] config load error: ${e}`);
+		}
+	}
+	return { ...DEFAULT_CONFIG };
+}
+
+export function saveConfig(config: AntiloopConfig): void {
+	try {
+		writeFileSync(getConfigPath(), JSON.stringify(config, null, 2), "utf-8");
+	} catch (e) {
+		console.error(`[antiloop] config save error: ${e}`);
+	}
+}

package/src/detect.ts

@@ -0,0 +1,167 @@
+// antiloop — similarity + detection engine. Lazy-loaded on first message_end.
+
+import type { AntiloopConfig, AntiloopState, LoopDetection } from "./types.ts";
+
+const MIN_CONTENT_LENGTH = 50;
+
+function normalizeText(t: string): string {
+	return t.toLowerCase().replace(/\s+/g, " ").replace(/[^\w\s]/g, "").trim();
+}
+
+function levenshtein(a: string, b: string): number {
+	if (!a.length) return b.length;
+	if (!b.length) return a.length;
+	const m: number[][] = [];
+	for (let i = 0; i <= b.length; i++) m[i] = [i];
+	for (let j = 0; j <= a.length; j++) m[0][j] = j;
+	for (let i = 1; i <= b.length; i++) {
+		for (let j = 1; j <= a.length; j++) {
+			m[i][j] = b.charAt(i - 1) === a.charAt(j - 1)
+				? m[i - 1][j - 1]
+				: Math.min(m[i - 1][j - 1] + 1, m[i][j - 1] + 1, m[i - 1][j] + 1);
+		}
+	}
+	return m[b.length][a.length];
+}
+
+function ngrams(text: string, n: number): Set<string> {
+	const out = new Set<string>();
+	for (let i = 0; i <= text.length - n; i++) out.add(text.substring(i, i + n));
+	return out;
+}
+
+function opening(text: string, n = 10): string {
+	return normalizeText(text.split(/\s+/).slice(0, n).join(" "));
+}
+
+function similarity(a: string, b: string): number {
+	if (a.length < MIN_CONTENT_LENGTH || b.length < MIN_CONTENT_LENGTH) return 0;
+	if (a === b) return 1;
+	const na = normalizeText(a);
+	const nb = normalizeText(b);
+	if (na.length < 20 || nb.length < 20) return 0;
+	if (na === nb) return 1;
+	if (na.length < 100 && nb.length < 100) {
+		const max = Math.max(na.length, nb.length);
+		return 1 - levenshtein(na, nb) / max;
+	}
+	const ga = ngrams(na, 3);
+	const gb = ngrams(nb, 3);
+	let inter = 0;
+	for (const x of ga) if (gb.has(x)) inter++;
+	const uni = ga.size + gb.size - inter;
+	return inter / uni;
+}
+
+function toolCallsSimilar(
+	c1: Array<{ name: string; args: string }>,
+	c2: Array<{ name: string; args: string }>,
+): boolean {
+	if (c1.length !== c2.length) return false;
+	if (!c1.length) return true;
+	for (let i = 0; i < c1.length; i++) {
+		if (c1[i].name !== c2[i].name) return false;
+		if (similarity(c1[i].args, c2[i].args) < 0.8) return false;
+	}
+	return true;
+}
+
+export function detectLoops(state: AntiloopState, config: AntiloopConfig): LoopDetection[] {
+	const out: LoopDetection[] = [];
+	const msgs = state.recentMessages;
+	if (msgs.length < 2) return out;
+	const start = Math.max(0, msgs.length - config.detectionWindow);
+	const win = msgs.slice(start);
+	const now = Date.now();
+
+	if (config.detectTextLoops) {
+		const last = win[win.length - 1];
+		if (last.content.length >= MIN_CONTENT_LENGTH) {
+			for (let i = 0; i < win.length - 1; i++) {
+				if (win[i].content.length < MIN_CONTENT_LENGTH) continue;
+				const s = similarity(last.content, win[i].content);
+				if (s >= config.similarityThreshold) {
+					out.push({
+						type: "text",
+						similarity: s,
+						messageIndices: [start + i, msgs.length - 1],
+						description: `text similarity ${(s * 100).toFixed(0)}% with msg ${start + i + 1}`,
+						timestamp: now,
+					});
+				}
+			}
+		}
+		if (win.length >= 3) {
+			const opens = win.map((m, idx) => ({ o: opening(m.content), idx }))
+				.filter((x) => x.o.length >= 20);
+			if (opens.length >= 3) {
+				const last = opens[opens.length - 1].o;
+				let n = 0;
+				for (let i = 0; i < opens.length - 1; i++) {
+					if (similarity(last, opens[i].o) > 0.8) n++;
+				}
+				if (n >= 2) {
+					out.push({
+						type: "structural",
+						similarity: 0.9,
+						messageIndices: [msgs.length - 1],
+						description: `repeated opening (${n + 1} similar starts)`,
+						timestamp: now,
+					});
+				}
+			}
+		}
+	}
+
+	if (config.detectToolLoops) {
+		const last = win[win.length - 1];
+		const lastCalls = last.toolCalls;
+		if (lastCalls && lastCalls.length) {
+			for (let i = 0; i < win.length - 1; i++) {
+				const prev = win[i].toolCalls;
+				if (prev && toolCallsSimilar(lastCalls, prev)) {
+					out.push({
+						type: "tool",
+						similarity: 1,
+						messageIndices: [start + i, msgs.length - 1],
+						description: `repeated: ${lastCalls.map((t) => t.name).join(", ")}`,
+						timestamp: now,
+					});
+				}
+			}
+		}
+	}
+
+	if (config.detectThinkingLoops) {
+		const last = win[win.length - 1];
+		if (last.thinking && last.thinking.length > 50) {
+			for (let i = 0; i < win.length - 1; i++) {
+				if (win[i].thinking && win[i].thinking!.length > 50) {
+					const s = similarity(last.thinking, win[i].thinking!);
+					if (s >= config.similarityThreshold) {
+						out.push({
+							type: "thinking",
+							similarity: s,
+							messageIndices: [start + i, msgs.length - 1],
+							description: `thinking similarity ${(s * 100).toFixed(0)}%`,
+							timestamp: now,
+						});
+					}
+				}
+			}
+		}
+	}
+
+	return out;
+}
+
+export function interventionMessage(level: 1 | 2 | 3, detections: LoopDetection[]): string {
+	const det = detections.map((d) => `- ${d.description}`).join("\n");
+	if (level === 1) {
+		return `[antiloop] ⚠️ loop warning\n${det}\nvary approach — try a different strategy.`;
+	}
+	if (level === 2) {
+		return `[antiloop] 🛑 stuck in loop\n${det}\nstop, change approach, do NOT repeat previous tool calls or reasoning.`;
+	}
+	return `[antiloop] 🚨 persistent loop\n${det}\nunable to break automatically — provide new instructions.`;
+}