pi-anti-doom-loop 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to **pi-anti-doom-loop**.
+
+## [0.0.5] — 2026-08-05
+
+### Added
+
+- **`/loopcheck suspend` / `resume`** — escape hatch: pause detection until the next prompt when repetition is intentional (polling, retrying a deploy). No env restart needed.
+- **Session counters** — `steers`/`aborts` appear in `/loopcheck` status; session-scoped (survive per-prompt resets, reset on `/loopcheck reset` or new session).
+- Fixture for the live regex-repeat capture (`parameter\s+(\S+)\s+("` 3× in one message) — regression-covered via the within-message signal.
+- `CHANGELOG.md` ships in the tarball.
+
+### Tests
+
+- 72 → 75: suspend/resume lifecycle, session counters, regex-repeat fixture, `/loopcheck` subcommands.
+
+## [0.0.4] — 2026-08-05
+
+### Added
+
+- **Near-identical text detection** — token-set Jaccard similarity ≥ 0.55 on consecutive assistant messages counts as a loop streak. Catches rephrasing loops where the model changes one or two words per turn ("inspect the failing test" → "examine the failing assertion") that exact matching missed.
+- **Escalation ladder for text loops: steer → abort → bounded resume** — the first detection steers the agent mid-run (injects guidance, work continues); a persistent loop aborts the run and queues **one** fresh-resume directive (`followUp`) so work continues with a new approach; further looping aborts for real and hands control back. The auto-resume budget is session-scoped so a stuck model cannot cycle forever.
+- Detector now fires on every message while a loop condition holds; the controller turns the 1st into a steer, later ones into aborts.
+- Tests: 65 → 72 (token-similarity unit cases, near-identical streak + reset, steer→abort→resume ladder, budget persistence, adapter wiring, fuzz no-FP + injected-3× properties).
+
+## [0.0.3] — 2026-08-05
+
+### Added
+
+- **Within-message self-repetition detection** — a sentence repeating 3+ times inside ONE message (growing self-concatenation loops like "…X:…X:…X") now aborts/steers immediately. Liquid Antidoom's loop definition ("a section repeats at least N times").
+- Segmenter ignores chunks < 16 chars so pasted logs with repeated one-word lines never false-positive.
+- Fixtures for the production growing-loop capture (exact + spaced variants).
+
+### Fixed
+
+- Production gap: loops that grow by self-concatenation evaded both verbatim-streak (messages differ) and identical-call (args vary) detection. Now caught at the message itself.
+
+### Tests
+
+- 51 → 65: `repeatedSegment` unit cases, growing-pattern `checkText` cases, fixture controller paths, fuzz no-FP + injected-3× properties.
+
+## [0.0.2] — 2026-08-05
+
+### Added
+
+- **Full test suite** — Node's built-in `node:test`, no framework:
+  - unit (detector semantics, options clamping, helpers)
+  - fixtures (real doom-loop transcripts: CI-log loops, verbatim repeats; healthy sessions not flagged)
+  - fuzz (seeded: never throws, no false positives, injected loops always block)
+  - integration (controller + adapter driven through a fake `PiLike`)
+  - e2e (real subprocesses: detector self-check, version guard, tarball contents)
+- **`controller.ts`** — extracted all event logic into a pure, pi-free, testable module; `index.ts` became a thin structural adapter.
+- `npm test`, `engines >= 22.18`, `files` includes `scripts/`.
+
+### Fixed
+
+- Thresholds clamped to a minimum of 2 (a config of 1 would brick the agent — deepsec finding).
+- GitHub Actions pinned to commit SHAs (NPM_TOKEN in scope — deepsec finding).
+- Release job `concurrency` group (publish race / TOCTOU).
+- `npm publish --dry-run` preflight before the real publish.
+- Version guard requires the git tag `v$version` on the manual-dispatch path.
+
+### Changed
+
+- Leveraged `better-result` (detector decisions) and `effect` v4 (release guard).
+
+## [0.0.1] — 2026-08-05
+
+### Added
+
+- Initial release. Detects and breaks agent doom loops in pi:
+  - **identical (tool, args) repeated** 3× in the last 10 calls → block with an instructive reason
+  - **same tool failing** 3× consecutively → block with "stop retrying, fix the root cause"
+  - escalation: re-issuing a blocked call aborts the turn
+- `/loopcheck` command (status + reset).
+- Counters reset per user prompt (legit repeated tasks are never false positives).
+- GitHub Actions release workflow: quality gate → version bump guard → dry-run → publish, triggered by `v*` tags.
+- `pi-package` keyword + `pi` manifest for the pi.dev gallery.
+
+[0.0.5]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.3...v0.0.4
+[0.0.2]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/irfndi/pi-anti-doom-loop/releases/tag/v0.0.1

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.
 
