pi-anti-doom-loop 0.0.3 → 0.0.4

package/README.md

@@ -21,13 +21,19 @@ pi install npm:pi-anti-doom-loop
 | Same tool failing consecutively  | 3×                      | A tool errored `3` times in a row — stop retrying it blindly                             |
 | Same assistant text verbatim     | 3× in a row             | The model re-emitted identical text `3` times (text-only loops)                          |
 | Same sentence inside ONE message | 3×                      | A sentence repeats `3`+ times within a single message (growing self-concatenation loops) |
+| Near-identical text (rephrasing) | 3× in a row             | Consecutive messages share ≥55% tokens — the model is rephrasing the same step           |
 
 Blocks hand the model an instructive reason ("change your approach, use a
 different tool, or ask the user"). If the model ignores the block and re-issues
-the exact same call, the turn is **aborted** and you are notified. Verbatim
-text loops and within-message self-repetition (no tool calls involved) abort
-the run immediately with a notification.
+the exact same call, the turn is **aborted**.
 
+### Escalation (text loops): steer → abort → bounded resume
+
+The first text-loop detection **steers** the agent mid-run (injects guidance,
+lets it continue). If it persists, the run is **aborted** and **one** fresh-
+resume directive is queued so work continues with a new approach. If it still
+loops after that, the run aborts for real and control returns to you — the
+auto-resume budget is capped so a truly stuck model can't cycle forever.
 Counters reset on every user prompt, so a task legitimately repeated later in
 the same session is never a false positive.
 

package/extensions/controller.ts

@@ -4,6 +4,13 @@
  * `index.ts` is a thin adapter that wires these methods to pi's event loop;
  * tests drive this controller directly with plain objects. Same behavior,
  * no pi dependency (only `better-result` via the detector).
+ *
+ * Escalation ladder for message loops:
+ *   detection #1 → steer  (inject guidance, let the agent continue)
+ *   detection #2 → abort + resume (stop the run, queue one fresh directive)
+ *   detection #3+ → abort for real (hand back to the user)
+ * The resume budget is session-scoped: `reset()` (per user prompt) keeps it,
+ * a fresh session (new controller) starts over.
  */
 import { LoopDetector, readOptions } from "./detector.ts";
 import type { LoopOptions } from "./detector.ts";
@@ -39,14 +46,20 @@ export interface ToolCallOutcome {
 
 export interface TextLoopOutcome {
   reason: string;
+  action: "steer" | "abort";
+  /** When aborting: also queue a single fresh-resume directive (bounded). */
+  resume: boolean;
 }
 
+/** How many auto-resumes per session before we hand control back for real. */
+export const RESUME_BUDGET = 1;
+
 export interface AntiLoopController {
   /** Returns a block decision for a tool call, or null to let it run. */
   onToolCall(toolName: string, input: unknown, toolCallId: string): ToolCallOutcome | null;
   /** Record a finished tool result (blocked calls' results are ignored). */
   onToolResult(toolName: string, toolCallId: string, isError: boolean): void;
-  /** Detect verbatim assistant-text loops; returns an abort reason or null. */
+  /** Detect assistant-text loops; returns a steer/abort decision or null. */
   onMessageEnd(role: string, content: unknown): TextLoopOutcome | null;
   /** Full reset (session start, user prompt, /loopcheck reset). */
   reset(): void;
@@ -57,6 +70,8 @@ export interface AntiLoopController {
 export function createController(opts: LoopOptions = readOptions()): AntiLoopController {
   let detector = new LoopDetector(opts);
   const blockedIds = new Set<string>();
+  let steered = false;
+  let resumes = 0;
 
   return {
     onToolCall(toolName, input, toolCallId) {
@@ -85,12 +100,26 @@ export function createController(opts: LoopOptions = readOptions()): AntiLoopCon
       const text = extractText(content);
       if (!text) return null;
       const hit = detector.checkText(text);
-      return hit.isOk() ? { reason: hit.value.reason } : null;
+      if (!hit.isOk()) return null;
+
+      const reason = hit.value.reason;
+      if (!steered) {
+        steered = true;
+        return { reason, action: "steer", resume: false };
+      }
+      if (resumes < RESUME_BUDGET) {
+        resumes++;
+        return { reason, action: "abort", resume: true };
+      }
+      return { reason, action: "abort", resume: false };
     },
 
     reset() {
       detector = new LoopDetector(opts);
       blockedIds.clear();
+      steered = false;
+      // resumes is intentionally NOT reset here: the auto-resume budget is
+      // session-scoped so a stuck model cannot cycle steer→abort forever.
     },
 
     status() {

package/extensions/detector.ts

@@ -147,26 +147,29 @@ export class LoopDetector {
     // `textRepeatThreshold`+ times inside ONE message (growing loops like
     // "…X:…X:…X"). Liquid.ai's loop definition — a section repeats at least N
     // times. No streak needed: the message itself is the loop.
-    if (!this.textFired) {
-      const chunk = repeatedSegment(norm, this.opts.textRepeatThreshold);
-      if (chunk !== null) {
-        this.textFired = true;
-        return Result.ok({
-          reason:
-            `Assistant message repeats "${truncate(chunk, 60)}" ${this.opts.textRepeatThreshold}+ times ` +
-            `within a single message. You appear to be in a loop — this run is aborted.`,
-        });
-      }
+    const chunk = repeatedSegment(norm, this.opts.textRepeatThreshold);
+    if (chunk !== null) {
+      return Result.ok({
+        reason:
+          `Assistant message repeats "${truncate(chunk, 60)}" ${this.opts.textRepeatThreshold}+ times ` +
+          `within a single message. You appear to be in a loop.`,
+      });
     }
 
-    this.textStreak = norm === this.lastText ? this.textStreak + 1 : 1;
+    // Cross-message streak: consecutive assistant texts that are identical
+    // OR near-identical (token-overlap similarity). Catches loops where the
+    // model slightly rephrases each turn ("inspect the failing test" →
+    // "examine the failing assertion") so exact matching never fires.
+    const similar =
+      norm === this.lastText ||
+      (this.lastText !== null && tokenSimilarity(norm, this.lastText) >= TEXT_SIMILARITY_THRESHOLD);
+    this.textStreak = similar ? this.textStreak + 1 : 1;
     this.lastText = norm;
-    if (this.textStreak >= this.opts.textRepeatThreshold && !this.textFired) {
-      this.textFired = true;
+    if (this.textStreak >= this.opts.textRepeatThreshold) {
       return Result.ok({
         reason:
-          `Assistant replied with identical text ${this.textStreak} times in a row ("${truncate(norm, 80)}"). ` +
-          `You appear to be in a loop — this run is aborted.`,
+          `Assistant replied with identical or near-identical text ${this.textStreak} times in a row ` +
+          `("${truncate(norm, 80)}"). You appear to be in a loop.`,
       });
     }
     return Result.err(undefined);
@@ -212,6 +215,31 @@ export function truncate(text: string, max: number): string {
 /** Minimum length of a segment worth treating as a repeated loop chunk. */
 export const MIN_REPEAT_CHUNK = 16;
 
+/** Jaccard similarity threshold for "near-identical" consecutive texts. */
+export const TEXT_SIMILARITY_THRESHOLD = 0.55;
+
+/**
+ * Token-set Jaccard similarity of two texts (case/whitespace-insensitive).
+ * Short tokens (< 3 chars: "a", "me", "to") are ignored to reduce noise.
+ * Returns 0..1; 1 = identical token sets.
+ */
+export function tokenSimilarity(a: string, b: string): number {
+  const tokenize = (s: string) => {
+    return new Set(
+      normalizeText(s)
+        .toLowerCase()
+        .split(/\s+/g)
+        .filter((w) => w.length >= 3 && /^[a-z0-9_-]+$/.test(w)),
+    );
+  };
+  const as = tokenize(a);
+  const bs = tokenize(b);
+  if (as.size === 0 || bs.size === 0) return 0;
+  let inter = 0;
+  for (const t of as) if (bs.has(t)) inter++;
+  return inter / (as.size + bs.size - inter);
+}
+
 /**
  * Returns the first sentence-ish segment that repeats `threshold` times
  * within a single normalized message, or null.
@@ -294,18 +322,22 @@ if (import.meta.main) {
   for (let i = 0; i < opts.windowSize; i++) d.record("bash", { command: `cmd ${i}` });
   assert.ok(d.check("bash", { command: "cmd 0" }).isErr(), "evicted repeats do not count");
 
-  // 7. verbatim assistant text loop: fires once at the 3rd identical message
+  // 7. verbatim assistant text loop: fires at the 3rd identical message and
+  //    every message after while the streak holds (controller escalates)
   d.reset();
   assert.ok(d.checkText("Now update buildProgram.").isErr(), "1st text passes");
   assert.ok(d.checkText("Now update buildProgram.").isErr(), "2nd text passes");
   const textHit = d.checkText("Now update buildProgram.");
   assert.ok(textHit.isOk(), "3rd identical text should fire");
   if (textHit.isOk()) {
-    assert.match(textHit.value.reason, /identical text 3 times/);
-    assert.match(textHit.value.reason, /aborted/);
+    assert.match(textHit.value.reason, /identical or near-identical text 3 times/);
   }
-  assert.ok(d.checkText("Now update buildProgram.").isErr(), "fires only once per run");
-
+  assert.ok(
+    d.checkText("Now update buildProgram.").isOk(),
+    "4th identical text still fires (escalation)",
+  );
+  d.reset();
+  assert.ok(d.checkText("Now update buildProgram.").isErr(), "reset clears the streak");
   // 8. whitespace drift does not hide a verbatim loop
   d.reset();
   d.checkText("Read the region:");

package/extensions/index.ts

@@ -9,11 +9,15 @@
  *    in the last `PI_ANTI_LOOP_WINDOW` calls → block with an instructive reason
  *  - the same tool failing `PI_ANTI_LOOP_FAILS` consecutive times (default 3)
  *    → block with a "stop retrying, fix the root cause" reason
- *  - the model re-emitting the same assistant text verbatim
- *    `PI_ANTI_LOOP_TEXT_REPEATS` times (default 3) → abort the run
+ *  - the model repeating text: verbatim, near-identical (token similarity),
+ *    or a sentence repeated inside ONE message → steer first, abort as
+ *    escalation, then a bounded auto-resume so work continues
  *
- * Blocking hands control back to the model once. If the model re-issues the
- * exact same blocked call, the turn is aborted (escalation).
+ * Escalation (message loops): detection #1 steers the agent mid-run; #2
+ * aborts the turn and queues one fresh-resume directive; #3+ aborts for real
+ * and hands control back to the user. Tool-call blocks hand the model an
+ * instructive reason (that is the steer); re-issuing the exact same blocked
+ * call aborts the turn.
  *
  * Counters reset on every user prompt, so a task legitimately repeated later
  * in the session is never a false positive. Disable with PI_ANTI_LOOP_DISABLE=1.
@@ -43,8 +47,24 @@ export interface PiLike {
       handler: (args: string, ctx: CommandCtxLite) => Promise<void> | void;
     },
   ): void;
+  sendMessage?(
+    content: { customType?: string; content?: string; display?: boolean },
+    options?: { deliverAs?: "steer" | "followUp" | "nextTurn"; triggerTurn?: boolean },
+  ): void;
 }
 
+/** Injected on the first loop detection — steer the agent back on track. */
+const STEER_TEXT =
+  "Anti-doom-loop steering: you are repeating the same action or text without making progress. " +
+  "Stop. Re-read the actual error output, pick ONE different action, and execute it. " +
+  "If you are stuck, ask the user instead of retrying.";
+
+/** Queued once after an abort so the work can continue with a fresh approach. */
+const RESUME_TEXT =
+  "Anti-doom-loop: the previous run was aborted because it looped. " +
+  "Start over with a genuinely different approach: do not repeat the previous investigation steps. " +
+  "Re-read the task, choose one new action, execute it, then report results.";
+
 export default function (pi: PiLike): void {
   if (process.env.PI_ANTI_LOOP_DISABLE === "1") return;
 
@@ -69,13 +89,30 @@ export default function (pi: PiLike): void {
     controller.onToolResult(event.toolName, event.toolCallId, event.isError === true);
   });
 
-  // Text-only doom loops (model re-emits the same sentence with no tool calls)
-  // never reach tool_call. Detect verbatim assistant repeats and abort the run.
+  // Text-only doom loops (model re-emits/rephrases the same thing with no
+  // tool calls) never reach tool_call. Steer first, abort as escalation,
+  // then a bounded auto-resume so the work continues.
   pi.on("message_end", (event: MessageEndEventLite, ctx: CtxLite) => {
     const outcome = controller.onMessageEnd(event.message.role, event.message.content);
     if (outcome === null) return;
+
+    if (outcome.action === "steer") {
+      ctx.ui.notify(`Anti-doom-loop: ${outcome.reason}`, "warning");
+      pi.sendMessage?.(
+        { customType: "anti-doom-loop", content: STEER_TEXT, display: true },
+        { deliverAs: "steer", triggerTurn: true },
+      );
+      return;
+    }
+
     ctx.ui.notify(`Anti-doom-loop: ${outcome.reason}`, "error");
     ctx.abort();
+    if (outcome.resume) {
+      pi.sendMessage?.(
+        { customType: "anti-doom-loop", content: RESUME_TEXT, display: true },
+        { deliverAs: "followUp", triggerTurn: true },
+      );
+    }
   });
 
   pi.registerCommand("loopcheck", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anti-doom-loop",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Detect and break agent doom loops in pi: blocks identical repeated tool calls and blind retries before they burn tokens.",
   "keywords": [
     "anti-doom-loop",