pi-anti-doom-loop 0.0.1 → 0.0.2

package/README.md

@@ -60,11 +60,19 @@ Requires Node 22.6+ (plain `node` runs the TS self-check).
 
 ```bash
 npm install
-npm test        # detector self-check (pure Node, no deps)
+npm test        # node --test: unit + fixture + fuzz + integration + e2e
 npm run check   # npm test + tsc + oxlint --deny-warnings + oxfmt
 ```
 
-Runtime deps: `better-result` (detector decisions) and `effect` v4 (the release guard).
+### Test suite (Node built-in runner, no framework)
+
+| Suite       | File                                          | What it proves                                                                                                    |
+| ----------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| unit        | `tests/unit.test.ts`                          | detector semantics: repeat/failure/text signals, window eviction, options clamping, helpers                       |
+| fixture     | `tests/fixtures.ts` + `tests/fixture.test.ts` | real doom-loop transcripts (CI-log loops, verbatim repeats) are caught; healthy sessions are not                  |
+| fuzz        | `tests/fuzz.test.ts`                          | seeded random streams: never throws, no false positives, injected loops always block, canonical stability         |
+| integration | `tests/integration.test.ts`                   | controller + `index.ts` adapter driven through a fake `PiLike`: blocks, escalations, aborts, resets, `/loopcheck` |
+| e2e         | `tests/e2e.test.ts`                           | real subprocesses: detector self-check, version guard, tarball contents (extensions/scripts ship, tests don't)    |
 
 > `peerDependencies` pins `@earendil-works/pi-coding-agent` at `"*"` on purpose — the
 > [pi packages docs](https://pi.dev/docs/latest/packages) require an unbounded range for

package/extensions/controller.ts

@@ -0,0 +1,116 @@
+/**
+ * Controller — the extension's event logic as a pure, pi-free module.
+ *
+ * `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).
+ */
+import { LoopDetector, readOptions } from "./detector.ts";
+import type { LoopOptions } from "./detector.ts";
+
+/** Minimal shapes of the pi events the controller consumes (structural). */
+export interface ToolCallEventLite {
+  toolName: string;
+  toolCallId: string;
+  input: unknown;
+}
+export interface ToolResultEventLite {
+  toolName: string;
+  toolCallId: string;
+  isError: boolean;
+}
+export interface MessageEndEventLite {
+  message: { role: string; content?: unknown };
+}
+export interface CtxLite {
+  ui: { notify(message: string, level: string): void };
+  abort(): void;
+}
+export interface CommandCtxLite {
+  ui: { notify(message: string, level: string): void };
+}
+
+export interface ToolCallOutcome {
+  block: true;
+  reason: string;
+  /** True when this exact call was blocked before — caller should abort the turn. */
+  escalate: boolean;
+}
+
+export interface TextLoopOutcome {
+  reason: string;
+}
+
+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. */
+  onMessageEnd(role: string, content: unknown): TextLoopOutcome | null;
+  /** Full reset (session start, user prompt, /loopcheck reset). */
+  reset(): void;
+  /** Human-readable status with thresholds + counters for /loopcheck. */
+  status(): string;
+}
+
+export function createController(opts: LoopOptions = readOptions()): AntiLoopController {
+  let detector = new LoopDetector(opts);
+  const blockedIds = new Set<string>();
+
+  return {
+    onToolCall(toolName, input, toolCallId) {
+      const decision = detector.check(toolName, input);
+      if (decision.isErr()) {
+        detector.record(toolName, input);
+        return null;
+      }
+      blockedIds.add(toolCallId);
+      const block = decision.value;
+      return { block: true, reason: block.reason, escalate: block.escalate };
+    },
+
+    onToolResult(toolName, toolCallId, isError) {
+      // Blocked calls never ran, so their (error) result must not count as a
+      // consecutive failure.
+      if (blockedIds.has(toolCallId)) {
+        blockedIds.delete(toolCallId);
+        return;
+      }
+      detector.recordResult(toolName, isError);
+    },
+
+    onMessageEnd(role, content) {
+      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;
+    },
+
+    reset() {
+      detector = new LoopDetector(opts);
+      blockedIds.clear();
+    },
+
+    status() {
+      const o = detector.opts;
+      return (
+        `anti-doom-loop: repeats>=${o.repeatThreshold}/window ${o.windowSize}, ` +
+        `fails>=${o.failThreshold}, text>=${o.textRepeatThreshold}. ${detector.summary()}`
+      );
+    },
+  };
+}
+
+/** Join the text content blocks of an assistant message. */
+export function extractText(content: unknown): string {
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((c) =>
+      typeof c === "object" && c !== null && c.type === "text" && typeof c.text === "string"
+        ? c.text
+        : "",
+    )
+    .join(" ");
+}

package/extensions/index.ts

@@ -9,90 +9,88 @@
  *    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
  *
  * Blocking hands control back to the model once. If the model re-issues the
  * exact same blocked call, the turn is aborted (escalation).
  *
  * 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.
+ *
+ * All logic lives in `controller.ts` (pure, pi-free, unit-tested); this file
+ * is a thin adapter wiring it to pi's event loop. The pi API is consumed
+ * structurally so the wiring stays testable and import-light.
  */
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { LoopDetector, readOptions } from "./detector";
+import {
+  createController,
+  type AntiLoopController,
+  type CommandCtxLite,
+  type CtxLite,
+  type MessageEndEventLite,
+  type ToolCallEventLite,
+  type ToolResultEventLite,
+} from "./controller.ts";
+import { readOptions } from "./detector.ts";
 
-export default function (pi: ExtensionAPI): void {
+/** The subset of pi's ExtensionAPI this extension uses (structural). */
+export interface PiLike {
+  on<E = unknown, C = unknown>(event: string, handler: (event: E, ctx: C) => unknown): void;
+  registerCommand(
+    name: string,
+    opts: {
+      description?: string;
+      handler: (args: string, ctx: CommandCtxLite) => Promise<void> | void;
+    },
+  ): void;
+}
+
+export default function (pi: PiLike): void {
   if (process.env.PI_ANTI_LOOP_DISABLE === "1") return;
 
-  let detector = new LoopDetector(readOptions());
-  let configTxt = settingsTxt(detector);
-  const blockedIds = new Set<string>();
+  let controller: AntiLoopController = createController(readOptions());
 
   pi.on("session_start", () => reset());
 
   // Fresh counters per user prompt: only the loop happening *right now* counts.
   pi.on("before_agent_start", () => reset());
 
-  pi.on("tool_call", (event, ctx) => {
-    const decision = detector.check(event.toolName, event.input);
-    if (decision.isErr()) {
-      detector.record(event.toolName, event.input);
-      return;
-    }
-    const block = decision.value;
-    blockedIds.add(event.toolCallId);
-    if (block.escalate) {
+  pi.on("tool_call", (event: ToolCallEventLite, ctx: CtxLite) => {
+    const outcome = controller.onToolCall(event.toolName, event.input, event.toolCallId);
+    if (outcome === null) return;
+    if (outcome.escalate) {
       ctx.ui.notify("Anti-doom-loop: identical call blocked again — aborting turn", "error");
       ctx.abort();
     }
-    return { block: true, reason: block.reason };
+    return { block: true, reason: outcome.reason };
   });
 
-  // Blocked calls never ran, so their (error) result must not count as a failure.
-  pi.on("tool_result", (event) => {
-    if (blockedIds.has(event.toolCallId)) {
-      blockedIds.delete(event.toolCallId);
-      return;
-    }
-    detector.recordResult(event.toolName, event.isError === true);
+  pi.on("tool_result", (event: ToolResultEventLite) => {
+    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.
-  pi.on("message_end", (event, ctx) => {
-    const message = event.message;
-    if (message.role !== "assistant") return;
-    const content = Array.isArray(message.content) ? message.content : [];
-    const text = content
-      .filter((c): c is { type: "text"; text: string } => c.type === "text")
-      .map((c) => c.text)
-      .join(" ");
-    if (!text) return;
-    const hit = detector.checkText(text);
-    if (hit.isOk()) {
-      ctx.ui.notify(`Anti-doom-loop: ${hit.value.reason}`, "error");
-      ctx.abort();
-    }
+  pi.on("message_end", (event: MessageEndEventLite, ctx: CtxLite) => {
+    const outcome = controller.onMessageEnd(event.message.role, event.message.content);
+    if (outcome === null) return;
+    ctx.ui.notify(`Anti-doom-loop: ${outcome.reason}`, "error");
+    ctx.abort();
   });
 
   pi.registerCommand("loopcheck", {
     description: "Anti-doom-loop status; `/loopcheck reset` clears counters",
-    handler: async (args, ctx) => {
+    handler: async (args: string, ctx: CommandCtxLite) => {
       if (args.trim().toLowerCase() === "reset") {
         reset();
         ctx.ui.notify("Anti-doom-loop: counters reset", "info");
         return;
       }
-      ctx.ui.notify(`${configTxt}. ${detector.summary()}`, "info");
+      ctx.ui.notify(controller.status(), "info");
     },
   });
 
   function reset(): void {
-    detector = new LoopDetector(readOptions());
-    configTxt = settingsTxt(detector);
-    blockedIds.clear();
+    controller = createController(readOptions());
   }
 }
-
-function settingsTxt(d: LoopDetector): string {
-  const o = d.opts;
-  return `anti-doom-loop: repeats>=${o.repeatThreshold}/window ${o.windowSize}, fails>=${o.failThreshold}`;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anti-doom-loop",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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",
@@ -31,7 +31,7 @@
   "scripts": {
     "check": "npm run test && tsc --noEmit && oxlint --deny-warnings && oxfmt --check .",
     "prepublishOnly": "npm run check",
-    "test": "node extensions/detector.ts",
+    "test": "node --test tests/*.test.ts",
     "guard": "node scripts/guard-publish.ts",
     "lint": "oxlint --deny-warnings",
     "format": "oxfmt .",