@@ -45,15 +51,17 @@ Environment variables, read at session/prompt start:
 
 ## Command
 
-- `/loopcheck` — show current thresholds and counters
+- `/loopcheck` — show thresholds, counters (steers/aborts this session), suspend state
 - `/loopcheck reset` — clear counters
+- `/loopcheck suspend` — pause detection until the next prompt (escape hatch for intentional repetition)
+- `/loopcheck resume` — re-enable detection early
 
 ## How it works
 
-Everything hooks into the `tool_call` / `tool_result` events; detection is a
-small sliding-window counter (see `extensions/detector.ts`) with no state kept
-between user prompts. Works with any model — cheap models just trigger it more
-often.
+Everything hooks into the `tool_call` / `tool_result` / `message_end` events;
+detection is a small sliding-window counter (see `extensions/detector.ts`) with
+per-session counters (steers/aborts) tracked in `extensions/controller.ts`.
+Works with any model — cheap models just trigger it more often.
 
 ## Development
 

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,17 +46,27 @@ 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;
+  /** Suspend detection until the next reset (escape hatch for intentional repetition). */
+  suspend(): void;
+  resume(): void;
+  isSuspended(): boolean;
   /** Human-readable status with thresholds + counters for /loopcheck. */
   status(): string;
 }
@@ -57,9 +74,15 @@ 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;
+  let steers = 0;
+  let aborts = 0;
+  let suspended = false;
 
   return {
     onToolCall(toolName, input, toolCallId) {
+      if (suspended) return null;
       const decision = detector.check(toolName, input);
       if (decision.isErr()) {
         detector.record(toolName, input);
@@ -81,23 +104,57 @@ export function createController(opts: LoopOptions = readOptions()): AntiLoopCon
     },
 
     onMessageEnd(role, content) {
+      if (suspended) return null;
       if (role !== "assistant") return null;
       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;
+        steers++;
+        return { reason, action: "steer", resume: false };
+      }
+      if (resumes < RESUME_BUDGET) {
+        resumes++;
+        aborts++;
+        return { reason, action: "abort", resume: true };
+      }
+      aborts++;
+      return { reason, action: "abort", resume: false };
     },
 
     reset() {
       detector = new LoopDetector(opts);
       blockedIds.clear();
+      steered = false;
+      suspended = false;
+      // resumes/steers/aborts are intentionally NOT reset here: they are
+      // session-scoped so a stuck model cannot cycle steer→abort forever and
+      // /loopcheck can report lifetime counters.
+    },
+
+    suspend() {
+      suspended = true;
+    },
+
+    resume() {
+      suspended = false;
+    },
+
+    isSuspended() {
+      return suspended;
     },
 
     status() {
       const o = detector.opts;
+      const s = suspended ? ", suspended" : "";
       return (
         `anti-doom-loop: repeats>=${o.repeatThreshold}/window ${o.windowSize}, ` +
-        `fails>=${o.failThreshold}, text>=${o.textRepeatThreshold}. ${detector.summary()}`
+        `fails>=${o.failThreshold}, text>=${o.textRepeatThreshold}. ${detector.summary()} ` +
+        `steers=${steers} aborts=${aborts}${s}`
       );
     },
   };

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;
 
@@ -53,7 +73,8 @@ export default function (pi: PiLike): void {
   pi.on("session_start", () => reset());
 
   // Fresh counters per user prompt: only the loop happening *right now* counts.
-  pi.on("before_agent_start", () => reset());
+  // Internal reset keeps session-scoped steers/aborts/resume budget.
+  pi.on("before_agent_start", () => controller.reset());
 
   pi.on("tool_call", (event: ToolCallEventLite, ctx: CtxLite) => {
     const outcome = controller.onToolCall(event.toolName, event.input, event.toolCallId);
@@ -69,23 +90,51 @@ 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", {
     description: "Anti-doom-loop status; `/loopcheck reset` clears counters",
     handler: async (args: string, ctx: CommandCtxLite) => {
-      if (args.trim().toLowerCase() === "reset") {
+      const arg = args.trim().toLowerCase();
+      if (arg === "reset") {
         reset();
         ctx.ui.notify("Anti-doom-loop: counters reset", "info");
         return;
       }
+      if (arg === "suspend") {
+        controller.suspend();
+        ctx.ui.notify("Anti-doom-loop: suspended until the next prompt", "info");
+        return;
+      }
+      if (arg === "resume") {
+        controller.resume();
+        ctx.ui.notify("Anti-doom-loop: resumed", "info");
+        return;
+      }
       ctx.ui.notify(controller.status(), "info");
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anti-doom-loop",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "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",
@@ -17,7 +17,8 @@
   },
   "files": [
     "extensions",
-    "scripts"
+    "scripts",
+    "CHANGELOG.md"
   ],
   "type": "module",
   "main": "extensions/index.ts",